Jianghu · 技术架构总览

Jianghu · 技术架构总览

前端 / 后端 / 3D / 本地生图 / 本地生视频 —— 这个作品是怎么造出来的

2026-10-09 · 依据 package.json / server/ / src/ / tools/ 实现整理

一、总体架构

铁律：后端权威——所有状态存服务器，前端只展示；掉落 / 升级 / 结算全在后端算，时间一律挂 clock.gameSeconds()（×60 倍率：24 真实分钟 = 1 作品天，锚点推导无定时器）。

二、前端（Three.js 3D + 2D 条带）

• 3D 山门：六边形山峰地形（程序化拼装，20×20 格）+ 360° 环幕水墨背景 + 实体云海（程序化低模球聚簇 + InstancedMesh）+ 日夜循环（PCFSoft 阴影、ACES 色调映射、场景雾）

• 挂机战斗：底部 2D 条带（纯 Canvas 图片滚动），角色动画播 webp 精灵表；战斗逻辑与表现分离（idleBattle / idleBand / anim 状态机）

• GLTF：建筑与植被走 GLTFLoader（大殿 / 厢房 / 植被 glb）；植被 9 种 × 700 株 InstancedMesh

• UI 浮窗：大殿招募 / 仓库 / 人物面板 / 游历大地图（2048×1152 折纸底图 + 71 节点）全部 DOM 浮层

• 时间客户端：每 2 秒拉后端时间，中间本地插值平滑，暂停 / 变速由后端权威

三、后端（零依赖 Node）

• 57 个端点（GET 15 + POST 40 + auth 2），路由精确匹配 + 前缀路由（/docs 静态伺服）

• 免登录白名单仅 4 条（health / config / register / login），其余一律 Bearer token

• 静态表（技能 220 / 装备模板 / 词条 / 套装 / 威能）全在后端，前端启动拉一次 /api/game/meta

• 掉落 roll / 经验结算 / 口粮扣账 / 声望推导全在后端；写接口统一 tmp+rename 原子落盘

四、美术资产管线（全部本地生成）

4.1 本地生图（ComfyUI + Z-Image Turbo）

提示词中文直出（Qwen3 文本编码） →

Z-Image Turbo 6B8 步 / CFG 1 →

BiRefNet 抠图透明底 RGBA →

折纸风素材落 public/assets/

• 跑在本地 ComfyUI（127.0.0.1:8188，D:/ComfyUI 常驻）；3070 Ti 8GB 实测 1024×1024 八步直出

• 产出：功法图标 240 张 / 装备与资源图标 / 十八职业半身像+头像（×男女 36 组）/ 三视图 / 环幕背景 / 游历地图 / 挂机条带背景 48 张 / 敌人立绘 48 张

• 已替代豆包 Seedream 云接口（省钱 + 离线）；中文提示词不用重写（Qwen3-4B 编码器）

• 显存互斥：Z-Image（约 11GB）与 H3 视频模型切换前先 POST /free 卸载对方

• 详见 本地生图方案.html（选型 / 显存账 / 安装 / 验收全流程）

4.2 本地生视频 → 动作精灵表（ComfyUI + MiniMax H3）

立绘生图产出 →

绿幕首帧四角 flood fill →

MiniMax H3图生视频 17k+5 帧@24fps →

抽帧抠绿12fps + despill →

逐帧对齐包围盒定基线 →

选窗拼表webp 精灵表 + meta

• GGUF Q2/Q3 量化 + Turbo LoRA 8 步，8GB 卡可跑（--lowvram）

• 抠绿用严判据（绿通道显著高于红蓝 + 亮度门槛）防误伤墨绿衣服；despill 去绿溢出

• 生成帧人物会漂移 → 逐帧测包围盒统一脚底基线 + 水平居中；循环动画取中段稳定窗口（seam 算法）

• 规模：85 个角色（36 职业门人 + 48 敌人 + 主角）× idle/跑/走/攻击/挨打/技能 若干套，actions.json 登记（帧数帧率不进作品代码）

• 验收页：敌人动作检查.html（MAD 相邻帧差自动体检 + 窗口分）

• 详见 本地H3动作生成方案.html（环境与模型 / 实测性能 / 动作配方 / 质量判据 / 坑点清单 / 已作废方案）

五、3D 与 Blender

• 本机 Blender 4.5（d:/3d-game/vendor/blender/），无头模式批量出模：--background --factory-settings --python

• Blender 产：植被 plants.glb（9 种低模，顶点色烘焙）、大殿 dadian.glb（三层主楼 + 双石狮）、厢房 xuanfang.glb——方法论：纸片原语 + 顶点色 + flat shading，与作品折纸美术语言一致

• AI 3D 生成线：dadian_seed3d.glb 来自 seed3d 实验（tools/gen_seed3d.py）

• 外部低模：采石场 / 仓库 / 伐木场 / 农田 / 铁矿 / 武器铺 / 药园 / 议事厅 8 个建筑复用 d:/3d-game 项目的现成低模

• 地形与云海不走 Blender：程序化生成（hexmap.js / clouds.js），改参数即改地形，无需过模

六、关卡敌人素材链（端到端全自动）

设定图gen_enemy_sprites 12 区域 48 张 →

BiRefNet 抠图透明立绘 →

H3 动作批跑gen_enemy_actions 46 角色 208 套 →

验收页build_action_gallery docs/assets/enemy

敌人动作批跑复用门人动作的整条 H3 管线（运行时注入角色表）；设计依据见 敌人图鉴与关卡生态设计.html。

七、开发与部署

• 开发：npm run dev:all（tools/dev.mjs 一键起后端 + vite，Ctrl+C 一起退，taskkill /T 防孤儿进程占端口）

• 常驻：service_install.py 装启动文件夹 VBS（隐藏窗口）→ service_host.mjs 守护（30s 心跳 / 3s 退避重试 / 日志落 _service.log / 先探测端口绝不抢）

• 端口：后端 8000 / vite 5180；前端只用相对路径 /api/*（vite 代理到 8000），免跨域

• 测试：playwright 无头验收（截图 / 请求断言）；自测脚本必须走账号引导拿 token

八、目录速查