spellforge/docs_dev/archived_cocos_architecture_draft.md

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

⚠️ 此文件为历史草案，已废弃。 项目已迁移至 Godot 4.6 + GDScript/C#。 当前权威架构请参阅：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 的方式来规避组件更新带来的开销。

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)

这是所有“部件”的基类。

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. 目录规范建议

assets/
  Scripts/
	Core/           # 核心架构 (EventBus, Pool, BaseClasses)
	Systems/        # 独立系统 (Physics, Input, Audio)
	Domain/         # 游戏业务逻辑
	  SpellSystem/  # 法术解释器, 定义, 执行栈
	  Combat/       # 伤害计算, 弹道管理
	  Enemy/        # AI 行为树
	View/           # UI 控制, 特效表现
	Config/         # 配置表加载器与类型定义