Skip to content
Tuxedo CatSTUDIO
Menu

UI Director V1 Integration Contract

Review draft. This source page has not completed website editorial and release-specific verification.

Status

Section titled “Status”

INTEGRATION CONTRACT - VERSION 1.1.0

The original 1.0.0 release established the UI Director product baseline.

Version 1.1.0 (numeric plugin Version 1) provides a LocalPlayer-owned transient presentation model, standalone UMG display projection, semantic UI navigation and input/focus coordination, and an Editor-only read-only Runtime Inspector in UIDirectorEditor. UI Director does not require DirectorBridge for standalone presentation. Dialogue and Inventory retain their own gameplay consequences and state authority; optional adapters are separately owned.

1. Fundamental Rule

Section titled “1. Fundamental Rule”

UI Director owns how game information is presented.

The source gameplay Director owns what that information means.

The bridge owns translation.

2. Required Dependency Pattern

Section titled “2. Required Dependency Pattern”

Core gameplay Directors do not gain mandatory UI Director dependencies.

Use optional bridge plugins.

Conceptually:

Dialogue Director -> Dialogue Director UI Bridge -> UI Director

Interaction Director -> optional DirectorBridge Interaction.UI adapter -> UI Director

Quest Director -> optional Quest UI Bridge -> UI Director

This preserves standalone usability.

UI Director must not hard-depend on Interaction Director core for its general presentation use cases. If DirectorBridge is absent, UI Director remains valid for non-Interaction UI. Interaction.UI is an optional Bridge integration supplied by DirectorBridge 1.13.0. It remains outside the UI Director plugin and is not required for standalone UI use.

3. Dialogue Director Integration

Section titled “3. Dialogue Director Integration”

Dialogue Director remains the authoritative controller of narrative gameplay flow for this project.

Dialogue Director determines:

  • active Dialogue session;
  • current node;
  • current text;
  • current speaker;
  • available choices;
  • conditions;
  • skill checks;
  • Probability results;
  • actions;
  • Quest updates;
  • Inventory updates;
  • Knowledge updates;
  • Relationship updates;
  • World State updates;
  • graph transitions;
  • Dialogue history.

UI Director determines:

  • how Dialogue appears;
  • where it appears;
  • input focus;
  • cursor behavior;
  • widget lifecycle;
  • visual transitions.

4. Dialogue Presentation Flow

Section titled “4. Dialogue Presentation Flow”

Conceptually:

Dialogue Director -> authoritative Dialogue presentation state -> Dialogue/UI Bridge -> UI Director -> configured Dialogue presentation widget

When Dialogue changes:

Dialogue Director -> bridge refreshes semantic view model -> UI Director updates existing presentation

5. Dialogue Input Flow

Section titled “5. Dialogue Input Flow”

Player selects a choice:

UI Widget -> UI Director / Dialogue UI presentation adapter -> Dialogue/UI Bridge -> Dialogue Director SelectChoice(SessionId, ChoiceId)

Dialogue Director then:

  1. validates the choice;
  2. resolves conditions/checks;
  3. calls Probability where required;
  4. executes approved actions;
  5. mutates domain Directors through their bridges/APIs;
  6. advances the Dialogue graph;
  7. exposes new presentation state.

UI Director does none of those gameplay operations.

6. Narrative-Heavy Game Contract

Section titled “6. Narrative-Heavy Game Contract”

For this project, Dialogue Director is the primary high-level narrative gameplay orchestrator.

This is intentional.

Dialogue Director may coordinate approved public APIs belonging to:

  • Probability Director;
  • Quest Director;
  • Inventory Director;
  • Character State Director;
  • Relationship Director;
  • Knowledge Director;
  • World State;
  • SignalBus;
  • other explicitly approved bridges.

Dialogue Director does not own those systems’ data.

7. No Gameplay Director Required

Section titled “7. No Gameplay Director Required”

A generic Gameplay Director is not part of the current approved architecture.

The current game is narrative-heavy and does not presently have a large independent action/combat gameplay orchestration layer that warrants another top-level coordinator.

This decision may be revisited only if significant future gameplay emerges that does not naturally belong to:

  • Interaction Director;
  • Dialogue Director;
  • a domain Director;
  • another clearly defined specialist system.

Do not create a generic Gameplay Director preemptively.

8. Headless / Action-Only Dialogue Direction

Section titled “8. Headless / Action-Only Dialogue Direction”

The architecture explicitly permits a future Dialogue execution path that contains no player-facing text.

Conceptually:

Interaction -> Dialogue orchestration -> Conditions -> Actions -> End

If no presentable Dialogue state occurs, Dialogue UI does not need to open.

