NPC & Self API¶

Two related APIs for AI NPCs:

NPC.* — make an NPC do things: speak, react to events, report action results, hold state.
Self.* — read and update the NPC's own identity and memory (who it is, what it thinks of a player).

These run server‑side, where the NPC's brain lives. Most NPC.* calls act on the NPC whose script is running; the ...To / ...As variants target a specific NPC you reference (handy from a shared object).

Speaking¶

NPC.Say("Welcome to the workshop!");          // this NPC says it (to everyone nearby)
NPC.SayTo(playerId, "Psst — over here.");      // directed at one player
NPC.SayAs(otherNpc, "And I agree!");           // make a referenced NPC speak

Reacting to the world¶

NPC.Notify / NPC.NotifyTo deliver World Events — your script tells the NPC something happened and it responds in character:

NPC.Notify("player_entered", "{\"playerName\": \"Ada\"}");
NPC.NotifyTo(thatNpc, "alarm", "{\"reason\": \"intruder\"}");

Reporting custom‑action results¶

Inside a Custom Action handler, tell the AI how it went:

NPC.CommandResult("The door is open.");        // success — the AI confirms naturally
NPC.CommandError("That door is locked.");      // failure — the AI won't pretend it worked

State¶

A small string "mode" you can set and read — drive behavior or branch dialogue on it:

NPC.SetState("guarding");
string mode = NPC.GetState();

NPC memory & relationships (`Self.*`)¶

The NPC remembers players and facts across a conversation. Use these to make it feel like it knows people:

Call	What it does
`Self.GetName()` / `Self.GetId()`	the NPC's own name / id
`Self.GetPersonality()`	its configured personality text
`Self.GetPlayerAffinity(playerId)`	how it feels about a player (a score)
`Self.SetPlayerAffinity(playerId, value)`	nudge that relationship up/down
`Self.AddPlayerNote(playerId, note)`	have it remember something about a player
`Self.AddKnowledge(fact)`	add a fact to what the NPC knows
`Self.RecordEvent(text)`	log something that happened for it to recall

// Reward a returning friend
Self.SetPlayerAffinity(playerId, Self.GetPlayerAffinity(playerId) + 10);
Self.AddPlayerNote(playerId, "Helped me find the lost key.");

Memory is per‑conversation / per‑session

Affinity and notes are tied to the NPC's running memory. For identity that survives across sessions, key your own records by the player's stable Player.GetUserId and persist them (Storage / HTTP).

Other¶

NPC.Think(prompt) → ask the NPC's AI to reason about something and return a string (advanced).
NPC.RegisterFunction(name) → register a custom AI‑callable function handled by On_<name> in your script (an alternative to the Action Designer for fully script‑driven tools).

Quick reference¶

API	Calls
Speak	`NPC.Say · SayTo · SayAs`
Events	`NPC.Notify · NotifyTo` → World Events
Action results	`NPC.CommandResult · CommandError` → Custom Actions
State	`NPC.SetState · GetState`
Advanced	`NPC.Think · RegisterFunction`
Identity	`Self.GetName · GetId · GetPersonality`
Memory	`Self.GetPlayerAffinity · SetPlayerAffinity · AddPlayerNote · AddKnowledge · RecordEvent`