关卡子弹功能开发

让关卡（而不是怪物 AI）能主动发射子弹：飞船的导弹、场景机关的激光、剧情里的炮击。 本模块是入口层——把「关卡想打一发子弹」这个意图，翻译成战斗组那套通用子弹框架能吃的 IBulletCreateData。核心难点有三个：关卡没有「发射者」实体（用环境空怪当替身）、 15 位 TypeId 要在编辑器里自动拼、发射器是持续物必须能销毁。

1. 边界：本模块管哪一段

1.1 与执行层的唯一契约

入口层跟执行层之间只有一个函数：

ControllerHolder.FightBulletController.CreateBulletWithSync(createData: IBulletCreateData): bigint
ControllerHolder.FightBulletController.DestroyBullet(bulletId: bigint, reason: string): void

只要把 IBulletCreateData 填对，剩下的弹道、碰撞、同步全是执行层的事。 所以本模块的全部技术含量，就是「怎么把 createData 填对」。

2. 核心设计：环境空怪当发射者替身

2.1 问题：关卡没有实体

2.2 解法：场景里放一只看不见的怪

public LaunchEnvBulletActor(bulletHandle: string, bulletTypeId: number,
    bornTransform: UE.Transform, customTarget: UE.Actor | undefined, reason = ''): void {
    if (this.CurrentEnvMonster === undefined) {
        Log.Info(ELogModule.AI, ELogAuthor.CYH, '环境怪不存在，无法触发环境子弹',
            ['typeId', bulletTypeId], ['reason', reason]);
        return;                                  // 关卡没摆环境怪 → 静默失败但有日志
    }
    // 子弹的动态上下文由环境怪的BP本身承载
    this.CurrentEnvMonster.BulletBornTransform = bornTransform;
    const bulletId = this.CreateEnvBullet(bulletTypeId, customTarget, EFightBulletConfigType.Actor);
    this.HandleMap.set(bulletHandle, bulletId);
}

2.3 单例语义：只有一只环境怪

// 后续数据多了再抽独立Model
protected CurrentEnvMonster: UE.BP_BaseEnvironmentMonster_C | undefined = undefined;

public SetCurrentEnvMonster(entityId: number): void {
    const aiComp = EntityInterfaceHelper.GetComponent(entityId, EComponent.CharacterAiComponent);
    const actorComp = EntityInterfaceHelper.GetComponent(entityId, EComponent.CharacterActorComponent);
    const envMonster = ObjectUtils.Cast(actorComp?.Actor, UE.BP_BaseEnvironmentMonster_C);
    if (aiComp?.IsEnvironment && envMonster !== undefined && envMonster !== this.CurrentEnvMonster) {
        if (this.CurrentEnvMonster !== undefined) {
            Log.Info(..., '添加了新的环境怪，会将老的替换掉',
                ['oldId', ...], ['newId', entityId]);
        }
        this.CurrentEnvMonster = envMonster;
    } else {
        Log.Error(..., '尝试将非环境的怪加入环境管理中', ['id', entityId]);
    }
}

public ClearEnvMonster(entityId: number): void { /* 只清「自己是当前那只」的情况 */ }

3. 15 位 TypeId 拼装规则

这是整个模块最值得讲的一段——它是客户端 TS、UE C++、编辑器三端共用的一套编码约定。

3.1 位段布局

// 15 位定长十进制串，从左到右四段
//  ┌────────── 6 位 ──────────┬─── 5 位 ───┬─ 3 位 ─┬ 1 位 ┐
//  │      CharTypeId          │ BulletTypeId│SubBullet│Config│
//  └──────────────────────────┴─────────────┴─────────┴──────┘
//   示例： 009501         00003        000       1
//         └ 环境怪 9501  └ 子弹表 3   └ 无子弹  └ 发射器

3.2 CharTypeId 的规范化（执行层侧）

战斗组那边还有一层 NormalizeCharTypeId，因为策划表里的角色 Id 有 4 位和 6 位两种写法：

/** 4位（1000-9999）→ value*100+1，例如 1005 → 100501
 *  6位（>=100000）→ 原样返回，完整保留后两位，例如 700499 → 700499 */
