🏗️ Construction System

Short Description

The Construction system provides a two-phase pipeline for instantiating and configuring events, ensuring deterministic variable initialization.

Long Description

In complex gameplay systems, you often need to configure an object's state before its logic begins to run. Gorgeous Events achieves this via the Construction Handle pattern. Instead of spawning an event and setting properties (which can lead to frame-delayed logic or initialization races), you create a handle, assign your data, and then trigger the build. This system is fully integrated with the Gorgeous Core Object Variable registry, allowing for type-safe data injection.

🚀 The Build Pipeline

1. Construction Handle

The UGorgeousConstructionHandle is a transient object that holds the intended state for a future event.

  • Queued: The handle is registered but the event doesn't exist yet.
  • Started: the UGorgeousEvent instance is spawned, and variables are transferred.

2. Assignment Mapper

The UGorgeousAssignmentMapper is a bridge used during the Started phase. It implements multiple IGorgeousVariableSetter interfaces, allowing it to "flush" variables from the handle into the event's registry.

📚 Usage Examples

  1. Use the Create Gorgeous Construction Handle node.
  2. Use Set Universal Variable (Handle) nodes to provide data (e.g., "TargetActor", "Amount").
  3. Call Start Construction.
  4. The handle will automatically instantiate the event and inject the data before OnEventStarted fires.

📝 API Reference

OnConstructionQueued

Triggered when the handle is placed in a queue for future processing. Useful for pooling or deferred narrative triggers.

OnConstructionStarted

Triggered when the event instance has been spawned and variable assignment is about to occur.

Parameter Name Type Description
Event UGorgeousEvent* The newly created event instance.

GetAssigmentMapper

Retrieves the mapper instance responsible for variable injection.

FlushAssignedVariables

(Mapper Only) Pushes all buffered variable assignments into the target event. This is usually called automatically by the handle.

Best Practices

  • Unique Identifiers: Use the UniqueEventIdentifier on the handle to track event instances in the InsightMatrix before they are even spawned.
  • Mapper Inheritance: Create custom AssignmentMapper subclasses if you need to perform complex data transformation or validation during the injection phase.
  • Single Use: Construction handles are invalidated after OnConstructionCleanup is called. Do not attempt to reuse a handle for multiple events.

Troubleshooting

  • Variables Not Initializing: Ensure your CorrespondingAssigmentMapper class is correctly set on the handle.
  • Construction Failed: Check the UniqueEventIdentifier. If the system detects a collision or an invalid outer, construction will be aborted.
  • Race Conditions: If your logic depends on variables being set, always use the Construction system instead of manual NewObject + property setting.