本页目录

WorldX:一句话生成 AI 自主世界的沙盒(TypeScript)

WorldX · YGYOOO/WorldX

WorldX 是一个用 TypeScript 编写的 AI 世界生成项目:输入一句话即可生成地图与角色,并让故事自行演化。项目围绕 LLM Agent、生成式智能体和涌现行为展开,技术栈标注为 Node.js 22.13+、TypeScript 5.x、React 19 与 Phaser 3,采用 M...

其他 自研引擎 TypeScript 物理系统 对话系统 存档系统 游戏状态管理 中级
★ Stars 1,630 Forks 276 License MIT 更新 2026-11-14

国内开发环境适配

Windows
AI 推断/待核验
Linux
AI 推断/待核验
macOS
AI 推断/待核验
引擎 / 框架:自研引擎 暂无中文教程标记 未标记站长实测
依赖安装使用 Node 内置 SQLite,无需编译原生模块;主要网络问题在于 Node.js 进程未走代理导致调用 OpenRouter / Google AI Studio 报 region、fetch failed 或超时,建议开启 TUN/全局代理或设置 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY;README 另提到 AtomGit 提供国内托管以便更快下载。

中文项目介绍

WorldX 试图把「世界构建」这件事压缩成一句话。你只需描述一个场景,它就会据此设计世界结构、生成地图与角色,并让角色在其中自主生活:做决策、与场景交互、建立关系、展开对话,从而涌现出没有提前写好剧本的故事。

README 给出的示例是「北宋汴京的夜市街,有算命的、当铺掌柜、小偷、捕快,还有一个穿越来的现代人」——输入这样一句描述后,剩下的工作交给 WorldX。除旁观之外,你还可以扮演「上帝」介入世界:广播事件、编辑角色的人设或记忆、与任意角色进行架空对话,观察世界因此产生怎样的走向。

项目当前标注为 Alpha 阶段,核心功能可用,仍在持续优化。

核心功能

一句话创造世界

描述任意场景,由模型把它变成可运行的世界。

AI 生成地图与角色

按你的要求生成美术与立绘,README 强调不是模板拼接。

自主 Agent 驱动

角色自主决策、建立关系、展开对话。

记忆与人格

角色会记住过去的经历,并据此形成行为模式。

多日演化

支持跨越昼夜循环持续演进。

上帝模式

广播事件、编辑人设/记忆、与角色开展架空对话。

时间线系统

同一个世界可以孕育多个不同时间线。

中英双语

界面与项目文档提供双语支持。

技术架构分析

项目架构与目录结构

整体分为「生成管线 + 模拟引擎 + 游戏客户端」三层:

  • orchestrator/:LLM 驱动的世界设计与配置生成,prompts/design-world.md 存放世界设计提示词模板。
  • generators/:美术生成管线,map/ 为多步骤并带审查循环的地图生成,character/ 为含抠图的角色立绘生成。
  • server/:模拟引擎(Express + SQLite + LLM),包含 core/(WorldManager、CharacterManager)、simulation/(SimulationEngine、DecisionMaker、DialogueGenerator)、llm/(LLMClient、PromptBuilder)与按时间线独立持久化的 store/。
  • client/:Phaser 3 + React 19 客户端,scenes/(BootScene、WorldScene)、ui/(React 覆盖层面板)、systems/(相机、寻路、回放)。
  • shared/:结构化输出解析等共享工具;library/worlds/ 为内置示例世界,output/worlds/ 存放你生成的世界。

开发模式下 npm run dev 会同时启动客户端与服务器,客户端位于 http://localhost:3200,服务器位于 http://localhost:3100。

补充说明

快速开始与前置条件

运行前需要满足两点:

  • Node.js 22.13+(推荐 24 LTS)。数据库使用 Node 内置的 SQLite(node:sqlite),安装依赖时无需编译原生模块。README 写明完整可用区间为 >=22.13 <23 || >=23.4;22.5 ~ 22.12 与 23.0 ~ 23.3 不可用,因为这段时间 node:sqlite 仍位于 --experimental-sqlite 标志之后。
  • 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:完整创建。 从零生成自己的世界,需要配齐全部四组模型配置,然后访问 http://localhost:3200/create 输入一句话。也可以走命令行:

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

模型配置:四个角色分工

WorldX 把大模型拆成四个独立角色,各自用环境变量前缀配置。除绘图模型支持 Google AI Studio 原生图片接口外,其余角色都走 OpenAI 兼容的 chat/completions 协议。

角色 环境变量前缀 用途
编排引擎 ORCHESTRATOR_ 设计世界结构、角色、规则,建议用推理较强的模型
绘图模型 IMAGE_GEN_ 生成地图美术和角色立绘
绘图审查 VISION_ 审查地图质量、定位区域/元素,需多模态模型
世界驱动 SIMULATION_ 驱动运行时角色行为,调用频繁,便宜的即可

每个角色通常需要三个变量,例如:

{ROLE}_BASE_URL=https://openrouter.ai/api/v1
{ROLE}_API_KEY=sk-or-v1-xxxx
{ROLE}_MODEL=google/gemini-3.1-pro-preview

绘图模型还可设置 IMAGE_GEN_PROVIDER,取值为 openai-compatible(默认,适合 OpenRouter)或 google-native(适合 Google AI Studio 图片生成)。README 提供 OpenRouter、Google AI Studio 以及「混合搭配」三套配置示例——例如用 Google AI Studio 的免费额度做世界设计与美术,用更便宜的供应商驱动模拟。README 同时提到图像生成模型的选择建议,认为在指令遵循上表现不足的模型容易在本项目中引发问题、影响最终效果。

网络与代理问题

README 专门提示:如果浏览器能访问 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,再在启动前导出 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY(注意替换成实际端口号)。

学习建议

这个项目适合想了解「LLM Agent + 生成式内容 + 游戏运行时」如何组合的开发者:可以从四个模型角色的分工切入,理解编排(离线设计)与模拟(在线驱动)为何要分离;再顺着 server/src/simulation 与 client/src/systems 阅读决策、对话与回放链路。注意项目处于 Alpha,README 中的模型示例会随平台变化,实际配置以你使用的平台为准。

开源许可证与版权说明

许可证标识:MIT。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目