AINPCEngine Node.js SDK

Official Node.js SDK for AINPCEngine - AI-powered NPC engine for games.

Create NPCs with real personalities, memories, and dynamic dialogue. Every NPC remembers, gossips, and reacts.

Install

npm install ainpcengine

Requires Node.js 22 or newer (the WebSocket client uses the built-in global WebSocket — zero dependencies).

Quick Start

const AINPCEngine = require('ainpcengine');

const client = new AINPCEngine({
  baseUrl: 'https://ainpcengine.com',
  apiKey: 'YOUR_API_KEY',       // Get one at https://ainpcengine.com
  gameId: 'your-game-id',
});

// Talk to an NPC
const result = await client.say(npcId, 'player_1', 'I need a sword', {
  location: 'blacksmith_shop',
  timeOfDay: 'evening',
});

console.log(result.response.dialogue);

Health Check

// No API key needed - great for startup checks
const status = await client.health();

NPC CRUD

// Create
const npc = await client.createNPC({
  name: 'Grok the Blacksmith',
  personality: {
    traits: ['gruff', 'honest'],
    speechStyle: 'direct, no-nonsense',
    backstory: 'Former soldier turned smith...',
    values: ['family', 'hard work'],
  },
  role: 'merchant',
  faction: 'ironforge',
});

// List all NPCs for your game
const npcs = await client.listNPCs();

// Get single NPC
const grok = await client.getNPC(npcId);

// Update
await client.updateNPC(npcId, {
  location: 'market_square',
  mood: { emotion: 'happy', intensity: 0.8 },
});

// Delete
await client.deleteNPC(npcId);

Generate NPCs

// Generate single NPC with full persona (OCEAN, schedule, psychology)
const npc = await client.generateNPC({ role: 'merchant' });

// Generate batch with social relationships
const { npcs, socialLinks } = await client.generateBatch({ count: 5 });

Events

// Player dialogue
const result = await client.say(npcId, playerId, message, context);

// Player approaches NPC
const result = await client.approach(npcId, playerId, context);

// Player leaves NPC
const result = await client.leave(npcId, playerId, context);

// Trade request
const result = await client.requestTrade(npcId, playerId, context);

// NPC autonomy tick (hourly world simulation)
const result = await client.ambientTick(npcId, context);

// NPC gossip
const result = await client.gossip(npcId, context);

// Generic event (21 event types supported)
const result = await client.sendEvent(npcId, {
  type: 'combat_started',
  playerId,
  context,
});

NPC Voice (TTS)

Give your NPCs a voice. Requires a Voice add-on on your plan.

const { audio, format, voice } = await client.speak(npcId, 'Welcome to my forge, traveler!');
// audio: base64-encoded audio you can play in your game client

Real-Time WebSocket

Stream game events and receive NPC responses and live state updates with minimal latency — ideal for in-game dialogue.

const { NPCWebSocket } = require('ainpcengine');

const ws = new NPCWebSocket({
  baseUrl: 'https://ainpcengine.com',
  apiKey: 'YOUR_API_KEY',
  gameId: 'your-game-id',
});

ws.on('response', (result) => {
  console.log(result.response.dialogue);
});

ws.on('state_update', ({ npcId, data }) => {
  console.log(`${npcId} changed:`, data); // mood, location...
});

ws.on('error', (err) => console.error(err.message));
ws.on('close', ({ code, reason }) => console.log('disconnected', code, reason));

await ws.connect(); // resolves when the server confirms

// Get live state updates for specific NPCs
ws.subscribe([npcId]);

// Send events - responses arrive via the 'response' event
ws.sendEvent(npcId, {
  type: 'player_dialogue',
  playerId: 'player_1',
  message: 'Hello!',
  context: { location: 'tavern' },
});

// Later
ws.unsubscribe([npcId]);
ws.close();

Events emitted: connected, response, error, subscribed, unsubscribed, state_update, close.

Error Handling

All non-2xx responses throw an AINPCError with structured fields:

const { AINPCError } = require('ainpcengine');

try {
  await client.say(npcId, playerId, 'Hello!');
} catch (err) {
  if (err instanceof AINPCError) {
    console.log(err.status);      // HTTP status, e.g. 402
    console.log(err.code);        // machine-readable code
    console.log(err.paymentUrl);  // where to fix billing (when relevant)
  }
}

Error codes:

| Code | Meaning | What to do | |------|---------|------------| | payment_required | 402 — no card on file yet, or subscription cancelled | Add a card at ainpcengine.com to start your 7-day free trial ($0 charged today). err.paymentUrl links straight there. | | npc_limit | Your plan's NPC limit is reached | Delete unused NPCs or upgrade your plan | | feature_not_in_plan | Feature not included in your plan | Upgrade your plan | | interaction_cap | Monthly included interactions used up | Overage billing or plan upgrade |

The 7-day free trial flow: sign up, pick a plan, add a card ($0 today) — your API key activates instantly and you aren't charged until day 7. Until a card is added, API calls return 402 with code: 'payment_required'.

if (err instanceof AINPCError && err.isPaymentRequired) {
  console.log(`Activate your trial: ${err.paymentUrl}`);
}

Game Context

const context = {
  location: 'blacksmith_shop',
  timeOfDay: 'evening',
  weather: 'rain',
  nearbyNPCs: ['merchant_1'],
  playerReputation: 75,
  playerLevel: 5,
  activeQuests: ['find_sword'],
  recentEvents: ['helped_village'],
};

Also Available

• Unity SDK
• Unreal SDK
• Godot SDK
• Rust SDK

Get an API Key

Sign up at ainpcengine.com to get your API key. Every plan starts with a 7-day free trial — $0 today.

License

MIT - Copyright (c) 2026 Joe Wee / Tyga.Cloud Ltd.