This must be implemented as an explicit Dialogue capability rather than relying on accidental empty text widgets.

This remains a Dialogue capability and does not change UI Director’s presentation-only role. Dialogue execution is separate from the available optional Dialogue/UI presentation integrations.

9. Direct Interaction Event Alternative

Section titled “9. Direct Interaction Event Alternative”

A simple interaction does not have to invoke Dialogue. It still uses the Interaction Director validation and DirectorBridge routing boundary. An explicitly authorized game route may lead to a handler or another typed destination, but this is not a generic Interaction.SignalBus adapter.

There is currently no generic Interaction SignalBus route. UI Director must not publish gameplay commands such as Interaction.Book.Discuss, Interaction.Item.Pickup, or generic Interaction verbs to SignalBus. Any cross-Director SignalBus use belongs to DirectorBridge only when an explicitly authorized route requires it.

Use Dialogue when the interaction benefits from:

  • narrative sequencing;
  • conditions;
  • skill checks;
  • ordered actions;
  • graph branching;
  • Dialogue history/context;
  • multiple domain mutations.

10. Interaction to Dialogue Flow

Section titled “10. Interaction to Dialogue Flow”

The consequence flow starts only after UI selection has gone through fresh Interaction validation:

UI semantic selection (slot and/or exact InteractionId) -> DirectorBridge Interaction.UI request proxy -> Interaction Director request API -> fresh Interaction validation -> DirectorBridge Interaction.Routing exact-ID route -> Interaction.Dialogue typed adapter -> Dialogue Director -> separate Dialogue/UI presentation integration -> UI Director

The UI label is presentation only. UI Director does not decide which Dialogue asset is started, directly call Dialogue Director because a button says “Discuss”, or choose conversation context/participants.

Interaction/Dialogue integration authoring and its Dialogue resolver determine the conversation definition, context, and participants.

11. Example: Discuss

Section titled “11. Example: Discuss”

UI shows:

Discuss

Semantic identity:

Interaction.Book.Discuss

Selection:

UI -> DirectorBridge -> Interaction request -> fresh validation.

Success:

Interaction -> DirectorBridge exact-ID route -> Interaction.Dialogue.

The Dialogue resolver determines the conversation definition/context and participants. UI does not determine the conversation. The resulting Dialogue session is then presented through the separate Dialogue/UI integration.

12. Example: Pickup

Section titled “12. Example: Pickup”

UI shows:

Pick Up

Semantic identity:

Interaction.Item.Pickup

Selection:

UI -> DirectorBridge -> Interaction request -> fresh validation.

Success:

Interaction -> DirectorBridge exact-ID route -> Interaction.Inventory.

The Inventory resolver determines item, destination, and quantity. UI does not call AddItem. UI may separately display resulting Inventory state through a future Inventory presentation integration.

13. Example: Inspect

Section titled “13. Example: Inspect”

UI shows:

Inspect

Semantic identity:

Interaction.Object.Inspect

Selection follows UI -> DirectorBridge -> Interaction request -> fresh validation. Destination must be an explicit Bridge/game route. Do not assume Inspect always belongs to UI Director or infer a destination from its label.

All examples preserve exact InteractionId and slot. DisplayText is for display only; localized text and parent Gameplay Tags are not routing identity.

Validated commands may reach typed destinations only after Interaction validation. Rejected attempts remain Interaction-owned results and may be relayed by DirectorBridge to UI for feedback; they do not call Dialogue, Inventory, another adapter, or generic SignalBus traffic.

Interaction Director 1.1 supports Auto, ViewCenter, and MouseCursor. Targeting mode and normalized Pointer Acquisition Radius belong to the Interaction Director LocalPlayer runtime. UI may display authoritative mode and candidate facts but must not infer mode, recalculate mouse acquisition, or recompute distance, visibility, focus, option resolution, or validity.

Interaction Director owns semantic bindings for Primary, Secondary, Tertiary, and Quaternary. The game/project owns Enhanced Input Mapping Contexts and physical input mappings. UI Director owns only UI navigation/selection within its own presentation surface.

The runtime accepts the semantic commands Up, Down, Left, Right, Confirm, Cancel, Next, and Previous. It does not bind physical keys or install/remove gameplay Mapping Contexts. Surface definitions can independently request an input mode (GameOnly, GameAndUI, UIOnly) and cursor policy (Preserve, Show, Hide). An active Modal/System UIOnly request takes precedence over GameAndUI, then GameOnly, then the configurable GameOnly baseline. Cursor policy uses the highest-ranked visible explicit request; Preserve restores the baseline captured for the LocalPlayer’s current controller.

