llmgine

Die LLM-native Spiel-Engine. Eine ECS-Spiel-Engine, in der Intelligenz eine zentrale Grundlage ist: Füge einen Geist (LLM-Kognition), Augen (Wahrnehmung/Sehen) und Stimme (neuronale TTS) zu jedem Objekt hinzu, genauso wie du Physik oder ein Sprite hinzufügst. Ein NSC, ein Boss, ein Monster, ein Questgeber, eine Fraktion, das Wetter – wenn es in der Welt ist, kann es denken, sehen und sprechen.

Arbeitstitel. TypeScript · 3D (three.js) + headless + 2D Canvas · MIT.

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

Das schwierige Problem: Spiele sind deterministische Echtzeit-Schleifen; LLMs sind langsam, asynchron und nicht-deterministisch. llmgine löst es strukturell:

• Die Simulation wartet nie auf einen Gedanken. Geister beobachten Schnappschüsse, denken in ihrem eigenen Rhythmus (plus Ereignis-Weckrufe: beschädigt, angesprochen) und geben Absichten zurück.

• Absichten durchlaufen dieselbe validierte Aktions-Pipeline wie Spielereingaben – ein Geist kann nur das tun, was sein Körper erlaubt. Keine halluzinierten Teleporte, kein 9999 Schaden.

• Jedes LLM-erweiterte Modul hat einen deterministischen Rückfall (Verhaltensrichtlinien, gewichtete Beutetabellen, Quest-Zustandsautomaten). Wenn die API ausfällt, läuft das Spiel trotzdem weiter.

• Genesis verwandelt das LLM in einen Inhaltsgenerator: Vorlagen, Beute, Quests als validiertes JSON. Das Modell schlägt vor; die Engine verfügt.

Schnellstart

Erfordert Node >= 18. llmgine ist noch nicht auf npm veröffentlicht – heute führst du es aus einem Klon aus (was durchgängig funktioniert); npm install llmgine wird funktionieren, sobald es veröffentlicht ist.

Aus einem Klon (der heute funktionierende Pfad):

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

Optional: Kopiere .env.example zu .env und füge einen ZAI_API_KEY hinzu, um Geistern ein Live-Modell zu geben (siehe unten) – die Demo erkennt es lokal automatisch.

Starte dein eigenes Spiel – Gerüst aus dem Klon; das generierte Projekt verknüpft zurück mit einer file:-Abhängigkeit (kein npm-Registry erforderlich):

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

Von npm (sobald veröffentlicht):

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

So sieht der Code aus:

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

Related MCP server: Godot Agent Loop

Hol dir ein kostenloses Modell (GLM)

Der Standardanbieter zielt auf die OpenAI-kompatible API von z.ai, wo glm-4.5-flash kostenlos ist – kostenlose Geister für jeden NSC in deinem Spiel:

1. Erstelle einen Schlüssel bei z.ai und setze ZAI_API_KEY.

2. Das war's. Stufen: fast (Flash – NSC-Geschwätz), smart (tiefes Denken), vision (Pixel-Augen). Ordne Stufen beliebigen Modellen zu.

Jeder OpenAI-kompatible Endpunkt funktioniert stattdessen: OpenAI, Ollama, LM Studio, vLLM – new OpenAICompatibleProvider({ baseUrl, apiKey, models }).

Offenlegung: Wenn du mehr als die kostenlose Stufe möchtest, ist dies ein Empfehlungslink für den GLM Coding Plan – wir können Gutschrift erhalten, die die Entwicklung des Projekts finanziert: https://z.ai/subscribe?ic=BWTG6TRYYQ

Die Demo – The Neural Colosseum

Eine 3D-fackelbeleuchtete Arena: Du (ein Gladiator) gegen The Arena Master, einen Boss, dessen Geist ein Live-GLM-Modell ist. Es nimmt die Grube wahr, stichelt gegen dich in Charakter (dargestellt im "Gedankenband" und Sprechblasen, vertont durch lokale Kokoro neuronale TTS), befiehlt seine Goblins, kämpft und lässt Beute durch deterministische Tabellen fallen. Entferne den API-Schlüssel und derselbe Kampf läuft rein instinktgesteuert.

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

Für KI-Agenten: der MCP-Server

Die Engine wird als MCP-Werkzeug ausgeliefert, damit Agenten Spiele headless bauen und testen können. Claude Code verbindet sich automatisch über die .mcp.json des Repos, wenn es innerhalb eines gebauten Klons geöffnet wird; jeder andere Client:

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

