AINPCEngine + Codex (Copilot)

1 Set environment variables

Add to your .env file:

CopyAINPCENGINE_API_URL=https://ainpcengine.com
AINPCENGINE_API_KEY=your-api-key-here
GAME_ID=my-game

Get a free API key at ainpcengine.com/auth/register — 1 NPC, 1000 interactions/month, no card.

2 Add to AGENTS.md

Paste this integration block into your project's AGENTS.md:

Copy# AINPCEngine Integration
# AI-powered NPCs with persistent memory, personality, and multi-agent intelligence.
# API: ${AINPCENGINE_API_URL} — Auth: x-api-key + x-game-id headers on EVERY request.

## Create NPC
POST /api/npcs with: name, role, personality: {traits[], speechStyle, backstory, values[]}
Optional: faction, location, inventory[{item, price, quantity}]

## Send Game Event (this is the main interaction)
POST /api/npcs/:npcId/event with: type, playerId, message, context: {location, timeOfDay, weather, playerReputation, playerLevel}
Returns: {response: {dialogue, emotion, action, tradeOffer, questUpdate}, tokenUsage}

## Event Types
player_approached, player_dialogue, player_left, combat_started, combat_ended,
trade_requested, trade_completed, quest_accepted, quest_completed, quest_failed,
ambient_trigger, world_event, npc_interaction

## NPC Persona (AI-generate full NPC)
POST /api/npcs/generate with: {role, name} → returns persona (OCEAN), schedule, psychology

## Other Endpoints
GET /api/npcs — list NPCs | GET /api/npcs/:id — single NPC
PATCH /api/npcs/:id — update | DELETE /api/npcs/:id — delete
POST /api/events — batch (up to 50) | POST /api/npcs/generate-batch — batch generate
GET /api/health — healthcheck | GET /api/stats — expert registry

## WebSocket (real-time)
ws://host/ws?apiKey=KEY&gameId=GAME
Send: {"action":"event","data":{type,npcId,playerId,message,context}}
Send: {"action":"subscribe","npcIds":["npc1","npc2"]}

## SDK Install
Unity: Copy sdk/unity/ → Assets/Plugins/AINPCEngine/
Unreal: Copy sdk/unreal/AINPCEngine/ → Plugins/
Godot: Copy sdk/godot/addons/ainpcengine/ → addons/

## Headers (EVERY request)
x-api-key: ${AINPCENGINE_API_KEY}
x-game-id: ${GAME_ID}
Content-Type: application/json

3 Try it

Ask your agent:

Copy"Create a gruff blacksmith NPC named Grok who remembers players"
"Send a dialogue event to Grok: 'Got any swords?'"
"Generate 5 guard NPCs with the NPC Persona"
"List all NPCs in my game"
"What event types can I send to an NPC?"

4 Clone a demo project

Full working demos with 3D village, 3 NPCs, dialogue UI, and the SDK pre-installed:

Copy# Unity (2022.3+)
git clone https://github.com/jyswee/ainpc-unity-demo.git

# Unreal (UE 5.3+)
git clone https://github.com/jyswee/ainpc-unreal-demo.git

# Godot (4.2+)
git clone https://github.com/jyswee/ainpc-godot-demo.git

5 Event types reference