Skip to main content

Getting Started

@open-core/npc-agents adds an intelligence layer for NPCs on top of OpenCore entity lifecycle.

Use it when you want behavior orchestration through controllers, skills, and optional AI decisions.

Core Concepts​

  • Controller: declares a behavior scope (@NpcIntelligentController({ id, planner, skills }))
  • Skill: executable unit (@NpcSkill() class)
  • Planner: chooses the next skill (rule or ai)
  • Runtime API: IntelligentNpcAPI to spawn, attach, observe, and run

Rule vs AI​

  • Rule: deterministic execution, you choose exact skill and args.
  • AI: planner chooses from allowed skills using current goal + observations.
  • Both return explicit run results (ok, done, skill, waitMs, error).

Built-in Skills​

  • IdleSkill
  • MoveToSkill
  • MoveRelativeSkill
  • SetHeadingSkill
  • WaitSkill
  • LookAtEntitySkill
  • GoToCarDriveParkSkill

This is the minimum setup for @open-core/npc-agents with server + client plugins.

1) Install​

pnpm add @open-core/npc-agents

2) Server Setup​

import { Server } from '@open-core/framework/server'
import { npcIntelligencePlugin } from '@open-core/npc-agents/server'

await Server.init({
mode: 'CORE',
plugins: [npcIntelligencePlugin()],
})

3) Client Setup​

import { Client } from '@open-core/framework/client'
import { npcClient } from '@open-core/npc-agents/client'

await Client.init({
mode: 'CORE',
plugins: [npcClient()],
})

4) Create a Controller​

import {
NpcIntelligentController,
MoveToSkill,
WaitSkill,
} from '@open-core/npc-agents/server'

@NpcIntelligentController({
id: 'patrol-controller',
planner: 'rule',
skills: [MoveToSkill, WaitSkill],
tickMs: 500,
})
export class PatrolController {}

5) Spawn and Run (Rule)​

import {
IntelligentNpcAPI,
NpcIntelligentController,
MoveToSkill,
WaitSkill,
} from '@open-core/npc-agents/server'

@NpcIntelligentController({
id: 'patrol-controller',
planner: 'rule',
skills: [MoveToSkill, WaitSkill],
})
export class PatrolController {
constructor(private readonly npcInt: IntelligentNpcAPI) {}

async runPatrol() {
const npc = await this.npcInt.spawn({
model: 's_m_y_cop_01',
position: { x: 0, y: 0, z: 72 },
networked: true,
})

await this.npcInt
.rule('patrol-controller')
.for(npc)
.name('Guard Alpha')
.npcType('guard')
.do(MoveToSkill, { x: 15, y: -40, z: 72 })
.do(WaitSkill, { ms: 2000 })
.runAll()
}
}

6) AI Setup with OpenRouter​

Set your API key:

export OPENROUTER_API_KEY=your_key_here

Configure plugin + AI controller:

import { Server } from '@open-core/framework/server'
import {
npcIntelligencePlugin,
NpcIntelligentController,
GoToCarDriveParkSkill,
MoveToSkill,
WaitSkill,
} from '@open-core/npc-agents/server'

await Server.init({
mode: 'CORE',
plugins: [
npcIntelligencePlugin({
openRouter: {
model: 'openai/gpt-4o-mini',
temperature: 0.2,
maxTokens: 220,
},
debug: {
enabled: process.env.NPC_AI_DEBUG === '1',
runtime: true,
llm: process.env.NPC_AI_DEBUG_LLM === '1',
},
}),
],
})

@NpcIntelligentController({
id: 'ai-driver',
planner: 'ai',
skills: [GoToCarDriveParkSkill, MoveToSkill, WaitSkill],
ai: {
model: 'openai/gpt-4o-mini',
temperature: 0.25,
perSkill: {
goToCarDrivePark: {
model: 'openai/gpt-4o',
temperature: 0.1,
},
},
},
})
export class AiDriverController {}

Run one AI decision:

await npcInt
.ai('ai-driver')
.for(npc)
.name('Courier #4')
.npcType('courier')
.goal('deliver-order', 'arrive quickly but safely')
.instruction('Take vehicle 120 and park near the player')
.deny(WaitSkill)
.run()