chore: initial commit

2026-05-08 11:04:00 +08:00
commit f55d2a57c3
6278 changed files with 866081 additions and 0 deletions
--- a/Docs/Design/06_EnemySystem.md
+++ b/Docs/Design/06_EnemySystem.md
@@ -0,0 +1,410 @@
+# 06 · 敌人系统
+
+> **命名空间** `BaseGames.Enemies` · `BaseGames.Enemies.AI` · `BaseGames.Enemies.Navigation`  
+> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
+> **依赖** `BaseGames.Combat` · Behavior Designer Pro · PathBerserker2d
+
+---
+
+## 目录
+
+1. [系统总览](#1-系统总览)
+2. [EnemyBase — 敌人基础组件](#2-enemybase--敌人基础组件)
+3. [EnemyStatsSO — 敌人属性配置](#3-enemystatsso--敌人属性配置)
+4. [敌人状态机](#4-敌人状态机)
+5. [Behavior Designer 任务目录](#5-behavior-designer-任务目录)
+6. [标准行为树模板](#6-标准行为树模板)
+7. [Boss 行为树模板](#7-boss-行为树模板)
+8. [PathBerserker2d 导航集成](#8-pathberserker2d-导航集成)
+9. [BossBase — Boss 特化设计](#9-bossbase--boss-特化设计)
+10. [敌人 Prefab 层级结构](#10-敌人-prefab-层级结构)
+11. [EnemyAnimationConfigSO](#11-enemyanimationconfigso)
+12. [编辑器友好设计](#12-编辑器友好设计)
+
+---
+
+## 1. 系统总览
+
+敌人系统由三个层次组成：
+
+```
+EnemyBase（MonoBehaviour，协调器）
+├── EnemyStats            ← 运行时属性（HP、防御等）
+├── EnemyMovement         ← Rigidbody2D 移动封装
+├── EnemyAnimator         ← Animancer 动画（单层）
+├── EnemyCombat           ← HitBox 管理
+├── EnemyNavAgent         ← PathBerserker2d 寻路封装
+└── BehaviorTree          ← Behavior Designer 行为树（AI 决策）
+
+组件关系：
+  BehaviorTree（What to do） → EnemyBase接口 → EnemyMovement/EnemyCombat/EnemyNavAgent（How to do it）
+  BD 任务通过 SharedVariable 访问 EnemyBase 接口，不直接操作 Rigidbody2D
+```
+
+---
+
+## 2. EnemyBase — 敌人基础组件
+
+`EnemyBase` 是所有敌人的基础，暴露给 BD 任务的**接口列表**：
+
+### 移动接口
+
+| 方法 | 调用方（BD任务） | 说明 |
+|------|---------------|------|
+| `MoveTo(Vector2 target)` | `BD_MoveTo` | 通过 NavAgent 移动到目标点 |
+| `MoveInDirection(float dir)` | `BD_Patrol` | 直接控制水平移动方向（无寻路）|
+| `StopMovement()` | `BD_StopMovement` | 立即停止移动 |
+| `JumpTo(Vector2 target)` | `BD_Jump` | 施加跳跃冲量朝向目标 |
+| `Knockback(DamageInfo)` | HurtBox | 受击击退（不由 BD 控制）|
+| `FacePlayer()` | `BD_FaceTarget` | 翻转 SpriteRenderer 朝向玩家 |
+
+### 战斗接口
+
+| 方法 | 调用方（BD任务）| 说明 |
+|------|--------------|------|
+| `BeginAttack(AttackType type)` | `BD_Attack` | 开始攻击（激活对应 HitBox）|
+| `CanAttack()` | `BD_CanAttack` | 检查攻击是否冷却完毕 |
+| `IsPlayerInRange(float range)` | `BD_IsInRange` | 检测玩家是否在攻击范围内 |
+| `IsPlayerVisible()` | `BD_IsVisible` | Raycast 检测玩家是否可见 |
+
+### 状态接口
+
+| 方法/属性 | 说明 |
+|----------|------|
+| `ForceState(EnemyStateType)` | 强制切换敌人状态（Stagger/Death 等）|
+| `TakeDamage(DamageInfo)` | 接受伤害（由 HurtBox 调用）|
+| `IsDead` | 是否已死亡（只读）|
+| `IsStaggered` | 是否处于硬直中（只读）|
+| `CurrentHP` | 当前 HP（只读，供 BD Conditional 使用）|
+
+---
+
+## 3. EnemyStatsSO — 敌人属性配置
+
+`EnemyStatsSO` 继承自 `ScriptableObject`，每类敌人一份资产：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `DisplayName` | `string` | 敌人名称（UI显示）|
+| `MaxHP` | `int` | 最大生命值 |
+| `DefenseStat` | `int` | 防御减免值 |
+| `WalkSpeed` | `float` | 行走速度 |
+| `RunSpeed` | `float` | 追击速度 |
+| `DetectionRange` | `float` | 玩家检测半径 |
+| `AttackRange` | `float` | 攻击触发范围 |
+| `AttackCooldown` | `float` | 攻击冷却时间 |
+| `GeoDropAmount` | `int` | 死亡时掉落 Geo |
+| `GeoDropVariance` | `int` | Geo 掉落随机浮动量 |
+| `StaggerResistance` | `float` | Stagger 抗性（0=正常，1=免疫）|
+| `PatrolDistance` | `float` | 巡逻范围（从出生点起）|
+
+### 资产存放路径
+
+`Assets/ScriptableObjects/Enemies/Stats/`
+
+命名规范：`ES_{EnemyName}.asset`，如 `ES_GruntWarrior.asset`、`ES_SkullArcher.asset`。
+
+---
+
+## 4. 敌人状态机
+
+`EnemyBase` 内部维护轻量状态枚举（不使用 Animancer FSM，BD 行为树处理大部分逻辑）：
+
+| 状态 | 说明 | 优先级 |
+|------|------|--------|
+| `Dead` | 已死亡，所有系统停用 | 最高 |
+| `Stagger` | 弹反/强击后硬直 | 90 |
+| `Hurt` | 受击硬直 | 80 |
+| `Controlled` | BD 行为树正常控制 | 10 |
+
+当 `EnemyBase.State != Controlled` 时，BehaviorTree 暂停执行（调用 `BehaviorTree.DisableBehavior()`）。
+
+---
+
+## 5. Behavior Designer 任务目录
+
+### Action Tasks
+
+| 任务类名 | 命名空间 | 说明 |
+|---------|---------|------|
+| `BD_MoveTo` | `BaseGames.Enemies.AI` | 通过 NavAgent 移动到 `SharedTransform target` |
+| `BD_MoveToPlayer` | `BaseGames.Enemies.AI` | 持续追踪玩家位置 |
+| `BD_Patrol` | `BaseGames.Enemies.AI` | 在巡逻区间来回移动（非寻路，直接控制速度）|
+| `BD_FacePlayer` | `BaseGames.Enemies.AI` | 翻转 Sprite 朝向玩家 |
+| `BD_Wait` | `BaseGames.Enemies.AI` | 等待 `SharedFloat duration` 秒（`Success` 后）|
+| `BD_WaitRandom` | `BaseGames.Enemies.AI` | 随机等待 min~max 秒 |
+| `BD_Attack` | `BaseGames.Enemies.AI` | 执行攻击（激活 HitBox，播放攻击动画）|
+| `BD_PlayAnimation` | `BaseGames.Enemies.AI` | 播放指定 AnimancerState |
+| `BD_StopMovement` | `BaseGames.Enemies.AI` | 立即停止移动 |
+| `BD_SetAlert` | `BaseGames.Enemies.AI` | 设置 SharedBool `isAlerted` 为 true，触发警觉动画 |
+| `BD_SpawnProjectile` | `BaseGames.Enemies.AI` | 从挂载点生成弹射物 |
+| `BD_TeleportTo` | `BaseGames.Enemies.AI` | 瞬移到指定位置（Boss 特殊移动）|
+
+### Conditional Tasks
+
+| 任务类名 | 说明 | 返回值 |
+|---------|------|--------|
+| `BD_IsPlayerInRange` | 玩家是否在攻击范围内 | `Success` / `Failure` |
+| `BD_IsPlayerVisible` | Raycast 检测玩家可见性 | `Success` / `Failure` |
+| `BD_CanAttack` | 攻击是否冷却完毕 | `Success` / `Failure` |
+| `BD_IsHPBelow` | HP 是否低于阈值（`SharedFloat threshold`）| `Success` / `Failure` |
+| `BD_IsPlayerOnSamePlatform` | 玩家是否在同一平台上 | `Success` / `Failure` |
+| `BD_IsPatrolComplete` | 巡逻是否到达端点 | `Success` / `Failure` |
+| `BD_IsAlerted` | 是否处于警觉状态 | `Success` / `Failure` |
+
+### BD SharedVariables 规范
+
+所有 BD 行为树中使用的 SharedVariable 命名约定（保持所有敌人一致）：
+
+| 变量名 | 类型 | 说明 |
+|--------|------|------|
+| `playerTransform` | `SharedTransform` | 玩家 Transform（由 EnemyBase 注入）|
+| `selfTransform` | `SharedTransform` | 自身 Transform |
+| `patrolPointA` | `SharedVector2` | 巡逻起点 |
+| `patrolPointB` | `SharedVector2` | 巡逻终点 |
+| `isAlerted` | `SharedBool` | 是否警觉 |
+| `targetPosition` | `SharedVector2` | 当前寻路目标 |
+| `hpThreshold` | `SharedFloat` | HP 百分比阈值（Boss 换相用）|
+
+---
+
+## 6. 标准行为树模板
+
+### 模板 A：巡逻-警觉-追击-攻击（近战普通敌人）
+
+```
+[Selector]
+  │
+  ├─ [Sequence] — 死亡检测（优先级最高）
+  │    └─ [Conditional] BD_IsHPBelow(0) → Running（触发 Dead 状态，BD 暂停）
+  │
+  ├─ [Sequence] — 追击并攻击
+  │    ├─ [Conditional] BD_IsPlayerVisible
+  │    ├─ [Action] BD_FacePlayer
+  │    ├─ [Selector] — 攻击或追击
+  │    │    ├─ [Sequence] — 攻击
+  │    │    │    ├─ [Conditional] BD_IsPlayerInRange
+  │    │    │    ├─ [Conditional] BD_CanAttack
+  │    │    │    ├─ [Action] BD_StopMovement
+  │    │    │    └─ [Action] BD_Attack
+  │    │    └─ [Action] BD_MoveToPlayer  — 追击
+  │    └─ [Action] BD_SetAlert
+  │
+  └─ [Sequence] — 巡逻
+       ├─ [Action] BD_Patrol
+       └─ [Action] BD_WaitRandom(1.0, 2.5)
+```
+
+### 模板 B：弓箭手（远程攻击）
+
+```
+[Selector]
+  ├─ [Sequence] — 远程攻击
+  │    ├─ [Conditional] BD_IsPlayerVisible
+  │    ├─ [Action] BD_FacePlayer
+  │    ├─ [Action] BD_StopMovement
+  │    ├─ [Conditional] BD_CanAttack
+  │    └─ [Action] BD_SpawnProjectile
+  │
+  ├─ [Sequence] — 保持距离
+  │    ├─ [Conditional] BD_IsPlayerInRange(3.0)  ← 太近则后退
+  │    └─ [Action] BD_MoveInDirection(-1)  ← 后退
+  │
+  └─ [Action] BD_Patrol
+```
+
+---
+
+## 7. Boss 行为树模板
+
+Boss 使用多阶段结构，`BD_IsHPBelow` 控制阶段切换：
+
+```
+[Selector]
+  │
+  ├─ [Sequence] — 阶段二（HP < 40%）
+  │    ├─ [Conditional] BD_IsHPBelow(0.4)
+  │    └─ [Subtree] BossPhase2BehaviorTree
+  │
+  ├─ [Sequence] — 阶段一（默认）
+  │    └─ [Subtree] BossPhase1BehaviorTree
+  │
+  └─ [Action] BD_Wait(99)  ← 异常保底（不应到达）
+```
+
+**BossPhase1BehaviorTree（子树）**：
+
+```
+[Selector]
+  ├─ [Sequence] — 近距攻击
+  │    ├─ [Conditional] BD_IsPlayerInRange(2.5)
+  │    ├─ [Conditional] BD_CanAttack
+  │    └─ [Action] BD_Attack(AttackType.MeleeCombo)
+  │
+  ├─ [Sequence] — 远程技能
+  │    ├─ [Conditional] BD_CanAttack
+  │    ├─ [Action] BD_StopMovement
+  │    └─ [Action] BD_Attack(AttackType.RangedSkill)
+  │
+  └─ [Action] BD_MoveToPlayer
+```
+
+---
+
+## 8. PathBerserker2d 导航集成
+
+`EnemyNavAgent` 是对 PathBerserker2d `NavAgent` 的封装，向 BD 任务提供简洁接口：
+
+### NavSurface 场景配置
+
+每个场景必须配置：
+
+```
+[NavMesh] (Scene Root GameObject)
+├── NavSurface               ← PathBerserker2d 导航面
+│   ├── Layer Mask: Ground, Platform, OneWayPlatform
+│   └── Agent Radius: 0.3（按最小敌人尺寸）
+└── NavLink_Platform_01      ← 平台跳跃链接（手动放置）
+    NavLink_Platform_02
+    ...
+```
+
+**NavSurface 烘焙时机**：
+
+- 编辑时（静态场景）：在 Unity Editor 中提前烘焙并保存
+- 运行时（动态场景，P1）：调用 `NavSurface.BuildNavMesh()` 动态重烘焙
+
+### NavLink 类型规范
+
+| NavLink 类型 | 使用场景 | 配置参数 |
+|-------------|---------|---------|
+| `Jump` | 从平台跳到下方平台 | `MaxFallHeight`、`JumpForce` |
+| `DropDown` | 穿越单向平台下落 | `OneWayPlatformLayer` |
+| `LedgeGrab` | 抓爬台阶（P1）| `ClimbHeight` |
+
+### EnemyNavAgent 封装接口
+
+| 方法 | 说明 |
+|------|------|
+| `RequestMoveTo(Vector2 dest)` | 请求寻路到目标，异步开始 |
+| `StopNavigation()` | 停止寻路，清空路径 |
+| `IsAtDestination()` | 是否到达目标点（误差 < 0.2 units）|
+| `OnNavPathFailed` | UnityEvent：寻路失败时触发（切换为直接追击）|
+
+**寻路失败容错**：若 `PathBerserker2d` 无法找到路径，`EnemyNavAgent.OnNavPathFailed` 触发，BD 行为树退化为简单的水平追击（`BD_MoveInDirection`）。
+
+---
+
+## 9. BossBase — Boss 特化设计
+
+`BossBase` 继承 `EnemyBase`，新增以下机制：
+
+### BossPhaseConfigSO
+
+每个 Boss 阶段独立 SO 资产，便于策划调整：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `PhaseIndex` | `int` | 阶段编号（从1开始）|
+| `HPThreshold` | `float` | 进入此阶段的 HP 百分比（0~1）|
+| `BehaviorTreeAsset` | `ExternalBehaviorTree` | 该阶段使用的 BD 行为树资产 |
+| `MusicTrack` | `AudioClip` | 阶段背景音乐 |
+| `PhaseTransitionFeedback` | `MMF_Player` | 换相时播放的 Feel 反馈（特效/震动）|
+
+### 血量分段显示
+
+`BossHPBar` 根据 `BossPhaseConfigSO[]` 绘制血量分段线，玩家可在 UI 中预判换相位置。
+
+### BossArena 配置
+
+```
+[BossArena] (Scene GameObject)
+├── ArenaCollider           ← PolygonCollider2D，限制玩家退出 Boss 房间
+├── BossSpawnPoint          ← Boss 出生点
+├── [CameraBounds_Boss]     ← 专属 Cinemachine Confiner（固定大视野）
+└── BossRoomTrigger         ← OnTriggerEnter2D 触发 Boss 战开始
+    └─ 发布 OnBossFightStarted 事件频道
+```
+
+---
+
+## 10. 敌人 Prefab 层级结构
+
+```
+[Enemy_GruntWarrior] (Prefab)
+├── SpriteRenderer
+├── AnimancerComponent
+├── Rigidbody2D (Body Type: Dynamic, Freeze Rotation Z)
+├── CapsuleCollider2D (物理碰撞)
+│
+├── [HurtBox]
+│   ├── BoxCollider2D (IsTrigger, Layer: EnemyHurtBox)
+│   └── HurtBox.cs
+│
+├── [HitBox_Melee]
+│   ├── BoxCollider2D (IsTrigger, Layer: EnemyAttack)
+│   └── HitBox.cs
+│       └── _damageSource: ES_GruntWarrior_Melee.asset
+│
+├── [DetectionRange]
+│   └── CircleCollider2D (IsTrigger, 半径 = DetectionRange)
+│
+├── EnemyBase.cs
+├── EnemyStats.cs         ← 持有 EnemyStatsSO 引用
+├── EnemyMovement.cs
+├── EnemyAnimator.cs
+├── EnemyCombat.cs
+├── EnemyNavAgent.cs      ← 持有 NavAgent 引用
+├── BehaviorTree.cs       ← 持有 BehaviorTreeAsset 引用
+└── EnemyFeedback.cs      ← 持有 MMF_Player 引用
+```
+
+---
+
+## 11. EnemyAnimationConfigSO
+
+每类敌人配置独立的 `EnemyAnimationConfigSO`（存放于 `Assets/ScriptableObjects/Enemies/Animations/`）：
+
+| 字段名 | 说明 |
+|--------|------|
+| `Idle` | 待机循环动画 |
+| `Walk` | 行走循环 |
+| `Run` | 奔跑循环 |
+| `Alert` | 警觉动画（发现玩家时）|
+| `Attack_Melee` | 近战攻击 |
+| `Attack_Ranged` | 远程攻击（弓箭手/法师）|
+| `Hurt` | 受击动画 |
+| `Stagger` | 弹反硬直 |
+| `Death` | 死亡动画（播放一次后保持最后帧）|
+
+---
+
+## 12. 编辑器友好设计
+
+### EnemyBase 自定义 Inspector
+
+```
+┌─ EnemyBase ─────────────────────────────────────┐
+│  State    : Controlled                          │
+│  HP       : █████████░░░  75 / 100             │
+│  Alerted  : ✓                                   │
+│  Nav Path : Active → Room_Forest_01 (0.8m)      │
+│  ─────────────────────────────────────────────  │
+│  BD Tree  : [GruntWarrior_Patrol.asset]         │
+│             [当前执行节点: BD_MoveToPlayer]      │
+│  ─────────────────────────────────────────────  │
+│  [强制Stagger 0.8s] [强制Death] [重置HP] [重置BD]│
+└─────────────────────────────────────────────────┘
+```
+
+### Scene 视图 Gizmos
+
+| Gizmo | 颜色 | 说明 |
+|-------|------|------|
+| 检测范围 | 黄色圆圈 | `DetectionRange` 球形范围 |
+| 攻击范围 | 红色圆圈 | `AttackRange` 球形范围 |
+| 巡逻路径 | 蓝色线段 | `patrolPointA` ↔ `patrolPointB` 连线 |
+| 寻路目标 | 绿色箭头 | 指向当前 NavAgent 目标点 |
+| HitBox | 橙色矩形 | 攻击判定区域（激活时实心，未激活时虚线）|
+| HurtBox | 绿色矩形 | 受击区域 |
+| 视线检测 | 青色射线 | `IsPlayerVisible` 使用的 Raycast |