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

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)

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

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

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>