deterministic 60 Hz ECS sim  ←— validated intents —— async LLM minds
        │                                                  ▲
        └—————— perception snapshots + pixel vision ———————┘

git clone https://github.com/lordbasilaiassistant-sudo/llmgine
cd llmgine
npm install
npm run build       # engine → dist/
npm test            # unit tests, no network (pretest rebuilds dist/ automatically)
npm run demo        # the 3D arena demo → http://localhost:4173

node dist/cli/index.js create my-game    # from the clone root
cd my-game && npm install && npm run dev # http://localhost:4173

npm install llmgine        # not yet — 404s today, tracked for a deliberate release
npx llmgine create my-game

import {
  World, GameLoop, SpatialGrid, ActionRegistry, actionSystem,
  Transform, Velocity, Named, Health, Speech, Behavior,
  STANDARD_VERBS, behaviorSystem, movementSystem,
  Mind, MindMemory, CognitionDriver, OpenAICompatibleProvider,
} from "llmgine";

const world = new World(42);            // seeded — deterministic
const grid = new SpatialGrid();
const actions = new ActionRegistry();
for (const v of STANDARD_VERBS) actions.register(v);

// any entity + Mind = intelligent entity
const guard = world.create();
world.add(guard, Transform, { x: 0, y: 0 });
world.add(guard, Velocity);
world.add(guard, Named, { name: "Gate Guard" });
world.add(guard, Health);
world.add(guard, Speech);
world.add(guard, Behavior, { mode: "idle" });
world.add(guard, Mind, {
  persona: "A vigilant town guard. Suspicious of strangers.",
  goals: ["guard the gate"],
  thinkEvery: 8,                        // seconds between thoughts
  fallbackMode: "wander",               // deterministic policy if the LLM is unavailable
});
world.add(guard, MindMemory);

const driver = new CognitionDriver({
  provider: new OpenAICompatibleProvider(),   // reads ZAI_API_KEY / LLM_API_KEY + LLM_BASE_URL
  actions, grid,
});
world.addSystem(actionSystem(actions));
world.addSystem(behaviorSystem());
world.addSystem(movementSystem(grid));
world.addSystem(driver.system());

new GameLoop(world).start();            // browser; or loop.advance(n) headless

git clone https://github.com/lordbasilaiassistant-sudo/llmgine
cd llmgine && npm install
npm run demo        # http://localhost:4173 — auto-detects ZAI_API_KEY locally

{ "mcpServers": { "llmgine": { "command": "node", "args": ["<path-to-clone>/dist/mcp/server.js"], "env": { "ZAI_API_KEY": "…" } } } }

curl -s localhost:4173/agent/call -d '{"method":"observe"}'
curl -s localhost:4173/agent/call -d '{"method":"act","args":["move_to",{"x":0,"y":-100}]}'
curl -s localhost:4173/agent/call -d '{"method":"step","args":[120]}'   # deterministic 2s
curl -s localhost:4173/agent/call -d '{"method":"actionLog"}'           # why was my verb rejected?