# 13 · 弹射物系统与对象池

> **命名空间** `BaseGames.Combat`（扩展）· `BaseGames.Core`（ObjectPool）  
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
> **依赖** `BaseGames.Core.Events` · `BaseGames.Combat`（DamageInfo / HurtBox）· `BaseGames.Parry`（弹反流程）

---

## 目录

1. [系统总览](#1-系统总览)
2. [Projectile 组件](#2-projectile-组件)
3. [弹射物类型](#3-弹射物类型)
4. [可弹反弹射物（ParryableProjectile）](#4-可弹反弹射物parryableprojectile)
5. [GlobalObjectPool — 对象池架构](#5-globalobjectpool--对象池架构)
6. [ProjectileConfigSO](#6-projectileconfigso)
7. [BD_SpawnProjectile Task 实现](#7-bd_spawnprojectile-task-实现)
8. [碰撞处理流程](#8-碰撞处理流程)
9. [跨场景 Pool 回收](#9-跨场景-pool-回收)
10. [事件频道](#10-事件频道)
11. [编辑器友好设计](#11-编辑器友好设计)

---

## 1. 系统总览

弹射物系统解决以下问题：

| 问题 | 方案 |
|------|------|
| 敌人频繁射击产生大量 GameObject | `GlobalObjectPool` 对象池复用，避免 GC |
| 弹射物需携带完整伤害信息 | `Projectile` 持有 `DamageInfo` 结构体 |
| 弹反机制需要反弹弹射物 | `ParryableProjectile` 扩展类，`OnParried()` 反转方向 |
| 不同弹射物行为差异大 | 类型枚举 + 配置 SO，同一组件支持多种轨迹 |
| 场景切换时池对象泄漏 | `SceneLoader` 触发 Pool 回收（见 §9）|

---

## 2. Projectile 组件

`Projectile` 是所有弹射物的基类，挂载在弹射物 Prefab 根对象上：

```csharp
namespace BaseGames.Combat
{
    [RequireComponent(typeof(Rigidbody2D), typeof(Collider2D))]
    public class Projectile : MonoBehaviour
    {
        // --- 运行时数据（从 ProjectileConfigSO 注入）---
        [HideInInspector] public DamageInfo DamageInfo;   // 由 BD_SpawnProjectile 注入
        [HideInInspector] public Vector2    Direction;    // 归一化发射方向

        protected ProjectileConfigSO _config;
        protected Rigidbody2D        _rb;
        protected float              _aliveTimer;

        // 初始化（对象池取出时调用，替代 Awake/Start）
        public virtual void Initialize(ProjectileConfigSO config, DamageInfo damageInfo, Vector2 direction)
        {
            _config     = config;
            DamageInfo  = damageInfo;
            Direction   = direction.normalized;
            _aliveTimer = 0f;
            _rb         = GetComponent<Rigidbody2D>();
            OnInitialized();
        }

        protected virtual void OnInitialized() { }

        protected virtual void Update()
        {
            _aliveTimer += Time.deltaTime;
            if (_aliveTimer >= _config.lifetime)
                ReturnToPool();
        }

        protected void ReturnToPool()
            => GlobalObjectPool.Instance.Return(_config.poolKey, gameObject);

        // 碰撞在子类或此处处理（见 §8）
        protected virtual void OnTriggerEnter2D(Collider2D other) { }
    }
}
```

---

## 3. 弹射物类型

通过 `ProjectileConfig.moveType` 枚举决定运动方式，同一个 `Projectile` 类支持三种轨迹：

### 3.1 LinearProjectile（直线）

```csharp
public class LinearProjectile : Projectile
{
    protected override void OnInitialized()
        => _rb.velocity = Direction * _config.speed;

    // 速度由物理引擎维持，不需要每帧更新
}
```

用途：弓箭手普通箭矢、法师小型法球。

### 3.2 ArcProjectile（抛物线）

```csharp
public class ArcProjectile : Projectile
{
    protected override void OnInitialized()
    {
        // 给定角度和速度，分解为 X/Y 分量
        float angle = _config.launchAngleDeg * Mathf.Deg2Rad;
        _rb.velocity = new Vector2(
            Direction.x * _config.speed * Mathf.Cos(angle),
            _config.speed * Mathf.Sin(angle)
        );
        _rb.gravityScale = _config.gravityScale;   // 受重力影响
    }
}
```

用途：投石、毒液弹、炸弹投掷。

### 3.3 HomingProjectile（追踪）

> **【违规修复】** 原实现使用 `GameObject.FindGameObjectWithTag("Player")`，违反零耦合原则（见 `00_Overview §2.1`）。  
> 已修正为通过 `TransformEventChannelSO` 事件频道注入玩家 Transform。

```csharp
public class HomingProjectile : Projectile
{
    [SerializeField] TransformEventChannelSO _onPlayerSpawned;  // 注入依赖（SO 引用）

    Transform _target;

    void OnEnable()
        => _onPlayerSpawned.OnEventRaised += SetTarget;

    void OnDisable()
        => _onPlayerSpawned.OnEventRaised -= SetTarget;

    void SetTarget(Transform t) => _target = t;

    protected override void OnInitialized()
    {
        // 若 _target 仍为 null（极少数情况：玩家未在事件频道广播时已存在）
        // ProjectileManager 在发射时传入缓存值（见下方 ProjectileManager 说明）
        _rb.velocity = Direction * _config.speed;
    }

    protected override void Update()
    {
        base.Update();
        if (_target == null) return;
        Vector2 toTarget = ((Vector2)_target.position - (Vector2)transform.position).normalized;
        Vector2 newVel   = Vector2.MoveTowards(
            _rb.velocity.normalized, toTarget,
            _config.homingStrength * Time.deltaTime) * _config.speed;
        _rb.velocity = newVel;
    }
}
```

**`ProjectileManager` 辅助缓存**（常驻 Persistent 场景，挂载于 GlobalObjectPool 同级）：

```csharp
public class ProjectileManager : MonoBehaviour
{
    [SerializeField] TransformEventChannelSO _onPlayerSpawned;
    Transform _playerTransform;

    void OnEnable()  => _onPlayerSpawned.OnEventRaised += t => _playerTransform = t;
    void OnDisable() => _onPlayerSpawned.OnEventRaised -= t => _playerTransform = t;

    /// <summary>
    /// 发射追踪弹时，由发射方调用，传入已缓存的玩家 Transform。
    /// 保证即使玩家在本帧出生，HomingProjectile 也能立即锁定目标。
    /// </summary>
    public void LaunchHoming(HomingProjectile proj, Transform origin, Vector2 direction)
    {
        proj.SetTarget(_playerTransform);       // 主动注入缓存值
        proj.Initialize(direction, origin);
    }

    public Transform PlayerTransform => _playerTransform;
}
```

**`PlayerController.Awake` 中广播**：

```csharp
// PlayerController.cs
[SerializeField] TransformEventChannelSO _onPlayerSpawned;

void Awake()
{
    // ... 其他初始化
    _onPlayerSpawned.Raise(transform);   // 广播自身 Transform，供 HomingProjectile 订阅
}
```

用途：追踪蜂群、Boss 阶段特殊弹。追踪强度 `homingStrength`（弧度/秒）由 SO 配置。

---

## 4. 可弹反弹射物（ParryableProjectile）

弹反机制的核心爽点之一：玩家成功弹反标有 `CanBeParried` 的弹射物后，弹射物反向飞回攻击者：

```csharp
public class ParryableProjectile : LinearProjectile
{
    bool _isParried = false;

    // ParrySystem 在弹反判定成功时调用此方法
    public void OnParried(Transform parryer)
    {
        if (_isParried) return;   // 防止重复弹反
        _isParried = true;

        // 1. 方向反转
        Direction = -Direction;
        _rb.velocity = Direction * _config.speed * _config.parrySpeedMultiplier;   // 弹反后速度可提升（默认 1.2×）

        // 2. 更新 DamageInfo：攻击者变为玩家，伤害变为反弹伤害
        DamageInfo = new DamageInfo(
            attacker:    parryer,
            receiver:    null,                         // 待碰撞时确定
            damage:      Mathf.RoundToInt(DamageInfo.Damage * _config.parryDamageMultiplier),
            direction:   Direction,
            flags:       DamageFlags.IsProjectile | DamageFlags.IsParried,
            soulGain:    0
        );

        // 3. 切换碰撞层：弹射物现在只伤害敌人，不再伤害玩家
        gameObject.layer = LayerMask.NameToLayer("PlayerProjectile");

        // 4. 视觉/音效反馈
        _onParryableProjectileParried.Raise();   // 订阅者：Feel MMF_Flash 金色闪光
    }
}
```

### ParrySystem 的弹反检测扩展

`ParrySystem` 已有弹反窗口检测（见 [05_ParrySystem.md](./05_ParrySystem.md)），在 `OnParrySuccess` 中增加弹射物检测：

```csharp
// ParrySystem.OnTriggerEnter2D（ParryHitBox 激活时）:
if (other.TryGetComponent<ParryableProjectile>(out var proj))
{
    proj.OnParried(transform);
    _onPlayerParrySuccess.Raise(/* DamageInfo */);
    // 触发子弹时间、音效、特效（与普通弹反相同流程）
}
```

---

## 5. GlobalObjectPool — 对象池架构

`GlobalObjectPool` 常驻 Persistent 场景，管理全游戏的对象池：

```csharp
namespace BaseGames.Core
{
    public class GlobalObjectPool : MonoBehaviour
    {
        public static GlobalObjectPool Instance { get; private set; }

        // Key: PoolKey（SO 资产引用，唯一标识）, Value: 对象队列
        readonly Dictionary<PoolKeySO, Queue<GameObject>> _pools = new();

        // 从 Inspector 配置预热清单
        [SerializeField] PoolPrewarmEntry[] _prewarmEntries;

        async void Awake()
        {
            Instance = this;
            foreach (var entry in _prewarmEntries)
                await PrewarmAsync(entry.key, entry.prefabRef, entry.count);
        }

        async Task PrewarmAsync(PoolKeySO key, AssetReferenceGameObject prefabRef, int count)
        {
            // 通过 Addressables 加载 Prefab 资源（Handle 保留，池销毁时 Release）
            var handle = Addressables.LoadAssetAsync<GameObject>(prefabRef);
            await handle.Task;
            var prefab = handle.Result;
            _handles[key] = handle;   // 记录 handle 以便最终 Release

            if (!_pools.ContainsKey(key)) _pools[key] = new Queue<GameObject>();
            for (int i = 0; i < count; i++)
            {
                var obj = Object.Instantiate(prefab, transform);
                obj.SetActive(false);
                _pools[key].Enqueue(obj);
            }
        }

        public GameObject Get(PoolKeySO key, GameObject prefab)
        {
            if (!_pools.ContainsKey(key)) _pools[key] = new Queue<GameObject>();
            var pool = _pools[key];
            if (pool.Count > 0)
            {
                var obj = pool.Dequeue();
                obj.SetActive(true);
                return obj;
            }
            return Object.Instantiate(prefab);   // 池耗尽时动态扩容
        }

        public void Return(PoolKeySO key, GameObject obj)
        {
            obj.SetActive(false);
            obj.transform.SetParent(transform);
            if (!_pools.ContainsKey(key)) _pools[key] = new Queue<GameObject>();
            _pools[key].Enqueue(obj);
        }

        // 场景切换时回收指定 key 的所有活跃对象（见 §9）
        public void RecycleAll(PoolKeySO key) { ... }
    }
}
```

### 预热清单（Inspector 配置）

| PoolKey | Prefab | 预热数量 | 说明 |
|---------|--------|---------|------|
| `Pool_Projectile_Arrow` | Arrow Prefab | 10 | 弓箭手弹射物 |
| `Pool_Projectile_MagicBall` | MagicBall Prefab | 8 | 法师弹射物 |
| `Pool_Collectible_GeoSmall` | GeoSmall Prefab | 20 | 小额 Geo |
| `Pool_Collectible_GeoMedium` | GeoMedium Prefab | 10 | 中额 Geo |
| `Pool_FX_HitSpark` | HitSpark Prefab | 15 | 命中粒子特效 |
| `Pool_UI_FloatingText` | FloatingText Prefab | 10 | 浮动伤害数字 |

### PoolKeySO

使用 `ScriptableObject` 作为字典 Key，避免字符串 Key 的拼写错误风险：

```csharp
[CreateAssetMenu(menuName = "Pool/PoolKey")]
public class PoolKeySO : ScriptableObject { }
// 每种对象类型创建一个 PoolKey.asset，在 Inspector 中拖拽引用
```

---

## 6. ProjectileConfigSO

每种弹射物类型一个 SO 资产：

```csharp
[CreateAssetMenu(menuName = "Combat/ProjectileConfig")]
public class ProjectileConfigSO : ScriptableObject
{
    [Header("基础属性")]
    public float  speed            = 8f;
    public float  lifetime         = 5f;      // 超时自动回池
    public int    damage           = 10;
    public bool   canBeParried     = false;

    [Header("弹射物类型")]
    public ProjectileMoveType moveType = ProjectileMoveType.Linear;

    [Header("Linear 参数")]
    // （LinearProjectile 使用 speed 即可）

    [Header("Arc 参数")]
    public float launchAngleDeg = 45f;
    public float gravityScale   = 1f;

    [Header("Homing 参数")]
    public float homingStrength = 180f;   // 度/秒

    [Header("弹反参数")]
    public float parrySpeedMultiplier  = 1.2f;
    public float parryDamageMultiplier = 1.5f;

    [Header("对象池")]
    public PoolKeySO                poolKey;
    public AssetReferenceGameObject prefabRef;     // Addressable 引用，替代裸 GameObject

    [Header("视觉")]
    public AssetReferenceGameObject hitFXPrefabRef; // 命中时特效（Addressable，也走对象池）
}
```

资产路径：`Assets/ScriptableObjects/Config/Combat/PC_{ProjectileName}.asset`

---

## 7. BD_SpawnProjectile Task 实现

BehaviorDesigner Action Task，敌人 AI 中调用：

```csharp
namespace BaseGames.Enemies.AI
{
    public class BD_SpawnProjectile : ActionTask
    {
        [SerializeField] SharedTransform spawnPoint;       // 发射点 Transform
        [SerializeField] ProjectileConfigSO projectileConfig;
        [SerializeField] SharedBool aimAtPlayer = true;
        [SerializeField] SharedVector2 fixedDirection;     // aimAtPlayer=false 时使用固定方向

        EnemyStatsSO _stats;

        public override void OnStart()
        {
            _stats = (GetDefaultGameObject().GetComponent<EnemyBase>()).Stats;

            // 计算发射方向
            Vector2 direction = aimAtPlayer.Value
                ? ((Vector2)(Owner.transform.position - spawnPoint.Value.position)).normalized * -1f
                : fixedDirection.Value.normalized;
            // 注：方向从敌人指向玩家

            // 构建 DamageInfo
            var dmgInfo = new DamageInfo(
                attacker:  Owner.transform,
                receiver:  null,
                damage:    projectileConfig.damage,
                direction: direction,
                flags:     DamageFlags.IsProjectile,
                soulGain:  0
            );

            // 从对象池取出弹射物
            var obj = GlobalObjectPool.Instance.Get(projectileConfig.poolKey, projectileConfig.prefab);
            obj.transform.position = spawnPoint.Value.position;
            obj.GetComponent<Projectile>().Initialize(projectileConfig, dmgInfo, direction);
        }

        public override TaskStatus OnUpdate() => TaskStatus.Success;
    }
}
```

---

## 8. 碰撞处理流程

`Projectile.OnTriggerEnter2D` 统一处理命中：

```csharp
protected override void OnTriggerEnter2D(Collider2D other)
{
    // 1. 检查碰撞层（使用 LayerMask 过滤）
    if (!_config.hitLayers.Contains(other.gameObject.layer)) return;

    // 2. 尝试获取 HurtBox
    if (other.TryGetComponent<HurtBox>(out var hurtBox))
    {
        DamageInfo.Receiver = other.transform;   // 填充接收方
        hurtBox.TakeDamage(DamageInfo);
    }

    // 3. 命中特效（从对象池取出 HitFX，播放完毕后自动回池）
    if (_config.hitFXPrefab != null)
    {
        var fx = GlobalObjectPool.Instance.Get(_config.hitFXPool, _config.hitFXPrefab);
        fx.transform.position = transform.position;
        // FX Prefab 自带 AutoReturn 组件，粒子播放完毕后调用 ReturnToPool()
    }

    // 4. 回池（弹射物消失）
    // 特殊情况：穿透型弹射物（_config.penetrating=true）不立即回池
    if (!_config.penetrating)
        ReturnToPool();
}
```

### 碰撞层矩阵规则

| 弹射物层 | 可命中层 | 说明 |
|---------|---------|------|
| `EnemyProjectile` | `Player`，`Ground` | 敌人弹射物 |
| `PlayerProjectile` | `Enemy`，`Ground` | 弹反后的弹射物 |

---

## 9. 跨场景 Pool 回收

房间切换（Unload 旧场景）时，场景内弹射物的目标（敌人/玩家）已被销毁，需要回收所有活跃弹射物：

```csharp
// SceneLoader.LoadRoom() 在 Unload 旧场景前：
GlobalObjectPool.Instance.RecycleAll(Pool_Projectile_Arrow);
GlobalObjectPool.Instance.RecycleAll(Pool_Projectile_MagicBall);
// ... 其他弹射物类型

// RecycleAll 实现：找到所有活跃的该类型对象，SetActive(false) 并入队
```

**替代方案**：Projectile 在 `OnDisable()` 中自动检测 return（若不是主动回池而是被场景卸载触发 OnDisable，则不操作，让场景卸载直接清理）。由于弹射物的 Pool 位于 Persistent 场景，不会随房间卸载，需要在 SceneLoader 中显式回收。

---

## 10. 事件频道

| 资产名 | 类型 | 用途 |
|--------|------|------|
| `OnParryableProjectileParried.asset` | `VoidEventChannelSO` | 弹反弹射物时触发，启动 Feel 特效 |

---

## 11. 编辑器友好设计

- `ProjectileConfigSO` Custom Inspector：预览弹射物轨迹（根据 `moveType` 在 Inspector 底部绘制轨迹示意图）
- `GlobalObjectPool` Inspector：实时显示每个 Pool Key 的队列大小 + 已借出数量
- 弹射物 Prefab Gizmo：在 Scene View 显示 HitBox 碰撞体范围（黄色矩形）
- `BD_SpawnProjectile` 在 BT 节点上显示弹射物名称标签（自定义 BD NodeView）