Action Designer¶
The Action Designer is the panel on the SSAINpc component where you give an NPC its actions (things it can do) and world events (things it reacts to). It has two tabs.
Actions tab — what the NPC can do¶
Click ➕ Add Action. You get two kinds:
- Built‑in actions — ready‑made and pre‑filled: move to player, follow, patrol, face, emote, play animation, look at, play audio, set a light, spawn/destroy, and more. Pick one and it's wired with a sensible AI description and parameters.
- Custom Script — calls a function in your NexusScript. Use this when you need your own logic.
Each action has:
| Field | Purpose |
|---|---|
| Command ID | The name the AI calls (e.g. set_light_color). |
| AI description | What the AI sees — describe the tool and when to use it, like instructing an assistant. |
| Parameters | Inputs, each typed and described. Mark a parameter exposed (the AI fills it) or fixed (a design‑time value the AI never controls — e.g. a scene reference). |
| Script function | (Custom only) the method your script implements, e.g. OnSetLightColor. |
→ Full detail + the handler pattern: Custom Actions.
Write descriptions for the AI, not for you
The Command ID, description, and parameter descriptions are the only thing the AI sees about a tool. Clear descriptions ("Change a room light's color; use when the player asks") make the difference between an NPC that uses your action well and one that ignores or misuses it.
Multi‑step actions (the action loop)¶
When a request needs several actions — "turn all three lights green", or "check the door, then open it if it's unlocked" — the NPC runs an action loop: it acts, sees what each action returned, and can act again, until the task is done or it hits a round cap.
- Within a single round the AI can fire many actions at once (if the model emits them together, they all run).
- Between rounds, the AI is told what its actions did, then gets to act again or reply — so it can chain steps and react to results.
The cap is the maxToolRounds field on the NPC (Advanced section), default 4:
maxToolRounds |
Behavior |
|---|---|
1 |
One acting turn. The AI can still fire several actions at once, but can't act, see the result, then act again. Fastest / cheapest. |
4 (default) |
Up to four acting rounds before it must reply. Handles "do this to all of them" and act‑then‑react flows. |
up to 8 |
More room for long chains. |
Each round is another model call
A higher cap means more capability but more cost and latency — every extra round is one more call to your AI provider. The loop stops early as soon as the AI stops requesting actions, so simple requests still finish in one round. If an NPC only ever does one of several things you asked, that's usually the model emitting one action and maxToolRounds being 1 — raise it.
Events tab — what the NPC reacts to¶
Define the world events your scripts will fire. Each event:
| Field | Purpose |
|---|---|
| Event ID | The id your script fires with NPC.Notify (must match exactly). |
| Context template | What the AI is told, with {placeholders} filled from the script's data. |
| React immediately | On = respond the moment it fires; Off = just remember it for later. |
Hit 📋 Examples for a categorized starter library:
| 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 |
→ Full detail + firing from a script: World Events.
Actions vs Events — which tab?¶
| You want… | Tab | Direction |
|---|---|---|
| The AI to do something | Actions | AI → your world |
| The NPC to react to something | Events | your world → NPC |
Tips¶
- Turn on
debugToolCalls(on the NPC) to log every action the AI invokes and its result — invaluable while wiring. - For custom actions and events, the script that implements/fires them must be on the NPC's GameObject or in its Action Scripts list.