API Documentation

ainpc login --key YOUR_KEY --game my-rpg
# All subsequent commands auto-include credentials

{
  "name": "Grok the Blacksmith",
  "role": "merchant",
  "faction": "village_guard",
  "location": "blacksmith_shop",
  "personality": {
    "traits": ["gruff", "honest", "protective"],
    "speechStyle": "gruff",
    "backstory": "Former soldier who retired to smithing",
    "values": ["honor", "craft", "family"],
    "quirks": ["always mentions the weather"]
  },
  "inventory": [
    { "item": "iron_sword", "price": 50, "quantity": 2 },
    { "item": "shield", "price": 30, "quantity": 1 }
  ]
}

{
  "type": "player_dialogue",
  "playerId": "player_joe",
  "message": "Do you have any swords for sale?",
  "context": {
    "location": "blacksmith_shop",
    "timeOfDay": "morning",
    "weather": "sunny",
    "playerReputation": 75,
    "playerLevel": 12
  }
}

{
  "response": {
    "dialogue": "Aye lad, got a fine iron blade. Fifty gold.",
    "emotion": "cheerful",
    "action": { "type": "gesture", "target": "display_rack" },
    "tradeOffer": { "item": "iron_sword", "price": 45 },
    "memoryUpdated": true
  },
  "tokenUsage": { "input": 1200, "output": 85, "calls": 1 }
}

{ "action": "event", "data": { "type": "player_dialogue", "npcId": "...", "message": "...", "context": {...} } }
{ "action": "subscribe", "npcIds": ["npc1", "npc2"] }

curl -X PATCH http://localhost:18542/api/npcs/{npcId} \
  -H "x-api-key: your-key" \
  -H "x-game-id: my-game" \
  -H "Content-Type: application/json" \
  -d '{"location": "town_square", "mood": {"emotion": "angry", "intensity": 0.8, "cause": "theft"}}'

curl -X POST http://localhost:18542/api/npcs/generate \
  -H "x-api-key: your-key" \
  -H "x-game-id: my-game" \
  -H "Content-Type: application/json" \
  -d '{"role": "merchant", "name": "Grok"}'

curl -X POST http://localhost:18542/api/npcs/generate-batch \
  -H "x-api-key: your-key" \
  -H "x-game-id: my-game" \
  -H "Content-Type: application/json" \
  -d '{"count": 5, "role": "guard"}'

{
  "events": [
    { "type": "player_dialogue", "npcId": "npc1", "playerId": "p1", "message": "Hello!", "context": {...} },
    { "type": "player_approached", "npcId": "npc2", "playerId": "p1", "context": {...} }
  ]
}

var client = new NPCEngineClient("http://localhost:18542", "key", "my-game");

// Talk to an NPC
var result = await client.Say(npcId, "player1", "Hello!", context);
Debug.Log(result.response.dialogue);

// AI-generate an NPC with full persona
var npc = await client.GenerateNPC(new GenerateNPCRequest { role = "merchant" });

// Batch-generate NPCs with relationships
var batch = await client.GenerateBatch(new GenerateBatchRequest { count = 5, role = "guard" });

// Send batch events
var results = await client.SendBatchEvents(new BatchEventItem[] { ... });

// Create client
UNPCEngineClient* Client = NewObject<UNPCEngineClient>();
Client->Init("http://localhost:18542", "key", "my-game");

// Bind response delegate
Client->OnEventResult.AddDynamic(this, &AMyActor::OnNPCResponse);

// Talk to an NPC
FGameContext Context;
Context.Location = "blacksmith_shop";
Context.TimeOfDay = "morning";
Client->Say(NpcId, "player1", "Got any swords?", Context);

// AI-generate an NPC
FGenerateNPCRequest GenReq;
GenReq.Role = "merchant";
Client->GenerateNPC(GenReq);

var client = AINPCEngineClient.new()
client.setup("http://localhost:18542", "key", "my-game")
add_child(client)

# Talk to an NPC
var context = AINPCModels.game_context("blacksmith", "morning", "sunny")
var result = await client.say(npc_id, "player1", "Got any swords?", context)
print(result.response.dialogue)

# AI-generate an NPC
var npc = await client.generate_npc("merchant", "Grok")

# Batch-generate NPCs with relationships
var batch = await client.generate_batch(5, "guard")

[dependencies]
ainpc-sdk = { git = "https://github.com/jyswee/ainpc-rust-sdk.git" }

const API = "https://ainpcengine.com/api";
const HEADERS = {
  "Content-Type": "application/json",
  "x-api-key": "your-api-key",
  "x-game-id": "my-game"
};

// Create an NPC
const npc = await fetch(`${API}/npcs`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    name: "Grok", role: "blacksmith",
    personality: {
      traits: ["gruff", "loyal"],
      speechStyle: "blunt, short sentences",
      backstory: "Third-gen smith",
      values: ["craftsmanship", "honor"],
      quirks: []
    }
  })
}).then(r => r.json());

// Talk to the NPC
const result = await fetch(`${API}/npcs/${npc.id}/event`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    type: "player_dialogue",
    playerId: "player_1",
    message: "Got any swords?",
    context: { location: "forge", timeOfDay: "morning" }
  })
}).then(r => r.json());

console.log(result.response.dialogue);

npm install -g ainpc-cli

# Setup
ainpc login --key YOUR_KEY --game my-rpg

# Create NPC
ainpc create "Grok" --role merchant --traits gruff,loyal

# Talk to NPC
ainpc say NPC_ID "Got any swords?"

# AI-generate full NPC (NPC Persona)
ainpc generate --role guard

# List all NPCs
ainpc list

# NPC voice synthesis
ainpc speak NPC_ID "Welcome, traveler"

# Full reference
ainpc --help