GitPedia

WorldX

One sentence creates an AI-driven world — generate maps, characters, and watch stories emerge on their own. 一句话生成一个AI自主驱动的世界.

From YGYOOO·Updated June 24, 2026·View on GitHub·

AI Agents · LLM · Procedural Generation · Simulation · Emergent Narrative The project is written primarily in TypeScript, distributed under the MIT License license, first published in 2026. It has gained significant community traction with 1,109 stars and 182 forks on GitHub. Key topics include: agent, ai, ai-agents, ai-characters, ai-simulation.

<p align="center"> <img src="docs/logo.png" alt="WorldX logo:d" width="200" /> </p> <p align="center"> <!-- <h1 align="center">WorldX</h1> --> <p align="center"><strong>一句话，生成一个鲜活的 AI 世界。</strong></p> </p> <p align="center"> <a href="./README_EN.md">English</a> | 中文 </p> <p align="center"> <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <img src="https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white" alt="Node.js 18+"> <img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black" alt="React 19"> <img src="https://img.shields.io/badge/Phaser-3-cdf0e8?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJMMiAyMmgyMEwxMiAyeiIgZmlsbD0iIzMzMyIvPjwvc3ZnPg==" alt="Phaser 3"> <img src="https://img.shields.io/badge/Status-Alpha-orange" alt="Alpha"> <img src="https://img.shields.io/badge/PRs-Welcome-brightgreen.svg" alt="PRs Welcome"> </p> <p align="center"> <code>AI Agents</code> · <code>LLM</code> · <code>Procedural Generation</code> · <code>Simulation</code> · <code>Emergent Narrative</code> </p>

说出你的要求，WorldX 会为你构筑一个完整的虚拟世界。
AI 角色们会在这个世界里自主生活：他们做决策、与场景交互、建立关系、开展对话、记忆并思考，涌现出没人提前写好剧本的故事。
你也可以作为"上帝"随时介入 —— 注入事件、编辑角色记忆或人格，看整个世界因此走向何方。你也能与任意角色展开一场架空对话。

"北宋汴京的夜市街，有算命的、当铺掌柜、小偷、捕快，还有一个穿越来的现代人"

只需要这一句话，剩下的交给 WorldX。

<table> <tr> <td align="center" valign="top" width="50%"><img src="docs/screenshot1.png" alt="WorldX: one-sentence world creation interface" width="400"/></td> <td align="center" valign="top" width="50%"><img src="docs/screenshot2.png" alt="WorldX: pixel world simulation with character dialogue sidebar" width="400"/></td> </tr> <tr> <td align="center" valign="top" width="50%"><img src="docs/screenshot3.png" alt="WorldX: pixel world simulation with character dialogue sidebar" width="400"/></td> <td align="center" valign="top" width="50%"><img src="docs/screenshot2_en.png" alt="WorldX: one-sentence world creation interface" width="400"/></td> </tr> </table> <p align="center"> <a href="https://www.bilibili.com/video/BV1HNosBLEE5"> <img src="https://img.shields.io/badge/📺_观看演示视频-Bilibili-00A1D6?logo=bilibili&logoColor=white&style=for-the-badge" alt="Bilibili Demo Video"> </a> </p>

欢迎大家尝试并分享自己构建的世界😄

特性

  • 一句话创造世界 —— 描述任何场景，看着它变为现实
  • AI 生成地图与角色 —— 任何风格，完全按照你的要求生成，不是模板拼接
  • 自主 Agent 驱动 —— 生成的世界中，角色自主决策、建立关系、展开对话
  • 记忆与人格 —— 角色记住过去的经历，并据此形成独特的行为模式
  • 多日演化 —— 支持跨越昼夜循环持续演进
  • 上帝模式 —— 广播事件、编辑角色人设/记忆、与角色开展架空对话，观察世界中涌现出哪些有趣的发展
  • 时间线系统 —— 同一个世界也可孕育多个不同时间线
  • 中英双语 —— 双语支持
<br>

🚧 项目当前处于 Alpha 阶段，核心可用，持续优化中

快速开始

前置条件

方式 A：快速运行

想先看看效果？项目内置了两个预生成的世界，配置 世界驱动 模型的大模型即可运行。

bash
git clone https://github.com/YGYOOO/WorldX.git
cd WorldX
cp .env.example .env
# 编辑 .env —— 只填 SIMULATION_* 三行即可
npm install
npm run dev

打开 http://localhost:3200，选择一个内置世界，点击播放。

方式 B：完整创建

从零生成你自己的世界，配齐全部大模型。

bash
# 编辑 .env —— 填写全部 4 组模型配置
npm run dev

打开 http://localhost:3200/create，输入一句话，看着你的世界诞生。

也可以用命令行：

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

模型配置

WorldX 使用 4 个模型角色，各自独立配置。除绘图模型支持 Google AI Studio 原生图片接口外，其余角色均采用 OpenAI 兼容的 chat/completions 协议。

