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) 批量生成。

示例：

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：弧线（采用方向渐近旋转，无重力）。
- guided：追踪（延迟后按目标方向渐近旋转，rotateSpeed 影响转向快慢）。
- 可通过 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 中添加相应配置即可。

README.md 6.5 KB Histórico Raw