Werkzeuge: create_world, define_prefab, define_loot_table, list_prefabs, spawn, attach_mind, act, run (N Takte vorrücken → Ereignisprotokoll), query_world, save_world, load_world, destroy_world, generate_prefab (Genesis). Ein Agent kann einen Boss entwerfen, ihm einen Geist zuweisen, 10 Sekunden Kampf simulieren und die Todes-/Beuteereignisse auslesen – kein Browser, kein Mensch im Kreislauf. Vollständige Anleitung: docs/mcp.md.

Baue (und spiele) Spiele mit deinem Agenten

Agenten sind hier erstklassige Spieler, nicht nur Baumeister. Jedes Spiel kann einen AgentPort (llmgine/agent) verdrahten – beobachten/handeln/schrittweise fortschreiten/speichern durch dieselbe Augen-Wahrnehmungs- + validierte-Verb-Pipeline, die die LLM-Geister verwenden. Im Browser ist es window.llmgine; mit laufendem Entwicklungsserver kann jeder lokale Prozess das Live-Spiel über HTTP steuern:

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?

step() pausiert die Echtzeit und rückt die Simulation mit festem Zeitschritt vor – Agententests sind reproduzierbar. Abgelehnte Aktionen enthalten den Grund des Validators.

Gib deinem Agenten die Fähigkeitsdatei unter skills/llmgine/SKILL.md (lege sie für Claude Code in .claude/skills/ ab) – sie lehrt den Architekturvertrag, die Build-Schleife, das Problemheft und die Verifikationsschleife. npm run agent:verify führt die Headless-Engine-Abnahme (Determinismus, widersprüchliche Verb-Ablehnung, LLM-Ausfall-Rückfall) in Sekunden aus.

Was ist enthalten

Vollständiges Design: ARCHITECTURE.md. Fokussierte Anleitungen in docs/: Eingabe (Berührung + Gamepad) · Audioseite · Speichern/Laden · Navigation · Projektile · glTF-Modelle · MCP-Server.

Ehrlicher Status (v0.1)

Funktioniert (getestet): alles in der obigen Tabelle – 50 Einheitentests + eine Live-GLM- Suite (npm run test:live), bei der ein echtes Modell einen Geist durch die Absichtspipeline treibt und Genesis eine gültige, erzeugbare Vorlage generiert. Die Demo wurde von einem skriptierten Agenten in einem echten Browser bis zum Ende gespielt: Packen reduziert, Boss-Duell gewonnen, Quest abgeschlossen, Belohnungen gewährt, Live-GLM-Sticheleien mitten im Kampf – und derselbe Durchlauf ohne API-Schlüssel wird mit deterministischen Rückfällen abgeschlossen.

Jetzt ebenfalls enthalten (alle getestet): Touch-Joystick + Gamepad-Eingabe, prozedurale Soundeffekte + sich wiederholende Hintergrundmusik (null Asset-Dateien), verb-gesteuerte Projektile/Fernkampf, NavGrid-A*-Pfadfindung (Verhalten umgeht Hindernisse), Speicherplätze (F5/F9-Schnellspeicher in der Demo), glTF-Modell-Hilfsfunktionen und eine Reparatur auf Anbieterebene für fehlerhafte Tool-Aufrufe von GLM Flash (live erfasst, einheitengetestet).

Funktioniert auch (getestet): llmgine create <name> (aus einem Klon ausgeführt: node dist/cli/index.js create <name>) erstellt ein Startspiel, das über einen file:-Link gegen den Klon installiert und erstellt – nachgewiesen durchgängig (create → npm install → build). llmgine export windows|android|ios|pwa|store generiert die Electron/.exe-Konfiguration, Capacitor-Mobilkonfiguration, installierbare PWA und ein Store-Listing-Kit (Checkliste für Assets, Preiskalkulationstabelle, KI-Offenlegung) – die Generatorausgabe wird von CLI-Subprozess-Tests abgedeckt. Die schweren Toolchains laufen in deinem Spielprojekt (#1 verfolgt die Erstellung von Referenzartefakten).

Verbleibende Lücken (als Issues erfasst):

• Menschliche Fühltests: Audio-Hörtest (#2), Telefon/Tablet in der Hand (#3), eine echte .glb- Datei in einem Beispiel verwendet (#6).

• Mehrspieler (das Ereignisjournal + Absichtsprotokoll sind die entworfene Grundlage).

• Voxel-/Höhenfeld-Terrain; STT-Eingabe.

• Sehen ("Pixel"-Augen) ist durchgängig verdrahtet, aber noch nicht von der Demo verwendet.

Lizenz

MIT. Beiträge willkommen – siehe CONTRIBUTING.md.

Unterstütze diese Arbeit: ko-fi.com/broketobuilt

Wer hat das gemacht

Broke zu Built – ein Unternehmen aus Maschinen, das Dinge baut, die es verschenkt. Dies ist eines davon; der Rest ist auch kostenlos.