---

title: Sect Management作品 · 技术架构总纲 version: v1.0 date: 2026-09-16 status: ⚠️ 引擎章节已过时（见下方横幅）——待重写为 Web 版

---

Sect Management作品 · 技术架构总纲

## ⚠️ 架构已迁移：本文档部分章节过时（2026-09-17 标注） 项目已放弃 Godot PC 端，改为 Python 后端 + three.js 前端 的 Web 版。 因此本文档以下内容不再适用： - 第一章「项目定位」的引擎/平台/语言 → 现为 Python 3.13 + three.js 0.186，Web 端 - 第一章 §1.1「为什么从 Unity 改到 Godot 4」 → 历史决策记录，结论已被推翻 - 第四章 §4.2「Unity → Godot 概念对照」 → 术语已换为 three.js 体系 - 第六「作品工程架构（game/）」→ PC 端工程已归档至 _archive/godot_pc/ 仍然有效：第三「目录约定」、第五「资产标准」（GLB 格式、面数预算、色板、命名规范全都在用）、 第七「验证策略」、第八「开发阶段」。 📌 当前架构的唯一真相源： - .workbuddy/memory/MEMORY.md（Web 版架构约定） - _archive/godot_pc/README.md（PC 端 → Web 版逐文件移植对应表） - 代码本身：web/backend/gamenet/ + web/frontend/src/ 待办：将本档重写为 Web 版技术宪法。

本文档是项目的技术宪法。所有子系统（作品本体、模型生产工具、美术资源生产工具）的目录约定、技术选型、接口规范以本文为准。 既有三份资产方案文档（3D资产生产体系-总体建设方案.md 等）中与本文冲突的部分，以本文为准——因其假设的引擎为 Unity，而本项目已改为 Godot 4。

---

一、项目定位

1.1 为什么从 Unity 改到 Godot 4

代价：3D 经营类生态不如 Unity 丰富；无成熟场景编辑器工作流——但本作品的地图与门派是程序化随机生成的，本来就不需要手工摆场景，这个代价实际不成立。

---

二、双线架构

整个项目切成两条互不阻塞的线，以 GLB 文件为接口。

