YGYOOO/WorldX

One sentence, One living world.

English | 中文

AI Agents · LLM · Procedural Generation · Simulation · Emergent Narrative

Powered by Atlas Cloud

Atlas Cloud provides WorldX with a single OpenAI-compatible API for both LLM (story & character generation) and image generation (maps, character visuals) — 59 curated LLM models + 300+ image/video models under one key.

Quick setup — all 4 WorldX roles via Atlas Cloud:

# Orchestrator — world design & character rules
ORCHESTRATOR_BASE_URL=https://api.atlascloud.ai/v1
ORCHESTRATOR_API_KEY=<your-atlascloud-key>
ORCHESTRATOR_MODEL=deepseek-ai/deepseek-v4-pro   # strong reasoning; max_tokens ≥ 512

# Image Generation — map art & character sprites (openai-compatible)
IMAGE_GEN_BASE_URL=https://api.atlascloud.ai/v1
IMAGE_GEN_PROVIDER=openai-compatible
IMAGE_GEN_API_KEY=<your-atlascloud-key>
IMAGE_GEN_MODEL=black-forest-labs/FLUX.1-dev

# Vision Review — map quality & region detection
VISION_BASE_URL=https://api.atlascloud.ai/v1
VISION_API_KEY=<your-atlascloud-key>
VISION_MODEL=qwen/qwen2.5-vl-72b-instruct

# Simulation Engine — character decisions & dialogue (any model works)
SIMULATION_BASE_URL=https://api.atlascloud.ai/v1
SIMULATION_API_KEY=<your-atlascloud-key>
SIMULATION_MODEL=deepseek-ai/deepseek-v3-turbo   # cost-effective for high-volume calls

Note: Set max_tokens ≥ 512 for Orchestrator and Vision calls to avoid truncated world designs.

Get your free key → atlascloud.ai/console/coding-plan · Browse all models → atlascloud.ai/models

WorldX turns a single text prompt into a fully autonomous AI world. The system designs the world, generates original maps and character art, then runs a living simulation where AI agents make decisions, form relationships, have conversations, and create emergent narratives — all without human intervention.

"A cozy autumn mountain village with a blacksmith, a tavern owner, a wandering monk, and a curious child"

That's all it takes. WorldX handles the rest.

Highlights

• One-sentence world creation — describe any scenario and watch it materialize
• AI-generated maps & characters — original art created to match your description, not templates
• Autonomous agent simulation — characters make decisions, form relationships, hold conversations
• Memory & personality — agents remember past events and act according to distinct personalities
• Multi-day evolution — worlds evolve across day/night cycles with scene transitions
• God mode — broadcast events, edit character profiles/memories, run sandbox chats with characters, and observe emergent developments
• Timeline system — branch, replay, and compare different simulation runs
• Bilingual UI — Chinese / English interface with one-click switching

🚧 The project is currently in Alpha — core features work, ongoing improvements ahead

Quick Start

Prerequisites

• Node.js 22.13+ (24 LTS recommended) — the database uses Node's built-in SQLite (node:sqlite), so installing dependencies requires no native module compilation. The full supported range is >=22.13 <23 || >=23.4: 22.5–22.12 and 23.0–23.3 will not work, as node:sqlite was still behind the --experimental-sqlite flag on those versions
• API keys — see Model Configuration below

Option A: Preview Mode (fastest)

Just want to see WorldX in action? Two pre-built worlds are included. You only need a Simulation model key.

git clone https://github.com/YGYOOO/WorldX.git
cd WorldX
cp .env.example .env
# Edit .env — fill in SIMULATION_* fields only
npm install
npm run dev

Open http://localhost:3200 — pick a pre-built world and hit Play.

Option B: Full Creation

Generate your own worlds from scratch. Requires all 4 model keys.

# Edit .env — fill in all 4 model sections
npm run dev

Open http://localhost:3200/create, type a sentence, and watch your world come to life.

Or use the CLI:

npm run create -- "A cyberpunk noodle shop where hackers and androids share rumors"

Model Configuration

WorldX uses 4 model roles, each configurable independently. All roles use the OpenAI-compatible chat/completions protocol except Image Gen, which can also use Google AI Studio's native image API.

Each role usually needs 3 env vars:

{ROLE}_BASE_URL=https://openrouter.ai/api/v1    # API base URL
{ROLE}_API_KEY=sk-or-v1-xxxx                     # API key
{ROLE}_MODEL=google/gemini-3.1-pro-preview       # Model identifier

Image Gen can additionally set IMAGE_GEN_PROVIDER. IMAGE_GEN_PROVIDER can be openai-compatible (default, for OpenRouter) or google-native (for Google AI Studio image generation).

Platform Examples

