NPC (Entity) | ForbocAI SDK

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

1 import { createSDKStore, setNPCInfo } from '@forbocai/core';
2 
3 const store = createSDKStore();
4 
5 store.dispatch(setNPCInfo({
6   id: 'npc_merchant_001',
7   persona: 'A cautious merchant guarding rare stock.',
8   initialState: {
9     trust: 0.2,
10     inventory: ['rusty_key', 'healing_potion']
11   }
12 }));

Process Input (Multi-Round Protocol)

1 import { processNPC } from '@forbocai/core';
2 import { createNodeCortex } from '@forbocai/node';
3 
4 const cortex = createNodeCortex('smollm2-135m');
5 await cortex.init();
6 
7 const response = await store.dispatch(processNPC({
8   npcId: 'npc_merchant_001',
9   text: "I'd like to buy the key.",
10   context: { playerGold: 50 },
11   apiUrl: 'https://api.forboc.ai',
12   apiKey: process.env.FORBOCAI_API_KEY,
13   cortex
14 })).unwrap();
15 
16 console.log(response.dialogue);
17 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

1 import { updateNPCState, selectActiveNPC } from '@forbocai/core';
2 
3 store.dispatch(updateNPCState({
4   id: 'npc_merchant_001',
5   delta: { trust: 0.35 }
6 }));
7 
8 const active = selectActiveNPC(store.getState());
9 console.log(active?.state);

CLI Equivalents

$ 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>