public static NormalizeCharTypeId(charTypeId: number): number {
    if (charTypeId >= 100000 && charTypeId < 1000000) { return charTypeId; }
    if (charTypeId >= 1000 && charTypeId < 10000) { return charTypeId * 100 + 1; }
    BulletLog.Warn(..., 'CharTypeId超出预期范围', ['CharTypeId', charTypeId]);
    return charTypeId;   // 告警后原样返回，暴露问题而不是静默兜底
}

3.3 编辑器侧的拼装实现

/** 根据实体配置ID、子弹配置ID和子弹类型ID计算子弹ID
 *  实现与UE的GetBulletIdFromInfo相同的功能 */
function GetBulletIdFromInfo(EntityConfigId: number,
    BulletConfigId: number, BulletTypeId: number): number {
    const CharTypeIdStr   = EntityConfigId.toString().padStart(6, '0');
    const BulletTypeIdStr = BulletConfigId.toString().padStart(5, '0');
    const SubBulletIdStr  = '0'.padStart(3, '0');        // 恒为 '000'
    const ConfigStr       = BulletTypeId === 1 ? '1' : '0';   // 1=发射器 0=子弹
    const bulletIdStr = `${CharTypeIdStr}${BulletTypeIdStr}${SubBulletIdStr}${ConfigStr}`;
    return parseInt(bulletIdStr);   // 15 位
}

3.4 自动修正 fixServerBulletId

function fixServerBulletId(to: ILaunchBullet): number {
    let typeId = to.BulletDamageSourceType?.ConfigId ?? 0;
    if (to.BulletDamageSourceType.Type === EEnvDamageSourceType.Default && typeId === 0) {
        typeId = 9501;                                  // 默认环境怪配置ID
        to.BulletDamageSourceType.ConfigId = typeId;   // 回写，让界面上也能看到
    }
    const finalTypeId = to.BulletConfigId;
    if (finalTypeId === undefined || finalTypeId === 0) { return 0; }  // 策划还没填，不拼
    const bulletType = to.BulletType !== undefined ? to.BulletType : 0;
    const bulletTypeId = GetBulletIdFromInfo(typeId, finalTypeId, bulletType);
    to.BulletTypeId = bulletTypeId;
    return bulletTypeId;
}

默认环境怪 ConfigId = 9501。这是个魔数，直接写死在函数里， 策划选「伤害来源 = 默认」时就用它。可优化点 按团队规范这里应该抽成带中文 JSDoc 的常量。

4. 编辑器 Scheme：三件套的教科书用法

launchBulletScheme 是全工程里 OnModify / OnSchemeCheck / OnFix 三件套用得最完整的一个例子，值得单独讲。

export const launchBulletScheme = createActionParamsScheme<ILaunchBullet>({
    Name: EAction.LaunchBullet, CnName: '发射关卡子弹', ShowName: true, NewLine: true,
    Fields: {
        BulletDamageSourceType: envDamageSourceScheme,
        BulletType: createConstEnumScheme<typeof EEnvBulletType>({
            CnName: '子弹类型',
            NameByValue: { [EEnvBulletType.Bullet]: '子弹', [EEnvBulletType.Emitter]: '发射器' },
        }) as Scheme<EEnvBulletType>,
        BulletConfigId: createIntScheme({ CnName: '子弹类型Id',
            Tip: '关联子弹表的RowName，关联战斗字段BulletTypeId' }),
        BulletTypeId: createIntScheme({ CnName: '子弹服务器Id(只读)',
            ReadonlyType: 'Always',
            Tip: '由BulletDamageSourceType的EntityId、BulletTypeId和BulletType自动计算' }),
        BulletSpawnType: bulletSpawnPositionScheme,
        BulletTargetType: bulletTargetPositionScheme,
        Mark: createStringScheme({ CnName: '标识符', Optional: true,
            Tip: '对于持续发射子弹的子弹发射器而言，需要有唯一标志符，来让删除子弹时找到对应的子弹',
            CreateDefault: () => '' }),
    },

    // ① 任何字段改动 → 立刻重算 TypeId
    OnModify: (from, to, type): void => { fixServerBulletId(to); },

    // ② 存盘/全量校验 → 报错但不改数据
    OnSchemeCheck: (value, messages): number => {
        let errorCount = 0;
        if (value.BulletTypeId <= 0) {
            messages.push(`子弹服务器Id计算错误: ${value.BulletTypeId}`); errorCount++;
        }
        const bulletIdStr = value.BulletTypeId.toString();
        if (bulletIdStr.length !== 15) {
            messages.push(`子弹服务器Id长度错误: ${value.BulletTypeId} (应为15位)`); errorCount++;
        }
        return errorCount;
    },

    // ③ 一键修复 → 重跑计算
    OnFix: (value): TFixResult => { fixServerBulletId(value); return 'fixed'; },
});

