WorldX GitHub Details, Stars and Alternatives

REPOSITORY OVERVIEW

Live repository statistics

★ 1.2KStars

⑂ 195Forks

◯ 7Open issues

◉ 1.2KWatchers

README preview

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

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

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

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

特性

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

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

快速开始

前置条件

Node.js 18+
API Key —— 详见下方模型配置

方式 A：快速运行

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

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：完整创建

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

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

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

也可以用命令行：

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 个环境变量：

{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 图片生成）。

平台配置示例

图像生成模型建议使用nano banana2（gemini-3.1-flash-image），gpt-image-2在指令遵循上依然有欠缺（虽然画风显著比nb2好看），在本项目中容易导致各类问题、影响最终效果

在 openrouter.ai 获取 Key：

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

在 aistudio.google.com 获取 Key：

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

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

# 世界设计 — 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

代理问题

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

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

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

scutil --proxy

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

# 注意把下面的端口号替换成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

架构

详细技术介绍

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          # 配置模板

开发

npm run dev          # 同时启动客户端和服务器（开发模式）
npm run create       # 通过命令行直接生成新世界

客户端：http://localhost:3200
服务器：http://localhost:3100

交流群

感谢

LinuxDO

License

MIT