# BulletControl 可移植模块

本目录收纳并抽象了原项目的子弹相关逻辑（不修改原脚本），包括类型定义、弹道、命中效果、生命周期、拖尾控制器，以及一个统一的子弹控制器与批量创建方法，方便迁移到其他 Cocos Creator 项目中复用。

## 目录结构

- `BulletTypes.ts`：统一的类型与配置接口（`WeaponConfig`、`BulletConfig` 等）。
- `ConfigLoader.ts`：轻量配置加载器（直接注入或从 `resources` 读取 `weapons.json`）。
- `effects/BulletCount.ts`：子弹生成信息计算（单发、散射、连发），输出位置、方向、延迟。
- `effects/BulletTrajectory.ts`：弹道控制（`straight`、`arc`、`guided`）。
- `effects/BulletHitEffect.ts`：命中效果整合（伤害、穿透、弹射、爆炸、燃烧）。
- `effects/BulletLifecycle.ts`：生命周期控制（存活时间、射程、穿透、弹射、回程）。
- `PortableEventBus.ts`：可选的本地事件总线（`on/once/off/emit`）。
- `BulletTrailController.ts`：拖尾效果控制器与预设。
- `BulletEngine.ts`：统一子弹控制器 `WeaponBulletController` 与批量创建 `BulletEngine.createBullets`。

## 快速接入

1) 复制目录：将 `assets/scripts/BulletControl` 整体拷贝到目标项目（保持相对路径结构）。
2) 准备配置：
   - 直接注入：`ConfigLoader.setWeaponsData(loadedJson)`。
   - 或从资源：将 `weapons.json` 放入 `resources/data/weapons.json`，再调用 `await ConfigLoader.loadWeaponsFromResources('data/weapons')`。
3) 运行时创建子弹：使用 `BulletEngine.createBullets(initData, bulletPrefabOrNode)` 批量生成。

示例：

```ts
import { Prefab, Vec3 } from 'cc';
import { BulletEngine } from './BulletEngine';
import { ConfigLoader } from './ConfigLoader';

// 预先加载/注入武器配置
ConfigLoader.setWeaponsData(myWeaponsJson);

const bullets = BulletEngine.createBullets({
  weaponId: 'sharp_carrot',
  firePosition: new Vec3(100, 200, 0),
  direction: new Vec3(1, 0, 0),
  sourceBlock: someBlockNode
}, myBulletPrefab /* Prefab | Node */);

// 将 bullets 添加到场景或发射节点下
bullets.forEach(n => myShootRoot.addChild(n));
```

## 接口要点（`BulletTypes.ts`）

- `WeaponConfig`：武器整体配置（`id`、`stats`、`bulletConfig`、升级与价格等）。
- `WeaponStats`：基础数值（伤害、速度、射程、冷却、暴击等）。
- `BulletConfig`：子弹外观与行为（`visual`、`count`、`trajectory`、`hitEffects`、`lifecycle`、`shouldRotate`）。
- `BulletInitData`：运行时生成所需（`weaponId|weaponConfig`、`firePosition`、`direction`、`sourceBlock`）。

## 生成与弹道（`effects`）

- 生成模式（`BulletCount`）：
  - `single`：单发。
  - `scatter`：散射（角度范围内平均分布）。
  - `burst`：连发（支持每发延迟）。
- 弹道模式（`BulletTrajectory`）：
  - `straight`：直线，按 `speed` 前进。
  - `arc`：带重力的弧线（`gravity` 生效）。
  - `guided`：简单追踪（`turnRate` 控制最大旋转速率）。
  - 可通过 `setTarget(nodeOrPosition)` 设置/更新目标。

## 命中与生命周期

- 命中效果（`BulletHitEffect`）：
  - 伤害、穿透（`pierce_damage`）、弹射（`ricochet_damage`）、爆炸、燃烧等。
  - `applyOnHit()` 返回命中结果，供生命周期消费计数与销毁判断。
- 生命周期（`BulletLifecycle`）：
  - 依据存活时间、射程、穿透/弹射剩余、回程逻辑决定是否销毁或折返。
  - `notifyHit(result)` 消费命中次数；`shouldDestroyNow()` 判断立即销毁；`shouldReturnNow()` 判断进入回程。

## 统一控制器与批量创建（`BulletEngine.ts`）

- `WeaponBulletController`：每颗子弹的统一控制器，负责：
  - 初始化弹道、命中效果、生命周期与拖尾。
  - 自动对齐朝向；若 `bulletConfig.shouldRotate === false`，仅旋转子节点 `Pellet`。
  - 监听 `Collider2D` 的 `BEGIN_CONTACT` 并触发命中与销毁判定。
- `BulletEngine.createBullets(initData, prefabOrNode)`：按 `BulletCount` 生成信息批量创建子弹（支持延迟激活）。

## 与原项目的差异与兼容

- 本模块为纯逻辑/渲染整合，不直接耦合敌人/伤害系统（在 `applyOnHit()` 返回后由生命周期判断）。
- 方向修正：针对部分武器贴图（上为前进方向）做了度数修正：`sharp_carrot/hot_pepper/okra_missile/mace_club` 使用 `-90°`。
- 可选事件总线：`PortableEventBus` 提供最小替换方案（迁移时可替换为项目自带总线）。

## 配置与数据迁移

- 已将以下文件可单独提取：
  - `assets/data/weapons.json`
  - `assets/data/excel/方块武器配置/方块武器配置表.xlsx`
  - `assets/data/excel/weapon_config_manager.py`
- 推荐在目标项目创建 `assets/exported_data/`，将上述文件复制到该目录，便于独立维护与回溯。
- 运行时通常只需 `weapons.json`；Excel 与 Python 管理器用于离线生成/校验配置。

## 常见用法片段

- 散射：在配置中设定 `count.mode = 'scatter'` 与 `spreadAngle`；代码不需要特殊处理，`BulletEngine` 将自动分配方向。
- 连发：设定 `count.mode = 'burst'` 与 `burstDelayMs`；`createBullets` 会按延迟激活。
- 追踪：将弹道设为 `guided`，在运行时调用 `trajectory.setTarget(targetNode)` 更新目标。
- 回程/回旋镖：生命周期 `type = 'return_trip'`；命中或距离耗尽后折返。

## 集成注意事项

- Prefab 模板需包含或允许添加：`Collider2D`（若要参与碰撞）、`WeaponBulletController`（将自动添加所需组件）。
- 旋转策略：若外观应由子节点控制，将 `bulletConfig.shouldRotate` 设为 `false` 并在 Prefab 内使用 `Pellet` 命名的子节点。
- 物理层：确保 `Collider2D` 所在分组/掩码与敌人/地形匹配，避免误碰撞或不触发。
- `deltaTime` 驱动：`BulletTrajectory`、`BulletLifecycle` 需要在组件 `update()` 中被调用（已集成于控制器）。

## 迁移步骤简表

1) 复制 `BulletControl` 目录到目标项目的 `assets/scripts/`。
2) 复制 `assets/exported_data` 中的数据文件（或自行定义位置）。
3) 使用 `ConfigLoader` 注入或加载 `weapons.json`。
4) 在你的发射逻辑中，调用 `BulletEngine.createBullets(...)` 创建并挂载到场景。

如需扩展新的弹道/效果/生命周期模式，参考现有类的接口进行实现，并在 `WeaponConfig` 中添加相应配置即可。