216 lines
8.4 KiB
Markdown
216 lines
8.4 KiB
Markdown
# Boss 系统架构设计
|
||
|
||
> **关联切片**：S6 P0（Mini Boss Wave 8 / Final Boss Wave 20）
|
||
> **依赖系统**：EnemyManager、StatusManager、EventBus、VFXManager、ZoneManager
|
||
|
||
---
|
||
|
||
## 1. 设计原则
|
||
|
||
- **阶段驱动（Phase-Driven）**：Boss 行为由明确的阶段（Phase）枚举驱动，阶段切换在 `_physics_process` 中以血量阈值触发，不使用独立 Timer Node。
|
||
- **与 EnemyManager 解耦**：Boss 不进入 EnemyManager SoA（避免 stride 污染和 AI 逻辑膨胀），由独立的 `BossManager` Autoload 管理；但向 SpatialGrid 注册自身坐标，使子弹归航与 ZoneManager 能命中 Boss。
|
||
- **数据驱动**：每个 Boss 的阶段配置存储于 `.tres` Resource（`BossPhaseDef`），美术/策划可在不修改代码的情况下调整阈值与攻击模式。
|
||
- **EventBus 集成**：阶段切换、死亡均通过 EventBus 广播，HUD/BGM/成就系统订阅。
|
||
|
||
---
|
||
|
||
## 2. BossManager Autoload
|
||
|
||
```gdscript
|
||
# boss_manager.gd (Autoload: BossManager)
|
||
# Boss 实体数量极少（≤ 2 同屏），不使用 SoA，用 Array[BossInstance] 即可。
|
||
|
||
const MAX_BOSSES: int = 2 # 同屏 Boss 上限
|
||
|
||
var _active: Array[BossInstance] = []
|
||
|
||
func spawn_boss(boss_def_id: String, spawn_pos: Vector2) -> int:
|
||
# 从 BossRegistry 加载 BossDef，实例化 BossInstance，注册到 SpatialGrid
|
||
pass
|
||
|
||
func _physics_process(delta: float) -> void:
|
||
for boss in _active:
|
||
boss.tick(delta)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Phase 状态机模板
|
||
|
||
### 3.1 枚举与切换条件
|
||
|
||
每个 Boss 的阶段定义在 `BossPhaseDef` Resource 中：
|
||
|
||
```gdscript
|
||
# boss_phase_def.gd
|
||
class_name BossPhaseDef
|
||
extends Resource
|
||
|
||
@export var phase_id: int # 阶段编号（0 起始）
|
||
@export var hp_threshold: float # 进入此阶段的血量百分比（0.0~1.0），如 0.5 = 50% HP
|
||
@export var attack_patterns: Array[String] # 此阶段可用的攻击模式 ID 列表
|
||
@export var move_speed_mult: float = 1.0 # 移动速度倍率（狂暴阶段可设 1.5）
|
||
@export var enrage_vfx: String = "" # 阶段切换时触发的 VFX ID（空=无）
|
||
@export var phase_bgm_layer: int = 0 # 动态音乐层级（0=基础，1=紧张，2=狂暴）
|
||
```
|
||
|
||
### 3.2 BossInstance 状态机
|
||
|
||
```gdscript
|
||
# boss_instance.gd
|
||
class_name BossInstance
|
||
extends RefCounted
|
||
|
||
enum BossPhaseState {
|
||
PHASE_0, # 初始阶段（100% HP）
|
||
PHASE_1, # 受伤阶段（阈值由 BossDef 配置，通常 70%）
|
||
PHASE_2, # 危机阶段（通常 40%）
|
||
PHASE_DYING # 死亡动画阶段（HP ≤ 0，播放死亡序列后才真正移除）
|
||
}
|
||
|
||
var boss_def: BossDef
|
||
var hp: float
|
||
var hp_max: float
|
||
var position: Vector2
|
||
var current_phase: BossPhaseState = BossPhaseState.PHASE_0
|
||
var _attack_cooldown: float = 0.0
|
||
var _pattern_index: int = 0 # 当前阶段攻击模式的轮询索引
|
||
var _phase_just_changed: bool = false # 本帧刚切换阶段的标志，用于触发 enrage VFX
|
||
|
||
func tick(delta: float) -> void:
|
||
_check_phase_transition()
|
||
if current_phase == BossPhaseState.PHASE_DYING:
|
||
_tick_dying(delta)
|
||
return
|
||
_tick_movement(delta)
|
||
_tick_attack(delta)
|
||
_sync_render()
|
||
|
||
# 血量阈值检查（每帧）
|
||
func _check_phase_transition() -> void:
|
||
var hp_pct: float = hp / hp_max
|
||
var phases: Array = boss_def.phases # Array[BossPhaseDef]，按 hp_threshold 降序排列
|
||
for i in phases.size():
|
||
var phase_def: BossPhaseDef = phases[i]
|
||
if hp_pct <= phase_def.hp_threshold and int(current_phase) < i + 1:
|
||
_enter_phase(i + 1, phase_def)
|
||
break
|
||
|
||
func _enter_phase(new_phase: int, phase_def: BossPhaseDef) -> void:
|
||
current_phase = new_phase as BossPhaseState
|
||
_pattern_index = 0
|
||
_attack_cooldown = 0.0
|
||
# 阶段切换 VFX
|
||
if phase_def.enrage_vfx != "":
|
||
VFXManager.play(phase_def.enrage_vfx, position, 1.0)
|
||
# 通知 EventBus（HUD 高亮、BGM 切换）
|
||
EventBus.emit(EventID.BOSS_PHASE_CHANGED, {
|
||
"boss_id": boss_def.id,
|
||
"phase": new_phase,
|
||
"bgm_layer": phase_def.phase_bgm_layer
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 攻击模式系统 (Attack Pattern)
|
||
|
||
攻击模式以 ID 字符串存储，在 `BossAttackRegistry` 中注册（类比 `SpellRegistry`），运行时由 `_tick_attack` 调用：
|
||
|
||
```gdscript
|
||
# boss_instance.gd（续）
|
||
func _tick_attack(delta: float) -> void:
|
||
_attack_cooldown -= delta
|
||
if _attack_cooldown > 0.0:
|
||
return
|
||
var phase_def: BossPhaseDef = boss_def.phases[int(current_phase)]
|
||
if phase_def.attack_patterns.is_empty():
|
||
return
|
||
# 轮询攻击模式
|
||
var pattern_id: String = phase_def.attack_patterns[
|
||
_pattern_index % phase_def.attack_patterns.size()
|
||
]
|
||
_pattern_index += 1
|
||
var cooldown: float = BossAttackRegistry.execute(pattern_id, self)
|
||
_attack_cooldown = cooldown
|
||
```
|
||
|
||
`BossAttackRegistry.execute(id, boss)` 返回该攻击模式的冷却时间（秒）。每种攻击模式是一个独立的 GDScript 函数或 Resource，通过 SpellEvaluator 发射子弹（走标准 BulletManager 路径）。
|
||
|
||
---
|
||
|
||
## 5. 具体 Boss 设计模板
|
||
|
||
### 5.1 Mini Boss — Wave 8（待策划填充）
|
||
|
||
| 字段 | 值 |
|
||
| :--- | :--- |
|
||
| `boss_id` | `"mini_boss_w8"` |
|
||
| `hp_max` | 2000（约为普通精英 6.6×） |
|
||
| `move_speed` | 120（比杂鱼慢，靠范围攻击弥补） |
|
||
| **Phase 0**（100%→60% HP）| 攻击模式：`"charge_slam"` + `"spread_shot_3"` |
|
||
| **Phase 1**（60%→30% HP）| 追加：`"summon_minion_x2"`；move_speed_mult=1.2 |
|
||
| **Phase 2**（30%→0% HP）| 追加：`"zone_aoe_fire"`；move_speed_mult=1.5；enrage_vfx="boss_enrage" |
|
||
| 死亡事件 | `BOSS_KILLED`（EventID 待分配，建议 ID=15）|
|
||
| 战场机制 | 无（Mini Boss 不设场地机制，Final Boss 才有）|
|
||
|
||
### 5.2 Final Boss — Wave 20（待策划填充）
|
||
|
||
| 字段 | 值 |
|
||
| :--- | :--- |
|
||
| `boss_id` | `"final_boss_w20"` |
|
||
| `hp_max` | 10000 |
|
||
| `move_speed` | 80（极慢，靠弹幕覆盖）|
|
||
| **Phase 0**（100%→70% HP）| 攻击模式：`"spiral_shot_8"` + `"summon_turrets_x4"` |
|
||
| **Phase 1**（70%→40% HP）| 追加：`"zone_ice_wall"`；场地：随机生成 4 个冰墙障碍（`ZoneManager` 驱动）|
|
||
| **Phase 2**（40%→15% HP）| 追加：`"enrage_laser_sweep"`；场地收缩：边界每 10 秒向中心缩小 50px |
|
||
| **Phase 3**（15%→0% HP）| 全弹幕覆盖；`"phase3_barrage"`；恢复部分 HP 后进入死亡序列（演出用）|
|
||
| 死亡事件 | `BOSS_KILLED`（`EventID` **16**）+ `GAME_CLEARED`（**17**）；阶段切换为 **15**（均以 `implementation_plan.md` §2.1 为准）|
|
||
| 战场机制 | 场地收缩（Phase 2+）、冰墙障碍（Phase 1+）|
|
||
|
||
---
|
||
|
||
## 6. EventBus 扩展（Boss 专用事件）
|
||
|
||
> **权威登记**：以下 ID 已并入 `technical/implementation_plan.md` §2.1 事件目录与 `event_ids.gd`，本节表为语义说明（勿改号）。
|
||
|
||
| 事件 ID | 常量名 | Payload | 订阅方 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| 15 | `BOSS_PHASE_CHANGED` | `{boss_id, phase, bgm_layer}` | HUD（阶段提示）、AudioManager（BGM 切换）|
|
||
| 16 | `BOSS_KILLED` | `{boss_id, wave_num}` | WaveManager（进入结算）、AchievementManager |
|
||
| 17 | `GAME_CLEARED` | `{elapsed_sec, wave_num}` | GameCycleManager（结算屏）、排行榜 |
|
||
|
||
---
|
||
|
||
## 7. 与现有系统的接口约定
|
||
|
||
| 接口 | 调用方向 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| `SpatialGrid.register_boss(id, pos, radius)` | BossManager → SpatialGrid | Boss 作为可被子弹命中的实体，每帧更新坐标 |
|
||
| `BulletManager._on_bullet_hit(bullet_id, target_id)` | BulletManager → BossManager | `target_id` 前缀区分：`enemy_xxx` vs `boss_xxx`（或通过 faction 位掩码判断）|
|
||
| `ZoneManager.spawn_zone(...)` | BossAttackPattern → ZoneManager | Boss 攻击模式可生成 Zone（如冰墙、火圈）|
|
||
| `VFXManager.play(vfx_id, pos, scale)` | BossInstance → VFXManager | 阶段切换 + 死亡演出 VFX |
|
||
| `SpellEvaluator.execute_boss_pattern(pattern_id, origin)` | BossAttackRegistry → SpellEvaluator | Boss 弹幕走标准 SpellEvaluator 路径，复用子弹生成管线 |
|
||
|
||
---
|
||
|
||
## 8. 目录规范
|
||
|
||
```text
|
||
scripts/autoloads/
|
||
boss_manager.gd # Autoload BossManager
|
||
scripts/domain/boss/
|
||
boss_def.gd # class_name BossDef (Resource)
|
||
boss_phase_def.gd # class_name BossPhaseDef (Resource)
|
||
boss_instance.gd # class_name BossInstance (RefCounted)
|
||
boss_attack_registry.gd # BossAttackRegistry（类比 SpellRegistry）
|
||
resources/bosses/
|
||
mini_boss_w8.tres
|
||
final_boss_w20.tres
|
||
resources/boss_patterns/
|
||
charge_slam.tres
|
||
spread_shot_3.tres
|
||
spiral_shot_8.tres
|
||
# ...
|
||
```
|