World Events¶

A world event is your script telling an NPC something happened — a player walked up, a door opened, a round ended — so the AI can react in character. You don't script what it says; you hand it the fact, and the AI writes the line.

This is the opposite direction from Custom Actions:

World Event = your script → the NPC. "This happened." (NPC.Notify)
Custom Action = the AI → your script. "Do this." (the AI calls a tool you implement)

1. Define the event (Action Designer ▸ Events)¶

On the NPC's SSAINpc, open the Action Designer ▸ Events tab and add an event:

Field	Meaning
Event ID	The id your script fires (e.g. `player_entered`). Must match exactly.
Context template	What the AI is told. Use `{placeholders}` for values your script sends.
React immediately	On = the NPC responds the moment it fires. Off = it just remembers it for next time.

Hit 📋 Examples for a ready‑made library (greeter, zones, doors, items, quests, game flow, world). The Greeter pair matches the GreeterTrigger example exactly.

2. Fire it from a script¶

// React immediately ON, template: "{playerName} just walked up to you. Greet them by name."
NPC.Notify("player_entered", "{\"playerName\": \"Ada\"}");

The JSON keys fill the template's {placeholders}. The AI sees "Ada just walked up to you. Greet them by name." and speaks a greeting.

Placeholders must match the keys you send

If your template uses {areaName} but the JSON only has playerName, {areaName} comes out blank. Send every key the template references.

3. Targeting which NPC¶

Call	Reaches
`NPC.Notify(eventId, json)`	The NPC this script is running on.
`NPC.NotifyTo(npc, eventId, json)`	A specific NPC you reference — so a standalone trigger object (a doorway, a zone) can notify one or several NPCs.

Use NotifyTo when the script isn't on the NPC itself.

Worked example — greet by username¶

GreeterTrigger (in the Examples) greets a player by name on enter and says goodbye on exit. It's dual‑mode: put it + a trigger collider on the NPC (leave Target Npcs empty → NPC.Notify), or on a separate zone and drag the NPC(s) into Target Npcs → NPC.NotifyTo.

void OnTriggerEnter(Collider other)
{
    string id = Player.IdOf(other.gameObject);   // "" if not a player
    if (id == "") return;
    string who = Player.GetUsername(id);          // validated account username
    if (who == "") who = "there";
    NPC.Notify("player_entered", "{\"playerName\": \"" + who + "\"}");
}

The two events player_entered / player_left (React immediately ON) go in the NPC's manifest — one click each from Examples ▸ Greeter.

Greet generically (no name) but still track who they are¶

What the NPC says is only what you pass in — so to keep a name out of its mouth, just don't send one. To still know who they are, use Player.GetUserId(id): a stable account id (same across sessions, unlike the per‑session Player.IdOf). Keep it in your own logic — never put it in the event. The IdentityGreeter example greets generically while tracking returning visitors by account id. See Player API and Storage.

Group	Examples
Greeter	greet on enter (by name / generic) · goodbye on leave
Zones & triggers	player entered a zone · door opened · button pressed
Items & quests	item picked up · objective completed · quest started
Game flow	round started / ended · score changed
World	alarm / danger · time of day changed

They're starting points — edit the wording and {placeholders} to fit your world.