API Documentation

{
  "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")