Event System

Event System

The event system is how NPC dialogue translates into gameplay actions. The LLM suggests events as part of its structured response, and the system validates and dispatches them through a strict pipeline before anything happens in-game.

Event Lifecycle

LLM Response
  └─ event_suggestions: [
       { "event_id": "shop.open", "confidence": 0.95, "args": { "shop_id": "..." } },
       { "event_id": "anim.trigger", "confidence": 0.8, "args": { "anim_id": "nod" } }
     ]
        │
        ▼
  ┌─────────────────────────────┐
  │ 1. Confidence Gate          │  event.confidence >= config.fireConfidenceThreshold?
  │    (NpcBrainConfig)         │  No → event silently skipped
  └──────────────┬──────────────┘
                 │ Yes
                 ▼
  ┌─────────────────────────────┐
  │ 2. Normalization            │  AiNpcBrain fills in NPC-specific args:
  │    (AiNpcBrain)             │  - shop_id from NpcUiBindings
  │                             │  - quest_board_id from NpcUiBindings
  │                             │  - relationship_id from NpcUiBindings
  │                             │  - anim_id fallback from context
  └──────────────┬──────────────┘
                 │
                 ▼
  ┌─────────────────────────────┐
  │ 3. EventGate Validation     │  Checks against NpcEventCatalog:
  │    (EventGate.cs)           │  - Event exists in catalog?
  │                             │  - All required args present?
  │                             │  - Arg types correct?
  │                             │  - Values in allowed list?
  │                             │  - No unexpected extra args?
  └──────────────┬──────────────┘
                 │ Pass
                 ▼
  ┌─────────────────────────────┐
  │ 4. Payload Dispatch         │  JSON string fired via:
  │    (UnityEvent<string>)     │  OnAnyNpcEventPayload.Invoke(payload)
  └──────────────┬──────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
  NpcAnimationReceiver  AureliaDemoReceiver
  (or your receiver)    (or your receiver)

Event Catalog Setup

The NpcEventCatalog ScriptableObject is the whitelist. Every event the NPC can suggest must be defined here.

Defining an Event

Each EventDefinition has:

Standard Events

These are the events used in the demo. You can add, remove, or modify them.

Shop Events

Quest Events

Relationship Events

Animation Events

UI Events

EventGate Validation Rules

EventGate.TryBuildPayload() performs these checks in order:

1. Catalog exists — returns false if no catalog is assigned.
2. Event ID exists — the event_id must match an entry in NpcEventCatalog.events.
3. Args object exists — the suggestion must have a non-null args dictionary.
4. Required args present — every arg defined in the catalog schema must be provided.
5. Type validation — each arg value must parse as the expected type (String always passes, Int/Float/Bool must parse).
6. Allowed values — if the schema arg has a non-empty allowedValues list, the provided value must be in that list.
7. No extra args — any arg key not in the schema is rejected.

If all checks pass, a minimal JSON payload is built and returned:

{"event_id":"shop.open","args":{"shop_id":"npc_aurelia_alchemist.shop"}}

Event Normalization

Before validation, AiNpcBrain.NormalizeEventSuggestion() patches the event args to ensure consistency:

This means even if the LLM omits or gets an arg wrong, the system fills in the correct NPC-specific value.

Auto-Animation Fallback

If the LLM doesn't suggest any anim.trigger event in a turn, AiNpcBrain automatically picks an animation based on context:

This ensures the NPC always has some body language, even without explicit LLM guidance.

Receiving Events

NpcAnimationReceiver

Handles anim.trigger and anim.move_to events.

Animation triggers: Looks up the anim_id in NpcAnimationMap to find the actual Animator trigger name, then calls Animator.SetTrigger().

Movement: Supports these built-in move_id values:

AureliaDemoReceiver

Routes non-animation events to UI panels via WindowRegistryRuntime. It:

1. Parses the JSON payload to extract event_id and args.
2. Normalizes common model aliases (e.g. quest.open → quest.open_board).
3. Looks up the target window ID (from args or NpcUiBindings fallback).
4. Closes all panels, then opens the matching one.
5. Supports Escape to close all panels.

Writing a Custom Event Receiver

To handle events your own way:

public class MyEventReceiver : MonoBehaviour
{
    public void OnEventPayload(string payload)
    {
        // Parse the JSON payload
        // payload format: {"event_id":"...","args":{"key":"value"}}

        // Route to your game systems
    }
}

Then wire AiNpcBrain.OnAnyNpcEventPayload → MyEventReceiver.OnEventPayload in the Inspector.

Adding a Custom Event

1. Open your NpcEventCatalog asset in the Inspector.
2. Add a new entry to the events list:
3. eventId: your unique ID, e.g. trade.barter
4. description: explain to the LLM when to suggest it
5. args: define required arguments with types and optional allowed values
6. Write a receiver that handles this event ID.
7. Wire it to OnAnyNpcEventPayload.

The LLM will automatically see the new event in its prompt and can start suggesting it in contextually appropriate moments.