角色环境变量前缀用途推荐模型
编排引擎ORCHESTRATOR_设计世界结构、角色、规则较强推理模型（如 gemini-3.1-pro-preview）
绘图模型IMAGE_GEN_生成地图美术和角色立绘文生图模型（如 gemini-3.1-flash-image-preview）
绘图审查VISION_审查地图质量、定位区域/元素多模态模型（如 gemini-3.1-pro-preview）
世界驱动SIMULATION_驱动运行时角色行为任意模型，便宜的就行（如 gemini-2.5-flash）

每个角色通常需要 3 个环境变量：

env
{ROLE}_BASE_URL=https://openrouter.ai/api/v1    # API 地址
{ROLE}_API_KEY=sk-or-v1-xxxx                     # API Key
{ROLE}_MODEL=google/gemini-3.1-pro-preview       # 模型标识

绘图模型可额外设置 IMAGE_GEN_PROVIDER，IMAGE_GEN_PROVIDER 可选 openai-compatible（默认，适合 OpenRouter）或 google-native（适合 Google AI Studio 图片生成）。

平台配置示例

<details> <summary><strong>OpenRouter</strong>（一个 Key 搞定全部模型）</summary>

在 openrouter.ai 获取 Key：

env
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
</details> <details> <summary><strong>Google AI Studio</strong>（有免费额度）</summary>

在 aistudio.google.com 获取 Key：

env
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
</details> <details> <summary><strong>混合搭配</strong>（不同角色使用不同平台）</summary>

你可以为每个角色使用不同的平台。例如用 Google AI Studio 免费额度来生成，用更便宜的供应商来驱动模拟：

env
# 世界设计 — Google AI Studio
ORCHESTRATOR_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
ORCHESTRATOR_API_KEY=AIzaSy...
ORCHESTRATOR_MODEL=gemini-3.1-pro-preview

# 美术生成 — 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

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

# 模拟运行 — DeepSeek（高频调用更划算）
SIMULATION_BASE_URL=https://api.deepseek.com/v1
SIMULATION_API_KEY=sk-...
SIMULATION_MODEL=deepseek-chat
</details>

代理问题

注意：建议在你的代理软件中开启 TUN / 虚拟网卡 / 全局透明代理模式，开启后 Node.js 请求通常会自动走代理，一般可避免此类问题。

如果浏览器可以访问 OpenRouter / Google AI Studio，但运行 npm run dev 或创建世界时报 This model is not available in your region、fetch failed、ETIMEDOUT，通常是因为浏览器走了代理，但 Node.js 进程没有走代理。

若代理软件不支持TUN/虚拟网卡/全局透明代理模式，可先查看本机代理端口：

bash
scutil --proxy

找到 HTTPPort / HTTPSPort 所示的端口号后，在启动项目前设置代理：

bash
# 注意把下面的端口号替换成HTTPPort/HTTPSPort所示的端口号
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890

npm run dev

架构

<img src="docs/chart1.png"/> <img src="docs/chart2.png"/>

详细技术介绍

https://zhuanlan.zhihu.com/p/2032410449854068566

项目结构

WorldX/
├── orchestrator/         # LLM 驱动的世界设计与配置生成
│   ├── src/
│   │   ├── index.mjs           # 管线入口：一句话 → 世界
│   │   ├── world-designer.mjs  # LLM 世界设计
│   │   └── config-generator.mjs
│   └── prompts/
│       └── design-world.md     # 世界设计 prompt 模板
├── generators/           # 美术生成管线
│   ├── map/              # 地图生成（多步骤 + 审查循环）
│   └── character/        # 角色立绘生成（含抠图）
├── server/               # 模拟引擎（Express + SQLite + LLM）
│   └── src/
│       ├── core/         # WorldManager, CharacterManager
│       ├── simulation/   # SimulationEngine, DecisionMaker, DialogueGenerator
│       ├── llm/          # LLMClient, PromptBuilder
│       └── store/        # SQLite 持久化（每时间线独立）
├── client/               # 游戏客户端（Phaser 3 + React 19）
│   └── src/
│       ├── scenes/       # BootScene, WorldScene
│       ├── ui/           # React 覆盖层面板
│       └── systems/      # 相机、寻路、回放
├── shared/               # 共享工具（结构化输出解析）
├── library/worlds/       # 内置示例世界
├── output/worlds/        # 你生成的世界
└── .env.example          # 配置模板

开发

bash
npm run dev          # 同时启动客户端和服务器（开发模式）
npm run create       # 通过命令行直接生成新世界
  • 客户端：http://localhost:3200
  • 服务器：http://localhost:3100

交流群

<img src="docs/qq_group.jpg" width="200px"/>

感谢

License

MIT

Contributors

Showing top 1 contributor by commit count.

YGYOOO

YGYOOO

23 commits

View all contributors on GitHub →

This article is auto-generated from YGYOOO/WorldX via the GitHub API.Last fetched: 6/24/2026