4.1 三件套各自的时机与职责

4.2 完整字段表

4.3 伤害来源与位置类型枚举

/** 关卡伤害来源类型 */
export const enum EEnvDamageSourceType {
    Default = 'Default',               // 默认 - 环境怪（ConfigId 兜底 9501）
    MonsterEntity = 'MonsterEntity',   // 指定一只怪当发射者
    Player = 'Player',                 // 玩家当发射者（走 FindRules 筛）
}

/** 子弹位置类型 */
export const enum EEnvBulletPositionType {
    Position = 'Position',   // 写死坐标
    Entity = 'Entity',       // 挂到某个实体身上
    Filter = 'Filter',       // 用筛选规则动态找
    NoTarget = 'NoTarget',   // 无目标（直线飞）
}

export interface IEnvDamageSourceType {
    Type: EEnvDamageSourceType;
    Location?: IVectorInfo; Rotation?: IRotatorInfo;   // 坐标类型时使用
    EntityId?: int; ConfigId?: int;                    // 实体类型时使用
    FindRules?: IEntityFindRules;                      // 玩家类型时使用
}

5. 网络分类 EFightBulletNetType

关卡子弹最终会流进战斗组的网络分类逻辑。虽然是执行层的事， 但排查「只有自己看得见 / 别人看得见自己看不见」这类 bug 必须懂。

export const enum EFightBulletNetType {
    /** 非同步:两端各自本地创建/销毁,不发协议 */
    LocalOnly = 0,
    /** 客户端权威:主控端本地发起 + 发协议,其余端等 Notify */
    ClientAuthority = 1,
    /** 服务器权威:服务器发创建协议,主控端(环境怪主控端)负责回发销毁协议 */
    ServerAuthority = 2,
}

5.1 分类的决策顺序

5.2 排查表：子弹同步异常

6. Mark：发射器的生命周期管理

6.1 为什么只有发射器需要 Mark

Scheme 的 Tip 把这件事说得很清楚：

Tip: '删除标识符对应的子弹。如果该子弹是单次子弹，而非子弹发射器，' +
     '则不需要配置该行为，它会在发射后自动删除。'

6.2 句柄表 HandleMap

private readonly HandleMap: Map<string, bigint> = new Map();

// 主动销毁环境子弹/子弹发射器
public DestroyEnvBulletEntity(handle: string, reason = 'DestroyEnvBulletEntity'): void {
    if (this.HandleMap.has(handle)) {
        const bulletId = this.HandleMap.get(handle)!;
        if (bulletId !== 0n) {
            ControllerHolder.FightBulletController.DestroyBullet(bulletId, reason);
        }
        this.HandleMap.delete(handle);   // 无论 bulletId 是否有效都要清表，防泄漏
    }
}

6.3 Mark 的三个约束

7. 三条调用入口

7.1 蓝图入口（主路径）

export class TsEnvMonsterBlueprintFunctionLibrary {
    public static GameLaunchEnvBulletActor(handle: string,
        /*@cpp: int*/ typeId: number, bornTransform: UE.Transform,
        target: UE.Actor | undefined): void {
        ControllerHolder.EnvMonsterController.LaunchEnvBulletActor(handle, typeId, bornTransform, target);
    }
    public static GameLaunchEnvBulletEmitter(...): void { /* 同构 */ }
    public static GameDestroyEnvBulletEntity(handle: string): void {
        ControllerHolder.EnvMonsterController.DestroyEnvBulletEntity(handle);
    }
}

注册在 Src/Game/ScriptedBlueprint/RegistrationStubs.ts:2572：

const tsEnvMonsterBlueprintFunctionLibrary = (
    await import('../AI/Environment/TsEnvMonsterBlueprintFunctionLibrary')
)...;
register(UE.EAlternativeBlueprintFunction.CppEnvMonsterBlueprintFunctionLibrary_GameDestroyEnvBulletEntity,
    tsEnvMonsterBlueprintFunctionLibrary.GameDestroyEnvBulletEntity);