┌─────────────────────────── 线 B · 工具链 ───────────────────────────┐
│                                                                     │
│  model-forge                    asset-forge                         │
│  (程序化建模工具)                (美术资源生产工具)                    │
│   Python → GLB                   Vue3 + FastAPI                     │
│      │                              │                               │
│      │ 产出 GLB                     │ 管理台账 / 提示词 / 管线 / 预览   │
│      ▼                              ▼                               │
│   out/*.glb  ──────────────────►  资产库                             │
│                                                                     │
└──────────────────────────────┬──────────────────────────────────────┘
                               │  GLB 文件（唯一接口）
                               ▼
┌─────────────────────────── 线 A · 作品本体 ─────────────────────────┐
│                                                                     │
│  game/  (Godot 4 工程)                                              │
│   ├── 随机世界生成                                                   │
│   ├── Sect Management（建设 / 生产 / 招募 / 研究 / 打造）                     │
│   ├── 人员境界成长（菜鸟 → 武圣，11 境 × 5 级）                       │
│   ├── 大地图势力（门派 / 山匪 / 官府 / 城镇）                          │
│   ├── 任务系统（镖局 / 缉拿 / 内务）                                   │
│   ├── 战斗结算与战报                                                  │
│   └── AI 势力成长与争霸                                               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

接口设计原则：线 A 对线 B 的依赖只有文件。作品工程只认 game/assets/models/ 下的 GLB，不关心它是程序化生成的、AI 生成的、还是从 Poly Pizza 下载的。这样任何一环的技术迭代都不会波及另一环。

---

三、目录约定

D:\3d-game\
├── docs\                          # 全部Design Docs
│   ├── 作品设计总纲.md            # GDD（策划案）
│   ├── 技术架构总纲.md            # 本文档
│   ├── 技术架构-Godot工程.md       # Godot 工程实现细则
│   └── 技术架构-美术资源工具.md     # Asset Forge 实现细则
├── game\                          # ★ 作品本体（Godot 4 工程）
│   ├── project.godot
│   ├── autoload\                  # 全局单例
│   ├── scripts\                   # GDScript 源码
│   ├── scenes\                    # .tscn 场景
│   ├── data\                      # JSON 数值配置（与代码分离）
│   └── assets\
│       ├── models\                # ← 从 model-forge 同步过来的 GLB
│       └── materials\             # 共享顶点色材质
├── model-forge\                   # ★ 模型生产工具（程序化建模）
│   ├── model_forge\
│   ├── preview\                   # Three.js 预览页
│   └── out\                       # 产出的 GLB
├── asset-forge\                   # ★ 美术资源生产工具
│   ├── backend\                   # FastAPI
│   └── frontend\                  # Vue 3 + TS
├── vendor\                        # 第三方依赖（Godot 引擎等）
├── blender_unity_prep.py          # 既有规整脚本（保留，备用）
└── *.md                           # 既有方案文档（保留，作为历史参照）

同步机制：model-forge/out/ → game/assets/models/ 由 tools/sync_assets.py 完成（增量复制 + 命名规范校验）。

---

四、Tech stack决策

4.1 已废弃的技术选型（不要用）

4.2 Unity → Godot 概念对照（避免用错术语）

---

五、资产标准（Godot 版）

源自既有方案第八章，但格式与材质落地方式已按 Godot 改写。

5.1 面数预算（三角形）

1 Godot unit = 1 米。

5.2 材质路线：统一顶点色 + 顶点分裂（已定）

5.3 16 色色板（menpai_v1）

以既有方案 6 色为核心扩展，具体色值由 model-forge/model_forge/palette.py 定义并与 asset-forge/backend/config/palette.json 保持单一数据源（以 Python 侧为准，工具侧读取同一份 JSON）。

5.4 命名规范（强制）

<类型前缀>_<资产名>_<序号>.glb

示例：bld_shanmen_01.glb、chr_zhangmen_01.glb、dec_denglong_01.glb、env_caodi_01.glb

命名是自动推断资产类型的唯一依据，作品侧同步脚本据此校验。

5.5 其他硬约束

---

六、作品工程架构（game/）

6.1 分层

┌─ 表现层 scenes/ ────────────────────────────────┐
│  GuildView（门派 3D 等距视图）                     │
│  WorldMapView（大地图）                           │
│  ui/（各类面板）                                   │
└───────────────┬─────────────────────────────────┘
                │ 只读数据 + 发事件
┌─ 逻辑层 scripts/ ────────────────────────────────┐
│  core/    GameState · EventBus · Clock · Save     │
│  world/   WorldGenerator · Faction · Town · Bandit│
│  guild/   Guild · Building · ResourceSystem · Tech│
│  units/   Character · GrowthSystem · Equipment     │
│  tasks/   TaskSystem · EscortTask · BountyTask     │
│  combat/  BattleSystem · BattleReport             │
└───────────────┬─────────────────────────────────┘
                │ 读取
┌─ 数据层 data/ ────────────────────────────────────┐
│  realms.json · buildings.json · resources.json     │
│  techs.json · equipment.json · tasks.json          │
│  balance.json · names.json                         │
└──────────────────────────────────────────────────┘

铁律：表现层不写逻辑，逻辑层不碰 Node 路径。 逻辑层通过 EventBus 广播状态变化，表现层订阅后刷新。

6.2 Autoload 单例（顺序不可乱）

6.3 数据驱动

**所有数值必须外置到 data/.json*，代码里不允许出现魔法数字。理由：

• 数值调优不需要改代码、不需要重启编辑器
• 工具链（Asset Forge）可以读取同一份配置做展示
• 后续做数值模拟/平衡性测试时可直接跑批量

6.4 挂机结算模型

离线时长 Δt = min(now - last_save_time, 上限)
每秒产出 = Σ(建筑产出 × 门人效率加成 × 加成系数)
离线收益 = 每秒产出 × Δt × 离线系数(建议 0.5~0.7)

必须在 Clock 中集中实现，落盘时间戳与结算逻辑同源，避免多处计算导致不一致。

---

七、验证策略

本项目无 GUI 自动化能力，因此全部验证靠数值与命令行：

禁止声称"目视检查正常"——没有 GUI 就老老实实用数值证明。

---

八、开发阶段

---

核心判断：本项目最大的风险不是技术难度，而是两条线的接口漂移——工具产出的资产规格一旦和作品侧的预期不一致，返工成本极高。因此本文档把"资产标准"（第五章）作为双线共同契约锁定，任何一侧改动都必须先改本文档。