> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.forboc.ai/npm/npc/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.forboc.ai/_mcp/server.

# NPC (Entity)

The current SDK runtime models NPCs as store entities plus protocol thunks.

## Core State Model

`npcSlice` stores:

* `id`
* `persona`
* `state` (`Record<string, unknown>`)
* `history`
* `lastAction`
* block metadata (`isBlocked`, `blockReason`)

## Register an NPC

```typescript
import { createSDKStore, setNPCInfo } from '@forbocai/core';

const store = createSDKStore();

store.dispatch(setNPCInfo({
  id: 'npc_merchant_001',
  persona: 'A cautious merchant guarding rare stock.',
  initialState: {
    trust: 0.2,
    inventory: ['rusty_key', 'healing_potion']
  }
}));
```

## Process Input (Multi-Round Protocol)

```typescript
import { processNPC } from '@forbocai/core';
import { createNodeCortex } from '@forbocai/node';

const cortex = createNodeCortex('smollm2-135m');
await cortex.init();

const response = await store.dispatch(processNPC({
  npcId: 'npc_merchant_001',
  text: "I'd like to buy the key.",
  context: { playerGold: 50 },
  apiUrl: 'https://api.forboc.ai',
  apiKey: process.env.FORBOCAI_API_KEY,
  cortex
})).unwrap();

console.log(response.dialogue);
console.log(response.action?.type);
```

`processNPC` requires:

* a resolved `npcId`
* persona (argument or active NPC)
* a local `cortex`
* memory engine only when API instructions require memory recall/store

## Update NPC State

```typescript
import { updateNPCState, selectActiveNPC } from '@forbocai/core';

store.dispatch(updateNPCState({
  id: 'npc_merchant_001',
  delta: { trust: 0.35 }
}));

const active = selectActiveNPC(store.getState());
console.log(active?.state);
```

## CLI Equivalents

```bash
npx forbocai npc create "A cautious merchant"
npx forbocai npc update <npcId> --mood suspicious --inventory "rusty_key,healing_potion"
npx forbocai npc process <npcId> "I'd like to buy that key"
npx forbocai npc chat <npcId>
```

> Managing NPC state and protocol execution with store + thunks