揭秘xianxia-AI-town架构设计:16个文件、12大系统如何实现单入口正交架构

原创2026-10-12 15:48:551,404 阅读

揭秘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,会看到它做三件事:

  1. 按序加载全部模块:先加载 3 个引擎,再加载 12 个系统,见 index.html 的 <script> 区块;
  2. 提供统一接口:每个模块都暴露 init() 和 update(dt),主循环逐帧调用,见 index.html 的 gameLoop;
  3. 绑定输入与 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 采集:

  1. 入口的 interact() 找到最近目标,调用 ResourceSystem.gather();
  2. 采集写入 GameState.player.inventory;
  3. 渲染帧里 renderer.js 自动画出掉落物;
  4. 物品栏 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小镇,是一个非常适合通读源码、直接模仿的开源范本。

登录后查看全文
xianxia-AI-town-AI-