ORCHESTRATOR_BASE_URL=https://api.atlascloud.ai/v1
ORCHESTRATOR_API_KEY=<your-atlascloud-key>
ORCHESTRATOR_MODEL=deepseek-ai/deepseek-v4-pro

IMAGE_GEN_BASE_URL=https://api.atlascloud.ai/v1
IMAGE_GEN_PROVIDER=openai-compatible
IMAGE_GEN_API_KEY=<your-atlascloud-key>
IMAGE_GEN_MODEL=black-forest-labs/FLUX.1-dev

VISION_BASE_URL=https://api.atlascloud.ai/v1
VISION_API_KEY=<your-atlascloud-key>
VISION_MODEL=qwen/qwen2.5-vl-72b-instruct

SIMULATION_BASE_URL=https://api.atlascloud.ai/v1
SIMULATION_API_KEY=<your-atlascloud-key>
SIMULATION_MODEL=deepseek-ai/deepseek-v3-turbo

ORCHESTRATOR_BASE_URL=https://openrouter.ai/api/v1
ORCHESTRATOR_API_KEY=sk-or-v1-xxxx
ORCHESTRATOR_MODEL=google/gemini-3.1-pro-preview

IMAGE_GEN_BASE_URL=https://openrouter.ai/api/v1
IMAGE_GEN_PROVIDER=openai-compatible
IMAGE_GEN_API_KEY=sk-or-v1-xxxx
IMAGE_GEN_MODEL=google/gemini-3.1-flash-image-preview

VISION_BASE_URL=https://openrouter.ai/api/v1
VISION_API_KEY=sk-or-v1-xxxx
VISION_MODEL=google/gemini-3.1-pro-preview

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

ORCHESTRATOR_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
ORCHESTRATOR_API_KEY=AIzaSy...
ORCHESTRATOR_MODEL=gemini-3.1-pro-preview

IMAGE_GEN_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
IMAGE_GEN_PROVIDER=google-native
IMAGE_GEN_API_KEY=AIzaSy...
IMAGE_GEN_MODEL=gemini-3.1-flash-image-preview

VISION_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
VISION_API_KEY=AIzaSy...
VISION_MODEL=gemini-3.1-pro-preview

SIMULATION_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
SIMULATION_API_KEY=AIzaSy...
SIMULATION_MODEL=gemini-2.5-flash-preview

# World design — Google AI Studio
ORCHESTRATOR_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
ORCHESTRATOR_API_KEY=AIzaSy...
ORCHESTRATOR_MODEL=gemini-3.1-pro-preview

# Art generation — Google AI Studio
IMAGE_GEN_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
IMAGE_GEN_PROVIDER=google-native
IMAGE_GEN_API_KEY=AIzaSy...
IMAGE_GEN_MODEL=gemini-3.1-flash-image-preview

# Vision review — Google AI Studio
VISION_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
VISION_API_KEY=AIzaSy...
VISION_MODEL=gemini-3.1-pro-preview

# Simulation — DeepSeek (cost-effective for high-volume runtime calls)
SIMULATION_BASE_URL=https://api.deepseek.com/v1
SIMULATION_API_KEY=sk-...
SIMULATION_MODEL=deepseek-chat

Architecture

Project Structure

WorldX/
├── orchestrator/         # LLM-driven world design & config generation
│   ├── src/
│   │   ├── index.mjs           # Pipeline entry: sentence → world
│   │   ├── world-designer.mjs  # LLM world design
│   │   └── config-generator.mjs
│   └── prompts/
│       └── design-world.md     # World design prompt template
├── generators/           # Art generation pipelines
│   ├── map/              # Map generation (multi-step with review loop)
│   └── character/        # Spritesheet generation (with chromakey)
├── server/               # Simulation engine (Express + SQLite + LLM)
│   └── src/
│       ├── core/         # WorldManager, CharacterManager
│       ├── simulation/   # SimulationEngine, DecisionMaker, DialogueGenerator
│       ├── llm/          # LLMClient, PromptBuilder
│       └── store/        # SQLite persistence (per-timeline)
├── client/               # Game client (Phaser 3 + React 19)
│   └── src/
│       ├── scenes/       # BootScene, WorldScene
│       ├── ui/           # React overlay panels
│       └── systems/      # Camera, Pathfinding, Playback
├── shared/               # Shared utilities (structured output parsing)
├── library/worlds/       # Pre-built example worlds
├── output/worlds/        # Your generated worlds
└── .env.example          # Configuration template

Development

npm run dev          # Start both client and server in dev mode
npm run create       # Generate a new world via CLI

• Client: http://localhost:3200
• Server: http://localhost:3100

Thanks

• LinuxDO

License

MIT