ainpcengine

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.