# [已归档] 模块化战术土豆 - 早期架构草案 (Cocos Creator 3.x / TypeScript)

> ⚠️ **此文件为历史草案，已废弃。**
> 项目已迁移至 **Godot 4.6 + GDScript/C#**。
> 当前权威架构请参阅：[docs/technical/architecture_design.md](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/         # 配置表加载器与类型定义
```