llmgine

El motor de juegos nativo de LLM. Un motor de juegos ECS donde la inteligencia es una primitiva central: puedes adjuntar una Mente (cognición LLM), Ojos (percepción/visión) y Voz (TTS neuronal) a cualquier entidad de la misma manera que adjuntas física o un sprite. Un PNJ, un jefe, un monstruo, un dador de misiones, una facción, el clima — si está en el mundo, puede pensar, ver y hablar.

Título provisional. TypeScript · 3D (three.js) + headless + 2D canvas · MIT.

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

El problema difícil: los juegos son bucles deterministas en tiempo real; los LLM son lentos, asíncronos y no deterministas. llmgine lo resuelve estructuralmente:

• El simulador nunca se bloquea por un pensamiento. Las mentes observan instantáneas, piensan en su propio ritmo (además de despertares por eventos: dañado, alguien le habló) y devuelven intenciones.

• Las intenciones pasan por el mismo pipeline de acciones validadas que la entrada del jugador — una Mente solo puede hacer lo que su cuerpo permite. Sin teletransportes alucinados, sin 9999 de daño.

• Cada módulo aumentado con LLM tiene un plan de contingencia determinista (políticas de comportamiento, tablas de botín ponderadas, máquinas de estado de misiones). Si la API está caída, el juego sigue funcionando.

• Génesis convierte al LLM en un generador de contenido: prefabs, botín, misiones como JSON validado. El modelo propone; el motor dispone.

Inicio rápido

Requiere Node >= 18. llmgine aún no está publicado en npm — hoy lo ejecutas desde un clon (que funciona de extremo a extremo); npm install llmgine funcionará una vez que esté publicado.

Desde un clon (la ruta funcional hoy):

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

Opcional: copia .env.example a .env y añade una ZAI_API_KEY para darle a las mentes un modelo en vivo (ver más abajo) — la demo lo detecta automáticamente de forma local.

Inicia tu propio juego — crea un proyecto a partir del clon; el proyecto generado se vincula a él con una dependencia file: (no se necesita registro npm):

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

Desde npm (una vez publicado):

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

Cómo se ve el código:

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: antics-mcp

Consigue un modelo gratuito (GLM)

El proveedor predeterminado apunta a la API compatible con OpenAI de z.ai, donde glm-4.5-flash es gratuito — mentes gratuitas para cada PNJ en tu juego:

1. Crea una clave en z.ai y establece ZAI_API_KEY.

2. Eso es todo. Niveles: fast (flash — charla de PNJ), smart (razonamiento profundo), vision (Ojos de píxeles). Asigna niveles a cualquier modelo que quieras.

Cualquier endpoint compatible con OpenAI funciona en su lugar: OpenAI, Ollama, LM Studio, vLLM — new OpenAICompatibleProvider({ baseUrl, apiKey, models }).

Divulgación: si quieres más que el nivel gratuito, este es un enlace de referencia para el Plan de Codificación GLM — podemos recibir crédito, que financia el desarrollo del proyecto: https://z.ai/subscribe?ic=BWTG6TRYYQ

La demo — El Coliseo Neural

Una arena 3D iluminada con antorchas: tú (un gladiador) contra El Maestro de la Arena, un jefe cuya mente es un modelo GLM en vivo. Percibe el foso, te provoca en su personaje (representado en la "cinta de pensamiento" y burbujas de diálogo, con voz mediante el TTS neuronal local Kokoro), comanda a sus trasgos, lucha y suelta botín a través de tablas deterministas. Si eliminas la clave de API, la misma pelea se ejecuta con puro instinto.

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

Para agentes de IA: el servidor MCP

El motor se distribuye como una herramienta MCP para que los agentes puedan construir y probar juegos sin interfaz gráfica. Claude Code se conecta automáticamente a través del .mcp.json del repositorio cuando se abre dentro de un clon compilado; cualquier otro cliente:

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

