🌳 Flow Tree System

Short Description

The Flow Tree is a node-based authoring model for sequencing Gorgeous Events using behavior tree-like logic.

Long Description

While manual event triggering is powerful, complex narrative sequences or scripted encounters are often easier to manage visually. The Flow Tree system allows developers to arrange events into logical structures like Sequences, Selectors, and Loops. Unlike traditional behavior trees that tick every frame, the Gorgeous Flow Tree is event-driven; the interpreter only steps forward when an active event completes, making it highly scalable for massive open-world scripting.

🚀 Node Types

The EGorgeousFlowNodeType_E defines how children are executed:

Node Type Behavior
Sequence Runs children left-to-right. Succeeds only if all children succeed.
Selector Runs children left-to-right. Succeeds if any child succeeds (stops on first success).
If Evaluates a condition and branches to Then or Else.
While Repeats its body as long as a condition is met.
Repeat Runs its body a fixed number of times.
Event The leaf node. Instantiates and executes a specific UGorgeousEvent class.

🧠 Condition Evaluation

Nodes can be gated by FGorgeousFlowCondition entries. These conditions are checked before a node is allowed to execute.

  • Has Variable: Checks if a specific key exists in the runtime variable system.
  • Conditional Chooser: Uses a UGorgeousConditionalObjectChooser to perform complex branching logic.

🏗️ Interpreter Lifecycle

The FGorgeousFlowTreeInterpreter manages the execution stack.

sequenceDiagram
    participant R as Runner
    participant I as Interpreter
    participant E as Event Node
    
    R->>I: Start(Tree)
    I->>I: Step()
    I->>E: TriggerEvent()
    E-->>I: OnEventFinished()
    I->>I: Step()
    I->>R: NotifyComplete()

📝 Configuration

The interpreter can be configured with a FConfig struct to control safety and precision:

  • MaxLoopIterations: Prevents infinite loops in development.
  • MaxContinueTimeMs: Time-slices execution to prevent frame spikes during complex branch resolution.
  • MissingConditionVarPolicy: Defines whether missing variables should trigger a warning, a failure, or just be ignored.

Best Practices

  • Node Enabled State: Use the bEnabled flag to quickly toggle off branches during development without deleting nodes.
  • Diagnostic Logging: Pay attention to FGorgeousFlowDiagnostic output. The interpreter provides detailed information about why a node failed or why a condition was not met.
  • Payload Usage: Use the Payload property bag on Event nodes to provide "one-off" data that doesn't need to be in the global registry.

Troubleshooting

  • Tree Not Advancing: Ensure your UGorgeousEvent leaf nodes are calling Complete(). The interpreter is event-driven and will wait indefinitely for a "Finished" signal.
  • Infinite Loop Detected: Check your While or Repeat nodes. If the loop budget is exceeded, the interpreter will abort and emit an error diagnostic.
  • Variable Mismatch: Use the FGorgeousAssumedInput list to declare what variables the tree expects. This allows the editor to validate your connections before you press Play.