joywayerandClaude Opus 4.8
ad2f4c0bc6
- 将开发过程/归档文档迁至 docs_dev/（development_plan、certification_checklist、 已废弃的 Cocos 架构草案 archived_cocos_architecture_draft），并修正全部跨引用 - 新增根 README.md（项目介绍，暂定名 Spellforge）与 docs_dev/README.md 索引 - 新增 docs_dev/doc_code_audit_2026-07-20.md：文档 vs 代码交叉审计报告（经 6 路对抗性复核，零证伪），含「代码更优 / 文档更优 / 中性」判定汇总 - 在 docs/ 各设计·技术·机制文档就地加「实现现状 (2026-07-20)」callout： 追认代码更优实现（纯 JSON 数据驱动、SpatialGrid-only 碰撞、MultiMesh 单档、 存档选最新槽等），订正陈旧/矛盾内容（.tres→JSON、Boss HP/阈值/波次、EventID、 StatusManager.apply 签名等），标记未实现功能（C# 热路径、Mana、元进展、 Boss 阶段/抗性、Tutorial、轨迹/连锁/催化等）与 latent bug（CoreFeatureTag 位运算、 pierce 空操作、MAX_OPS 不读 cpu_limit） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
215 lines
10 KiB
Markdown
215 lines
10 KiB
Markdown
# [已归档] 模块化战术土豆 - 早期架构草案 (Cocos Creator 3.x / TypeScript)
|
|
|
|
> ⚠️ **此文件为历史草案，已废弃。**
|
|
> 项目已迁移至 **Godot 4.6 + GDScript/C#**。
|
|
> 当前权威架构请参阅：[docs/technical/architecture_design.md](../docs/technical/architecture_design.md)
|
|
|
|
---
|
|
|
|
## 1. 概述 (Overview)
|
|
|
|
本文件记录了项目早期基于 **Cocos Creator 3.x** 的架构探索。核心设计思想（HMWS 法术系统、ECS-Lite、Zero-GC、Strategy 模式）已被 Godot 版本继承并大幅扩展。
|
|
核心体验结合了 **Brotato (土豆兄弟)** 的快节奏割草体验与 **Noita** 的深度法术构建系统。
|
|
架构设计的首要目标是 **高性能**（支持同屏大量单位与弹幕）与 **极高的可扩展性**（特别是武器系统的模块化）。
|
|
|
|
### 1.1 设计目标
|
|
1. **超模块化武器系统 (Hyper-Modular Weapon System)**：超越 Noita 的线性构建，引入更灵活的管道流与事件钩子机制。
|
|
2. **高性能战斗引擎**：支持同屏 500+ 敌人，2000+ 弹幕，60FPS 稳定运行。
|
|
3. **数据驱动 (Data-Driven)**：所有游戏内容（法术、属性、波次）完全配表化/JSON化。
|
|
|
|
---
|
|
|
|
## 2. 系统分层架构 (Layered Architecture)
|
|
|
|
采用能够严格分离数据与表现的架构模式。虽然 Cocos 是组件式的，但在核心战斗层我们将采用 **Manager + Data** 的方式来规避组件更新带来的开销。
|
|
|
|
```mermaid
|
|
graph TD
|
|
Layer1[表现层 (Presentation Layer)] --> Layer2[逻辑层 (Domain/Logic Layer)]
|
|
Layer2 --> Layer3[数据层 (Data Layer)]
|
|
Layer2 --> Layer4[核心库 (Core Library)]
|
|
|
|
subgraph Layer1
|
|
ViewComponents[Cocos Components (Sprite, Animation)]
|
|
UIManagers[UI System]
|
|
Effects[Particle Wrapper]
|
|
end
|
|
|
|
subgraph Layer2
|
|
CombatMgr[Combat Manager (Main Loop)]
|
|
SpellEvaluator[Spell Interpreter (The "CPU")]
|
|
EnemyAI[Boid AI System]
|
|
GameCycle[Wave & Shop Cycle]
|
|
end
|
|
|
|
subgraph Layer3
|
|
ConfigMgr[JSON Config Loader]
|
|
SaveSystem[Persistent Storage]
|
|
Inventory[Player State & Inventory]
|
|
end
|
|
|
|
subgraph Layer4
|
|
Pool[Object Pool System]
|
|
SpatialHash[Spatial Hashing (Collision)]
|
|
EventBus[Global Event Bus]
|
|
end
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 核心子系统：超模块化法术系统 (HMWS)
|
|
|
|
这是本项目的技术核心。我们将 Noita 的“魔杖”概念抽象为 **“法术管道 (Spell Pipeline)”**。
|
|
|
|
### 3.1 核心概念差异
|
|
|
|
| 特性 | Noita 原版 | HMWS (本项目) | 改进目的 |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **执行流** | 线性 (Deck -> Hand -> Discard) | **树状/图状结构 + 事件驱动** | 支持“子母弹”、“条件触发”、“击中后分裂逻辑”的无限嵌套。 |
|
|
| **属性计算** | 累加式 (Cast Delay += 0.1) | **管线式 (Pipeline)** | 允许中间件对属性进行乘算、覆写或逻辑重定向。 |
|
|
| **载体** | 法杖 (Wand) | **构建核心 (Core)** | 核心决定了插槽拓扑结构（不仅仅是线性数组，可能是矩阵或特定触发槽）。 |
|
|
|
|
### 3.2 数据结构设计 (TypeScript)
|
|
|
|
#### A. 基础单元 (ISpellNode)
|
|
这是所有“部件”的基类。
|
|
```typescript
|
|
interface ISpellContext {
|
|
caster: Entity; // 施法者
|
|
target: Vec2; // 目标点
|
|
stats: CastStats; // 当前累积的属性（伤害、速度、扩散等）
|
|
payloads: ProjectileDef[]; // 待发射的弹头定义队列
|
|
}
|
|
|
|
abstract class SpellNode {
|
|
id: string;
|
|
type: SpellType; // ACTION (投射物), MODIFIER (修正), TRIGGER (触发器), LOGIC (逻辑门)
|
|
|
|
// 核心执行函数：修改 Context 或 产生行为
|
|
abstract execute(ctx: ISpellContext, deck: SpellDeck): void;
|
|
}
|
|
```
|
|
|
|
#### B. 法术解析器 (The Evaluator)
|
|
为了高性能，解析器必须 **零垃圾回收 (Zero-GC)**。在施法计算帧，不应当 `new` 任何对象。
|
|
* 使用预分配的 `Context` 对象池。
|
|
* 使用 `Stack<SpellNode>` 来模拟递归，防止深层递归爆栈。
|
|
|
|
#### C. 高级特性：动态插槽与逻辑门
|
|
* **Logic Spells (逻辑法术)**：引入 `IfHPBelow`, `OnKillAction`, `EveryNbShot` 等逻辑块，让玩家实现“如果血量低于30%，则发射吸血导弹”的构建。
|
|
* **Variable Storage (变量存储)**：允许法术在法杖上写入/读取临时变量（例如：记录连击数）。
|
|
|
|
### 3.3 扩展性设计
|
|
所有法术行为通过 **Strategy Pattern (策略模式)** 实现。
|
|
新增一个法术只需：
|
|
1. 在 JSON 中定义 ID 和贴图。
|
|
2. 实现一个 `SpellAction` 类。
|
|
3. 在注册表中注册。
|
|
|
|
### 3.4 进阶构建机制 (Advanced Mechanics) - 玩法增强
|
|
为了超越“线性堆砌”的枯燥感，架构支持以下三种深度玩法机制：
|
|
|
|
#### A. 拓扑插槽系统 (Topology Slots)
|
|
核心（Core）不再仅仅是一个列表，它可以是一个 **2D 网格** 或 **电路板**。
|
|
* **adjacency_bonus (邻接加成)**：某些插槽有物理连接。例如，将 [火元素] 放在 [高压槽] 旁边，会自动获得 +20% 范围。
|
|
* **Circuit Logic (电路逻辑)**：法术流不再只是从左到右。核心板可以有分叉路口，玩家需要用 [分流器法术] 将能量流引导到不同的分支。
|
|
|
|
#### B. 状态寄存器与图灵完备 (State Registers & Turing Completeness)
|
|
为了实现真正的“图灵完备”，架构必须支持：**状态存储**、**条件跳转** 和 **循环**。
|
|
|
|
1. **Registers (寄存器)**:
|
|
* 在 `ISpellContext` 中引入 `MemoryBank`，提供 4 个 Float 寄存器 (`R1`, `R2`, `R3`, `R4`)。
|
|
* 寄存器在同一帧内所有法术间共享，甚至可以跨帧持久化（如果法杖配置了 Persistent Memory 核心）。
|
|
|
|
2. **Instruction Set (指令集法术)**:
|
|
* **OPS**: `Add R1, 1` (加法), `Set R2, HP_Percent` (赋值).
|
|
* **JUMP**: `JumpIf R1 > 10, Label_A` (条件跳转到标签A).
|
|
* **LABEL**: `Label_A` (标记跳转点).
|
|
|
|
3. **Recursion Control (递归控制)**:
|
|
* 为了防止死循环 (`While(true)`), 解释器引入 `MaxOpLimit` (最大操作数限制，例如 100 ops/frame)。超过限制强制中断并在此帧失效。
|
|
|
|
4. **实战应用**:
|
|
* **计数器**: 每射击 3 次，第 4 次发射强力火球。
|
|
* **动态模式切换**: 根据敌人距离 (`R1 = EnemyDistance`)，如果近则跳转到 [霰弹逻辑]，如果远则跳转到 [狙击逻辑]。
|
|
|
|
#### C. 共鸣系统 (Resonance System)
|
|
在**预编译阶段 (Pre-compile Phase)** 进行模式匹配。
|
|
* 如果检测到 `[水]` 和 `[电]` 法术在执行链中紧邻，架构自动插入一个隐藏的 `[导电反应]` 中间件。
|
|
* 这允许设计隐藏配方（Hidden Recipes），鼓励玩家探索特定组合。
|
|
|
|
---
|
|
|
|
## 4. 高性能战斗架构 (High-Performance Combat Architecture)
|
|
|
|
为了实现“同屏 2000+ 弹幕”和“复杂逻辑构建”的双重目标，本架构采用 **Data-Oriented (面向数据)** 与 **Hybrid-ECS** 相结合的策略，最大化 CPU 缓存命中率并消除 GC 压力。
|
|
|
|
### 4.1 核心原则：零 GC (Zero-GC Principle)
|
|
在核心战斗循环 (Game Loop) 中，**绝对禁止**使用 `new` 关键字分配堆内存。
|
|
* **Context Pooling**: `ISpellContext` 等高频对象在关卡加载时预分配 2000 个，使用时复用，用完 `Reset`。
|
|
* **Static Temporaries**: 向量计算使用全局静态临时变量 (`_tempVec2`)，避免中间对象产生。
|
|
|
|
### 4.2 实体管理：ECS-Lite
|
|
虽然 Cocos Creator 是基于组件的，但在海量单位管理上，我们将剥离组件的 Update 逻辑。
|
|
* **Manager-Based Logic**: 子弹 (`Bullet`) 和 敌人 (`Enemy`) 不挂载 `UpdateComponent`。
|
|
* 也就是：`cc.Node` 仅仅作为渲染容器。
|
|
* **Centralized Loop (中央循环)**:
|
|
* `BulletManager` 维护一个紧凑的 `Float32Array` (SoA 布局: `[x, y, vx, vy, type...]`)。
|
|
* 在 `update(dt)` 中，直接遍历 Array 进行物理积分，速度比遍历 Node Tree 快一个数量级。
|
|
* **Dirty Sync**: 仅当物体在屏幕视口内，且逻辑坐标发生位移时，才去同步 `cc.Node.position`。
|
|
|
|
### 4.3 物理与碰撞机制
|
|
* **Builtin Optimization**: 优先使用 Cocos **Builtin-Physics** (非 Box2D) 进行 Geometry Overlap 检测。
|
|
* **Spatial Hashing Fallback**: 若 Builtin 仍有压力，回退到定制的 **Spatial Grid** (一维数组网格)，只计算临近 Grid 的实体碰撞，确保碰撞检测复杂度维持在 O(N)。
|
|
* **Separation Logic**: 怪物挤压不使用刚体求解，而是施加简单的轻量级斥力向量。
|
|
|
|
### 4.4 渲染优化
|
|
* **Node Pooling**: 严格的节点池管理。
|
|
* **Throttling (分帧降频)**:
|
|
* 伤害数字：每帧最多弹出 10 个，多余的合并或延迟显示。
|
|
* AI 索敌：不需要每帧执行 `FindNearest`，可分散到 10~20 帧内轮询一次。
|
|
|
|
---
|
|
|
|
## 5. 游戏循环设计 (Game Loop)
|
|
|
|
结合 Brotato 的经济循环：
|
|
|
|
1. **准备阶段 (Shop/Inventory)**
|
|
* 玩家拖拽法术卡牌组合逻辑。
|
|
* **解析预热**：在玩家关闭背包时，预先编译法术链，生成 cached 的指令列表。避免战斗中实时解析带来的开销。
|
|
2. **战斗阶段 (Wave)**
|
|
* 生成大量敌人。
|
|
* Player 自动开火 (执行 Cached 指令列表)。
|
|
* 掉落拾取 -> 经验值/金币。
|
|
3. **结算阶段**
|
|
* 随机 3 选 1 升级（属性成长）。
|
|
* 商店刷新法术与道具。
|
|
|
|
---
|
|
|
|
## 6. 技术栈选型总结
|
|
|
|
| 模块 | 方案 | 理由 |
|
|
| :--- | :--- | :--- |
|
|
| **语言** | TypeScript | 类型安全，便于重构 |
|
|
| **ECS框架** | Custom Lite (Manager-based) | 避免第三方 ECS 库的学习成本与 overhead，针对本项目定制最优 |
|
|
| **物理** | Custom Spatial Hash | Box2D 性能瓶颈明显 |
|
|
| **UI** | Cocos UI + Virtual List | 背包道具可能很多，需要虚拟列表优化 |
|
|
| **配置** | JSON + Type Interface | 灵活且易于热更 |
|
|
|
|
## 7. 目录规范建议
|
|
|
|
```text
|
|
assets/
|
|
Scripts/
|
|
Core/ # 核心架构 (EventBus, Pool, BaseClasses)
|
|
Systems/ # 独立系统 (Physics, Input, Audio)
|
|
Domain/ # 游戏业务逻辑
|
|
SpellSystem/ # 法术解释器, 定义, 执行栈
|
|
Combat/ # 伤害计算, 弹道管理
|
|
Enemy/ # AI 行为树
|
|
View/ # UI 控制, 特效表现
|
|
Config/ # 配置表加载器与类型定义
|
|
```
|