⏸️ Voiding & Dependencies

Short Description

The Voiding system provides automatic dependency management, allowing events to pause completion until all requirements are met.

Long Description

In complex gameplay sequences, an event may finish its logic but cannot "close" until other systems have finished theirs. For example, a quest event might finish its objective logic, but must wait for a "Quest Complete" UI animation to finish. Instead of using complex timers or tick checks, Gorgeous Events uses Voiding Contexts. When an event attempts to finish, the system checks for active blockers. If any exist, the event enters the Voided state and automatically completes when the blockers resolve.

🚀 Blocker Types

The system provides several built-in UGorgeousEventVoidingContext types:

  • 🔐 Lock Context: Prevents completion as long as a specific FGameplayTag is present (e.g., Lock.UI.Animation).
  • ❄️ Freeze Context: Prevents completion while the event is explicitly "Frozen" by the developer.
  • 🔗 Sub-Event Context: Prevents the parent event from finishing until all registered child events have finished.
  • 🌳 Class Space Context: Prevents completion if a unique execution constraint in the class space is violated.

🏗️ Technical Flow

graph TD
    Trigger[Complete() Called] --> Check{Blockers Active?}
    Check -- No --> Finish[State: Finished]
    Check -- Yes --> Void[State: Voided]
    Void --> Monitor[Voiding Context Monitoring]
    Monitor --> Resolve{All Resolved?}
    Resolve -- Yes --> Finish

📝 API Reference

InvalidateVoiding

Manually triggers a re-evaluation of the voiding state. Used when external logic knows a dependency has changed.

Parameter Name Type Description
bRegisterAgain bool If true, the context will stay active after evaluation.

CheckVoidingNeed

The core logic of a voiding context. Override this in Blueprint to create custom completion requirements.

Best Practices

  • Avoid Infinite Voiding: Ensure every VoidingContext has a clear resolution path. For example, a "Lock" context must have a corresponding "Unlock" logic path.
  • UI Synchronization: Use voiding to keep narrative events alive until the player has dismissed all relevant dialogue boxes.
  • Sub-Event Transparency: Remember that UGorgeousEventWithSubEvents automatically registers a sub-event voiding context. You don't need to add it manually.

Troubleshooting

  • Event Stuck in Voided: Use the InsightMatrix debug panel to view active VoidingContexts for the event. This will show exactly which tag or sub-event is blocking completion.
  • Premature Completion: If an event finishes while you expected it to wait, verify that the VoidingContext was correctly added to the event's VoidingRegistry during initialization.