Smart NPCs developer docs

Quickstart

Five steps from zero to a reactive NPC. If anything misbehaves, each step links to the fix.

1. Install the client.
   terminal

   npm install @npc/client

2. Copy your public key. Open Studio → Overview and copy the game's pk_live_… key. Public keys are safe in browser code; the sk_live_… secret is shown once at creation and must never leave your server (see Keys & Origins).
3. Create a character. In Studio → Characters, add a slug such as smith with a persona and allowed behaviours. The slug is the id you pass to npc() — a typo silently spawns a blank default character (why).
4. Allow your origin. In Studio → My Games, add every origin that serves your game (http://localhost:5173 for dev, https://yourgame.com for prod). Browsers send an Origin header; anything not on the list gets FORBIDDEN_ORIGIN (fix).
5. Paste the snippet and fire an event. Then verify it in Studio → Test console and Studio → Ops → Interaction Transcripts — every exchange lands there with its behaviour, latency, and turn id.

import { npc } from '@npc/client';

// 1. Public key + character slug — no secrets in the browser.
const smith = npc({
  key: 'pk_live_your_game_key',
  id: 'smith',
});

// 2. Report events, switch on the guaranteed behaviour enum.
async function onPlayerInteract(event, worldState = {}) {
  // react() NEVER throws. It always returns a behaviour.
  const reaction = await smith.react(event, worldState);

  switch (reaction.behaviour) {
    case 'greet':      npcSprite.play('wave'); break;
    case 'warn':       npcSprite.play('angry'); break;
    case 'offer_deal': npcSprite.play('trade'); break;
    default:           npcSprite.play('idle'); break;
  }

  if (reaction.say) {
    showDialogueBubble(reaction.say);
  }
}

// 3. Fire-and-forget memory (returns immediately, never throws).
smith.observe('player completed the dragon cavern quest');

Client SDK reference

The @npc/client surface is four methods. Every one is safe to call from a render loop: nothing throws, ever — failures degrade to your fallback instead of crashing the frame.

npc(options)

react(event, world?, options?) → NpcReaction

The primary call: describe what happened, optionally attach world state, and get back a behaviour enum plus an optional dialogue line. Never throws.

say(text, world?, options?) → NpcDialogue

Conversation call: the player says a line, the NPC answers in character. Same guarantees as react (never throws, same fallback semantics); the result carries text instead of behaviour/say.

observe(event) → void

Fire-and-forget memory write. Returns immediately; delivery failures are swallowed because observations must never break gameplay.

forget() → Promise<boolean>

Erases this player's relationship and memory with the character (your GDPR/COPPA “forget me” button) and drops the local player id, so the next call starts a fresh stranger. Resolves true on success,false otherwise — never throws.

Players, sessions & trust

• Player identity. The SDK mints a plr_… id and persists it in localStorage (npc_player_id). Memory, disposition, and revocation all key off it — clearing site data starts a fresh stranger.
• Session tokens. The client exchanges the public key for a short-lived session token (15 minutes). An expired token returns 401, which the SDK refreshes and retries once, transparently.
• Duplicate suppression. The identical event + world state within 3 seconds returns the previous response without a network call — safe to fire from overlap handlers every frame.
• Idempotency. Every request carries an idempotency key, so retried calls (including the 401 refresh above) replay the original response instead of executing twice.
• World attestation (optional). If your server holds the game secret, it can HMAC-sign the world state; the browser forwards the signature via worldSignature and the response reports worldTrusted: true. Unsigned worlds work fine — they are just advisory, so never gate prizes or purchases on unattested state.

Keys & origins

Origin allowlist

Browsers attach an Origin header, and the worker checks it against the game's allowlist (Studio → My Games → origins) before doing any work:

• Exact match: https://yourgame.com (scheme and port matter).
• Prefix match: a trailing * matches a URL prefix — https://yourgame.com/* covers every path on that host.
• Allow all: a lone * skips the check. Fine for local dev, never for production.
• No header, no check: native apps and curl send no Origin, so they pass. The allowlist stops browser hotlinking, not determined attackers — pair it with world attestation for anything valuable.

Content rating

Each game carries an E / T / M rating that scopes moderation strictness. Pick the lowest rating your content actually needs — stricter ratings reject more edge-case dialogue.

Limits & quotas

Hard numbers, so you can design around them instead of discovering them at 2am.

Troubleshooting

Every failure the client can surface, mapped to its cause and fix. Start here before support — and when you do contact support, quote the turnId from the failing response.

FAQ