Logical focus remains a PresentationId; UMG/Slate user focus is ephemeral and is restored inside a recreated surface where possible. An optional focusable surface interface may provide a preferred initial widget or consume Confirm and Cancel. The active modal alone receives navigation. Cancel closes it only when its definition explicitly enables Cancel-to-close; otherwise a surface handler may consume Cancel. UI Director does not pause gameplay or infer gameplay consequences from Confirm.

Interaction Director is LocalPlayer-owned. Bridge calls and UI presentation subscriptions preserve the owning LocalPlayer explicitly or use a deterministic UI-player context; they must not assume Player 0.

The optional Interaction.UI adapter provides a focused-target presentation snapshot, resolved option views, authoritative range/visibility/ focus feedback, latest rejection/result presentation, exact slot/ID request proxy, and LocalPlayer context. It must not execute consequences, resolve Dialogue/Inventory definitions, publish generic consequence SignalBus events, or recalculate Interaction runtime state. World prompts, lists, radial menus, context menus, focused-object panels, and controller selectors are presentation modes over the same options and all route selections back through validation.

14. Probability / Roll Presentation

Section titled “14. Probability / Roll Presentation”

Probability Director owns random resolution.

Dialogue Director owns the narrative meaning of the check.

UI Director may display:

  • chance;
  • skill;
  • roll;
  • modifiers;
  • success/failure;
  • presentation effects.

UI Director must never generate or reroll the result.

15. SignalBus Boundary

Section titled “15. SignalBus Boundary”

SignalBus may carry explicitly authorized loosely coupled semantic events.

Do not route every Dialogue line, choice update, or presentation refresh through SignalBus.

Dialogue/UI is long-lived session state and uses the optional bridge plus authoritative Dialogue state/delegates.

UI Director does not own gameplay consequence publication. There is no generic Interaction.SignalBus route. Cross-Director SignalBus use belongs to DirectorBridge only where an explicitly authorized route requires it.

16. Optional Integration Boundaries

Section titled “16. Optional Integration Boundaries”

UI Director V1.1 provides a LocalPlayer-owned semantic presentation model, standalone display definitions, navigation and input coordination, and an Editor-only Runtime Inspector. Its runtime and editor modules have no dependency on another Director or on DirectorBridge.

The optional DirectorBridge 1.13.0 Interaction.UI adapter and the separate Dialogue, Inventory, and Interaction routes remain owned by DirectorBridge and their source Directors. These integrations can be used alongside UI Director, but are not required for its standalone presentation features. Gameplay meaning and consequences remain with the source Director; UI Director does not execute them.

Neutral presentation view and action seam

Section titled “Neutral presentation view and action seam”

FUIDirectorPresentationView, its entries, and metrics are domain-neutral presentation data. UpdatePresentationView replaces a complete view; it does not patch fields. The LocalPlayer subsystem allocates monotonically increasing int64 revisions across presentation registrations and committed view, visibility, or type changes. Removing and re-registering an identity therefore cannot revive an old action; exhaustion rejects further revisions without wrapping. Surface reconstruction alone does not change semantic revision.

SubmitPresentationAction accepts entry-bound actions only. It requires a visible presentation, enabled view, current revision, a current non-None EntryId, a matching current non-None ActionId, and an enabled entry. Hidden, disabled, stale, entryless, unknown-entry, or mismatched actions are rejected without an accepted-action event. Once validation succeeds, the owning UUIRuntimeSubsystem broadcasts the same accepted action once through its native OnPresentationActionAcceptedNative() event and once through the existing Blueprint dynamic OnPresentationActionAccepted event, in that order, before returning. Neither event can change the already-established acceptance result; acceptance does not mutate the presentation or execute gameplay. The Editor build records only the latest action attempt per presentation in a bounded, 128-entry diagnostic map under WITH_EDITOR. Recording occurs after validation and reuses EUIDirectorPresentationActionStatus and EUIDirectorPresentationActionReason; it does not change the return result or accepted-action events. This diagnostic seam is absent from non-Editor builds. The native accepted-action delegate is instance-owned by each LocalPlayer subsystem. Optional C++ consumers bind with an FDelegateHandle and remove their binding during their own teardown. An external adapter may consume this seam, but UI Director has no dependency on it. IUIDirectorPresentationViewReceiver is optional; ordinary UUserWidget surfaces remain supported. A view-only update to an unchanged presentation type keeps the widget instance and pushes the replacement view to a receiver. The Editor Runtime Inspector is read-only and uses only UI Director’s public state queries and lifecycle events. UI Runtime and Editor keep no dependencies on other Directors, SignalBus, or DirectorBridge.