register(UE.EAlternativeBlueprintFunction.CppEnvMonsterBlueprintFunctionLibrary_GameLaunchEnvBulletActor,
    tsEnvMonsterBlueprintFunctionLibrary.GameLaunchEnvBulletActor);
register(UE.EAlternativeBlueprintFunction.CppEnvMonsterBlueprintFunctionLibrary_GameLaunchEnvBulletEmitter,
    tsEnvMonsterBlueprintFunctionLibrary.GameLaunchEnvBulletEmitter);

7.2 关卡行为入口（只有删除）

export class LevelEventDestroyEnvBullet extends LevelEventBase {
    public override ExecuteNew(inParams: IActionParams, context: TGeneralContext, actionId?: number): void {
        const params = inParams as IDestroyEnvBullet;
        Log.Info(ELogModule.Level, ELogAuthor.TJH, 'LevelEventDestroyEnvBullet', ['Mark', params.Mark]);
        ControllerHolder.EnvMonsterController.DestroyEnvBulletEntity(params.Mark);
    }
}

[EAction.LaunchBullet]:     { Context: ['entity', 'levelPlay', 'wildEvent'], ImplementType: 'Server' },
[EAction.DestroyEnvBullet]: { Context: ['entity', 'levelPlay', 'wildEvent'], ImplementType: 'Server' },

7.3 具体业务实例：P40 飞船导弹

private readonly OnP40SpawnBullet = (bulletId: number, tag = 'P40SK'): void => {
    LevelBulletController.SpawnBulletStat?.Start();      // 性能埋点
    const actor = this.GetBindingPositionByTag(tag);
    const mesh = actor?.GetComponentByClass(UE.SkeletalMeshComponent.StaticClass()) as UE.SkeletalMeshComponent;
    if (mesh) {
        const key1 = 'RightMissileLauncher02';
        const bornTransform1 = mesh.GetSocketTransform(FNameUtil.GetDynamicFName(key1));
        const allEntityHandle = EntityInterfaceHelper.GetAllEntities();
        for (const entityHandle of allEntityHandle ?? []) {
            if (entityHandle.EntityType !== Game.Protocol.EntityType.ENTITY_TYPE_ROLE) { continue; }
            const targetActor = EntityInterfaceHelper.GetActorByEntityId(entityHandle.Id);
            if (!targetActor) { continue; }
            ControllerHolder.EnvMonsterController.LaunchEnvBulletEmitter(
                key1, 12 /*右*/, bornTransform1!, targetActor,
                'LevelBulletController.OnP40SpawnBullet' + key1);
            TimerSystem.Delay(() => {                          // 左右交替 100ms 错峰
                const key2 = 'LeftMissileLauncher02';
                const bornTransform2 = mesh.GetSocketTransform(FNameUtil.GetDynamicFName(key2));
                ControllerHolder.EnvMonsterController.LaunchEnvBulletEmitter(
                    key2, 13 /*左*/, bornTransform2!, targetActor, '...' + key2);
            }, 100);
        }
    }
    LevelBulletController.SpawnBulletStat?.Stop();
};

/** 通过标签名称获取LevelSequence中绑定对象的位置 */
private GetBindingPositionByTag(bindingName: string): UE.Actor | undefined {
    return UE.KuroCollectActorComponent.GetActorWithTag(
        FNameUtil.GetDynamicFName(bindingName), UE.ECollectActorType.Default) as UE.KuroLevelSequenceActor;
}

8. 常见修改场景

8.1 加一种新的关卡子弹（策划路径）

8.2 加一个新的 Seq 触发点（程序路径）

照抄 OnP40SpawnBullet，但把上面表格里标 该改 / 风险 的几处改掉：

/** XX 飞船左右导弹发射器的骨骼插槽名 */
const MissileSockets = ['RightMissileLauncher02', 'LeftMissileLauncher02'] as const;
/** 左右导弹的子弹表 RowName（右 12 / 左 13） */
const MissileBulletIds = [12, 13] as const;
/** 左右交替发射的错峰间隔，避免视觉上像齐射 */
const MissileStaggerMs = 100;

// handle 带上玩家 entityId，避免多目标时句柄互相覆盖
const handle = `${socketName}_${entityHandle.Id}`;

8.3 排查「关卡子弹没出来」

8.4 排查「发射器停不下来」

9. 已识别的技术债清单

10. 面试怎么讲