揭秘xianxia-AI-town架构设计:16个文件、12大系统如何实现单入口正交架构
揭秘xianxia-AI-town架构设计:16个文件、12大系统如何实现单入口正交架构
xianxia-AI-town(修仙AI小镇)是一款由大模型驱动的浏览器修仙模拟游戏,NPC决策由 LLM 驱动、NPC 与玩家平权。本文带你拆解它的架构设计:16 个文件、12 大系统如何靠"单入口 + 正交模块"跑起来,帮助新手读懂浏览器游戏项目架构的完整组织思路。
🎮 三步在本地跑起 xianxia-AI-town
这是一个纯前端项目:一个 HTML 入口 + 16 个 JavaScript 文件,没有构建步骤、没有依赖安装。
git clone https://gitcode.com/gh_mirrors/xi/xianxia-AI-town-AI-
克隆完成后,用浏览器直接打开仓库根目录下的 index.html,即可开始游戏。WASD 移动、E 交互、空格攻击,操作细节见官方文档 GAME_GUIDE.md。
项目全貌:4 + 12 的一层式文件清单
整个项目的全部代码只有 16 个文件,且只分两层:根节点 index.html,以及它直接引用的二级节点。完整清单维护在 DEPENDENCY_MATRIX v11.md 中,结构如下:
| 层级 | 文件 | 职责 |
|---|---|---|
| 根节点(1个) | index.html | 单入口:UI、游戏主循环、输入绑定 |
| 引擎层(3个) | js/engine/core.js | 封装 Matter.js 物理引擎 |
| js/engine/state.js | 游戏全局状态(玩家、NPC、资源、境界表) | |
| js/engine/renderer.js | 所有 Canvas 渲染 | |
| 系统层(12个) | js/systems/ | building / resource / combat / faction / technique / weather / dialog / cultivation / crafting / social / survival / spiritual |
12 个系统各自独立成文件:建造、资源采集、战斗、门派、功法快捷栏、天气、对话、修炼、合成、社交、生存、灵力——一个玩法一个文件,职责一目了然。
单入口设计:index.html 如何"串起"整个世界
打开 index.html,会看到它做三件事:
- 按序加载全部模块:先加载 3 个引擎,再加载 12 个系统,见 index.html 的
<script>区块; - 提供统一接口:每个模块都暴露
init()和update(dt),主循环逐帧调用,见 index.html 的gameLoop; - 绑定输入与 UI:键盘、鼠标事件统一在入口分发到对应系统(如 E 键调用
GameActions.interact())。
这就是"单入口"的含义:只有 index.html 引用所有模块,它自己则把调度权交给主循环。想理解游戏一帧发生了什么?读 gameLoop 这一个函数即可。
三大引擎:物理、状态、渲染各司其职
引擎层是 12 个系统共同依赖的地基:
- 物理引擎 js/engine/core.js:封装 Matter.js,负责碰撞、速度、力场;俯视角下关闭重力,玩家与 NPC 的移动都走物理速度而非直接改坐标。
- 状态中心 js/engine/state.js:全局"黑板"。玩家、13 个 NPC、资源、建筑、境界表(练气一层到元婴初期)全部集中在这里,任何系统都可读写。
- 渲染器 js/engine/renderer.js:一帧内按固定顺序绘制背景、灵脉区域、天气、地形、建筑、资源、NPC、粒子、小地图。
三者互不引用,都只被入口加载——这是"正交"的第一层含义。
12大系统如何接入:统一接口 + 互不引用
正交架构的核心规则是:所有二级节点文件互不引用,只通过共享的 GameState 间接协作。
举个完整链路——玩家靠近资源按 E 采集:
- 入口的
interact()找到最近目标,调用ResourceSystem.gather(); - 采集写入 GameState.player.inventory;
- 渲染帧里 renderer.js 自动画出掉落物;
- 物品栏 UI 由入口的
updateInventory()刷新。
四个环节分布在 4 个文件,但没有一个文件 import 另一个系统文件。新增玩法时只需:新建一个系统文件、暴露 init/update、在入口加两行加载与调用——不改动任何现有模块。
NPC与玩家平权:架构上的核心亮点
"NPC 和玩家平权"不是口号,而是数据结构层面的一视同仁:
- 同构属性:NPC 与玩家使用同一套字段——饥饿、灵力、修为、门派、背包、金币,见 js/engine/state.js 的
createEntity; - 同节拍行为:NPC 定时执行"采集 / 修炼 / 休息"行为循环,见 js/engine/state.js 的
updateNPCBehavior; - 大模型驱动决策:对话系统 js/systems/dialog.js 接入通义千问 Qwen API,并保留每个 NPC 最近 20 条聊天记录到 localStorage,让 NPC 的回复具备记忆与个性。
玩家不是"上帝",而是小镇里与 NPC 遵循同样规则的一位修士——这正是单入口正交架构带来的好处:规则只需在共享状态里定义一次,对所有角色生效。
五条架构约束:让 16 个文件保持整洁
项目在 DEPENDENCY_MATRIX v11.md 中用一张验证表固化了五条纪律:
| 原则 | 现状 |
|---|---|
| 单入口点 | 只有 index.html 是主入口 |
| 二级节点正交 | 15 个二级文件互不引用 |
| 单向引用 | 只有 index.html 引用二级节点 |
| 最大三级深度 | 实际为二级深度 |
| 行数上限 | 根节点 ≤1000 行、二级节点 ≤400 行 |
配合 DELTA_DEPENDENCY_MATRIX 系列增量文档,每次迭代都能回答"改了哪些文件、改了多少行"——架构纪律被写成了可检查的表格,而不是口头约定。
小结:新手能从这套架构学到什么
- 单入口:调度逻辑集中在一个文件,读一个函数就懂一帧;
- 正交模块:12 大系统互不引用,靠共享状态协作,增删玩法零风险;
- 统一接口:
init() / update(dt)是所有系统的"插座",即插即用; - 可验证的纪律:用依赖矩阵 + 行数上限,把整洁变成可检查项。
如果你正在写第一个前端小游戏,16 个文件就能跑完物理、渲染、AI 对话的修仙AI小镇,是一个非常适合通读源码、直接模仿的开源范本。