The mental model
A custom node is an editor package, not a separate service or secret execution environment. Its inner graph contains the same actions, decisions, data connections, and variables available in the surrounding workflow. At validation and execution time, BotFrame expands that graph into the surrounding workflow.
Custom nodes cannot contain triggers. Execution enters through an input boundary and leaves through an output boundary, preserving the same execution scope as one continuous graph.
Create one
- Add Custom node from LogicDrag it from the node library or use quick add.
- Open the inner graphDouble-click the node. Use the breadcrumb to return to the outer workflow.
- Build the behaviorConnect ordinary nodes between the input and output boundaries. Do not add a trigger.
- Name the packageWith no inner node selected, use the inspector to edit the custom node’s name and description.
Define inputs and outputs
Select the input or output boundary node inside the custom node. The inspector lets you add, rename, choose a data type for, and remove the ports shown on the outer node.
| Boundary | Port | Purpose |
|---|---|---|
| Input | Flow input | Starts an inner execution path from the surrounding graph. |
| Input | Value input | Supplies a value of the selected data type to nodes inside the package. |
| Output | Flow output | Returns execution to a named path on the surrounding graph. |
| Output | Value output | Returns a result of the selected data type produced inside the package. |
Expose only the values and outcomes the caller needs. Internal connections remain visible when the custom node is opened, but do not clutter the outer graph.
Choose variable scope deliberately
Variables created inside a custom node have two storage choices.
| Scope | Duplication | Use it for |
|---|---|---|
| Instance | Copied to a new independent variable for every duplicated or library-created instance. | Counters, temporary state, message IDs, and settings that belong to one package instance. |
| Project | Continues to reference the shared project variable. | State deliberately shared with the outer workflow or other custom nodes. |
Instance variables still appear in the project variable inspector when its internal-variable section is expanded. They are hidden by default to keep the main list readable.
Copies are independent
Duplicating a custom node copies its graph and remaps its instance variables. Editing either copy later changes only that instance. There is no template link, inheritance, or background update between copies.
Choose Add to library from inside a custom node to save a portable snapshot. Adding that library item to another workflow creates a new independent copy. Project-variable references remain project-scoped, so review or recreate those dependencies when moving the node to a different project.
Validation and permissions
- Every exposed boundary port must connect to a compatible inner value or flow path.
- Triggers are rejected inside custom nodes.
- Nested custom nodes remain inspectable and are expanded before validation and execution.
- Discord permissions are derived from the actions packaged inside the node.
- Deleting or renaming an exposed port can disconnect the corresponding outer edge; run validation after interface changes.
The outer graph is the concise view. Opening the node always reveals the complete behavior that will run.