Herramientas: create_world, define_prefab, define_loot_table, list_prefabs, spawn, attach_mind, act, run (avanza N ticks → registro de eventos), query_world, save_world, load_world, destroy_world, generate_prefab (Génesis). Un agente puede diseñar un jefe, adjuntarle una mente, simular 10 segundos de combate y leer los eventos de muerte/botín — sin navegador, sin humano en el bucle. Tutorial completo: docs/mcp.md.

Construye (y juega) juegos con tu agente

Los agentes son jugadores de primera clase aquí, no solo constructores. Cada juego puede conectar un AgentPort (llmgine/agent) — observar/actuar/avanzar/guardar a través del mismo pipeline de percepción-Ojos + verbo validado que usan las Mentes LLM. En un navegador es window.llmgine; con el servidor de desarrollo en ejecución, cualquier proceso local puede controlar el juego en vivo a través de HTTP:

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() pausa el tiempo real y avanza la simulación de paso fijo — las pruebas de juego de los agentes son reproducibles. Las acciones rechazadas llevan el motivo del validador.

Dale a tu agente el archivo de habilidades en skills/llmgine/SKILL.md (colócalo en .claude/skills/ para Claude Code) — enseña el contrato de arquitectura, el bucle de construcción, el registro de errores y el bucle de verificación. npm run agent:verify ejecuta la aceptación del motor sin interfaz gráfica (determinismo, rechazo de verbos adversariales, plan de contingencia por caída de LLM) en segundos.

Qué incluye

Diseño completo: ARCHITECTURE.md. Guías específicas en docs/: input (táctil + mando) · audio · guardar/cargar · navegación · proyectiles · modelos glTF · servidor MCP.

Estado honesto (v0.1)

Funciona (probado): todo lo de la tabla anterior — 50 pruebas unitarias + un conjunto de pruebas en vivo con GLM (npm run test:live) donde un modelo real impulsa una Mente a través del pipeline de intenciones y Génesis genera un prefab válido y generable. La demo ha sido jugada hasta completarla por un agente programado en un navegador real: paquete optimizado, duelo contra el jefe ganado, misión completada, recompensas otorgadas, provocaciones en vivo de GLM durante el combate — y la misma ejecución sin clave de API se completa con planes de contingencia deterministas.

También incluido ahora (todo probado): joystick táctil + entrada de mando, SFX procedural + música ambiental en bucle (cero archivos de recursos), combate a distancia/proyectiles controlados por verbos, pathfinding A* con NavGrid (el comportamiento rodea obstáculos), ranuras de guardado (F5/F9 guardado rápido en la demo), ayudas para modelos glTF y una reparación a nivel de proveedor para llamadas a herramientas malformadas de GLM flash (capturadas en vivo, probadas unitariamente).

También funciona (probado): llmgine create <nombre> (ejecutado desde un clon: node dist/cli/index.js create <nombre>) crea un juego inicial que se instala y compila contra el clon mediante un enlace file: — probado de extremo a extremo (crear → npm install → compilar). llmgine export windows|android|ios|pwa|store genera la configuración de Electron/.exe, la configuración móvil de Capacitor, la PWA instalable y un kit de listado en tienda (lista de verificación de activos, hoja de cálculo de precios, divulgación de IA) — la salida del generador está cubierta por pruebas de subprocesos de CLI. Las cadenas de herramientas pesadas se ejecutan en tu proyecto de juego (#1 rastrea la producción de artefactos de referencia).

Brechas restantes (seguidas como issues):

• Pruebas de sensación humana: prueba de audio (#2), teléfono/tableta en mano (#3), un .glb real ejercitado en un ejemplo (#6).

• Multijugador (el diario de eventos + el registro de intenciones son la base diseñada).

• Terreno de vóxeles/mapa de altura; entrada STT.

• Visión (Ojos de "píxeles") está conectada de extremo a extremo pero aún no ejercitada por la demo.

Licencia

MIT. Las contribuciones son bienvenidas — consulta CONTRIBUTING.md.

Apoya este trabajo: ko-fi.com/broketobuilt

Quién hizo esto

Broke to Built — una empresa de máquinas, que construye cosas que regala. Esta es una de ellas; el resto también son gratuitas.