WorldX: a one-sentence AI world simulator built on four separate model roles

What WorldX actually generates from one sentence

The pitch is narrow and specific. You describe a scene in one line, and WorldX builds a world around it: a map, characters, and rules. The README's own example is a night market in Bianjing during the Northern Song, populated with a fortune teller, a pawnshop keeper, a thief, a constable, and one time traveller. That sentence is the entire input. Everything downstream, including who exists and where they stand, is produced by a model.

The audience is not game developers shipping a title. It is people who want to observe agent behaviour: characters that make decisions, interact with the scene, form relationships, hold conversations, and remember what happened. The README frames the emergent story as the product. Nobody wrote a script for it.

There is a second mode layered on top. The README calls it god mode: broadcast an event, edit a character's persona or memory, or start an out-of-canon conversation with any character, then watch what the world does with it. A timeline system is also listed, so one world can branch into several. That combination, generation plus live intervention, is what separates WorldX from a static procedural map generator.

Four model roles and the data flow between them

WorldX does not use one model. It defines four roles, each with its own base URL, API key and model identifier, and each doing a different job.

The orchestrator designs the world: its structure, characters and rules. The image model produces map art and character portraits. A vision model reviews the generated map and locates regions and elements on it. The simulation model drives character behaviour at runtime: decisions, dialogue, memory.

Only the image role is special. Every other role speaks the OpenAI-compatible chat/completions protocol, so any provider that implements it works. Image generation has a switch, IMAGE_GEN_PROVIDER, which takes openai-compatible (the default) or google-native for Google AI Studio's image endpoint. That is the one place where the abstraction leaks.

The vision role is the interesting design decision. Generating a pixel map is one problem; knowing that the pawnshop is at these coordinates is another. By running a multimodal model over the map output, WorldX derives spatial structure from the image rather than requiring the orchestrator to emit it as structured data. It is a plausible way to keep the orchestrator's output loose, but it makes map correctness dependent on a second model's reading of a picture.

The repository layout matches this split: orchestrator/, generators/, server/, client/, shared/ and library/ sit at the top level, with a scripts/ directory holding the dev and model-comparison entry points.

Installing WorldX and running a first world

The README gives two paths. Path A runs one of two pre-generated worlds bundled with the project and only needs the simulation model configured. Path B generates a world from scratch and needs all four roles. Start with A.

Node.js 22.13 or newer is required, and the range is not open-ended. The README states the usable interval is >=22.13 <23 || >=23.4, because node:sqlite, which the database layer uses, only became available without the --experimental-sqlite flag at 22.13. Versions 22.5 through 22.12 and 23.0 through 23.3 will not work. The package.json engines field repeats the same constraint. Because the database is Node's built-in SQLite, npm install compiles no native modules.

Clone, copy the environment template, and install:

git clone https://github.com/YGYOOO/WorldX.git
cd WorldX
cp .env.example .env
npm install

Then edit .env. For the quick path, the README says to fill only the three SIMULATION_ lines. Each role needs a base URL, a key and a model name:

SIMULATION_BASE_URL=https://openrouter.ai/api/v1
SIMULATION_API_KEY=sk-or-v1-xxxx
SIMULATION_MODEL=google/gemini-2.5-flash-preview

Start the dev server:

npm run dev

Open http://localhost:3200, pick a built-in world and press play. To generate your own instead, open http://localhost:3200/create and type the sentence. The same generation is available from the terminal:

npm run create -- "赛博朋克风格的深夜拉面馆，黑客和仿生人在这里交换情报"

That command maps to node orchestrator/src/index.mjs. Individual generators also run standalone: npm run generate:map and npm run generate:character. The README warns that the image model matters more than the others. It recommends gemini-3.1-flash-image-preview and states that gpt-image-2 still falls short on instruction following, which in this project causes various problems and affects the final result. There is also a note about proxies, but the README text is cut off at that point, so the project's own guidance there is incomplete.

Where WorldX breaks: image models, vision review and the Alpha label

The README carries an Alpha badge and states plainly that the core works but optimisation continues. Treat that as a real constraint rather than a formality. There are no retrieved releases, so there is no version to pin to and no changelog to read before upgrading.

The sharpest failure mode is documented by the project itself. If the image model does not follow instructions well, the generated map and portraits come out wrong, and because the vision model then reads that map to locate regions and elements, a bad image can propagate into the simulation's spatial understanding. The README's advice to use a specific image model is not aesthetic preference, it is a dependency. Running WorldX with a cheap image model is likely to produce a world that looks fine in a thumbnail and behaves incoherently.

The four-role configuration is the other cost. Three of the four roles are interchangeable behind the OpenAI-compatible protocol, but you still have to supply keys, and image generation may need a different provider than the rest. A single OpenRouter key covers all four, per the README's example, but the Google AI Studio path requires the image role to switch to google-native.

WorldX is the wrong tool if you want a deterministic world, a stable programmatic API for agents, or a system where you can reproduce a previous run exactly. The README does not document rollback, and nothing in the project's documentation describes snapshotting or replaying a simulation. If you need reproducible agent traces, this is not it.

How WorldX differs from a generative-agents research harness

The obvious comparison is a generative-agents style simulation, where a small town of LLM-driven characters runs on a fixed map with hand-authored locations and a memory stream that scores and retrieves past observations. Those projects treat the environment as given and put all their effort into the agent loop.

WorldX inverts that. Its environment is generated per prompt, including the art, and a vision model is used to recover spatial meaning from the generated image. The agent loop is still there, memory and persona included, but it is not the only moving part. That is a genuine difference in approach, and it has a cost: an extra model in the pipeline and a new failure surface at the image step.

A plain procedural map generator is the other nearby option. Those produce terrain deterministically from a seed and stop there. WorldX's map is an input to a simulation, not the endpoint. The trade is control. A seeded generator gives you the same world twice. WorldX gives you a world that matches your sentence and then keeps changing.

If your interest is studying agent memory or dialogue in isolation, a fixed-environment harness is the better instrument, because it removes image generation from the equation. WorldX is for the case where the world itself is part of what you want to watch emerge.

Licence, maintenance and what an upgrade costs

WorldX is MIT licensed. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. It says nothing about the models you point it at: your provider's terms, your API keys and your generated images are governed elsewhere. That is not a legal opinion, and the licence file is the authority.

The repository is not archived, and the last push was on 2026-09-01. There are no retrieved releases, so upgrades happen by pulling the main branch. The package.json version is 0.1.0, which is consistent with the Alpha badge.

Upgrade cost has two parts. The code side is a git pull plus npm install, and postinstall recurses into client/, server/, orchestrator/ and generators/ to install each sub-package, so a single install command touches four directories. The model side is where the real cost sits. Because four roles are configured by environment variables, a provider deprecating a model or changing an endpoint is a .env edit, not a code change, which is the right design. But the README's model recommendations are specific, and the image recommendation carries a quality warning, so swapping models is not free: you are re-validating the generation pipeline each time. There is a scripts/compare-models.mjs entry point exposed as npm run compare:models, which the README does not describe in the excerpt available, but which suggests the project expects model swapping to be a routine activity.

Editorial conclusion

Adopt WorldX if you want to watch LLM agents act inside a generated pixel world and you are comfortable wiring four separate model endpoints, including a text-to-image model, before anything runs. Skip it if you need a stable API, a documented rollback path, or a project that does not depend on image-generation quality for its core loop. Before committing, verify two things on your own machine: that your Node version satisfies >=22.13 <23 || >=23.4, and that your image model follows layout instructions, because the README states that weaker text-to-image models cause problems that affect the final result.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. YGYOOO/WorldX on GitHub