UMassBattleAgentComponent
Source/MassBattle/Public/Components/MassBattleAgentComponent.h
概述 Overview
把 Actor(通常为 Character/Pawn)绑定到 Mass agent 实体的组件,派生自 UMassBattleEntityComponentBase。核心职责:从 AgentConfigAsset 经 UMassBattleAgentSubsystem 构建实体模板并生成 agent(本地路径);锁步会话(IsLockstepSession(),会话驱动——客户端始终走锁步栈,服务器/单机读网络 GameMode 的 bEnableNetworkSync)时走服务器驱动的 AgentComponent.Spawn 锁步指令路径;每帧按同步模式执行实体↔组件↔Actor 变换同步(含 bFreeYaw 炮塔模式、FF 快进映射);快照恢复后按 FAgentController.LockstepNetID 重链到重建实体。公开 4 个静态变换辅助函数用于脚部/胶囊中心换算。
Binds an Actor (usually a Character/Pawn) to a Mass agent entity; derived from UMassBattleEntityComponentBase. Core responsibilities: builds the entity template from AgentConfigAsset via UMassBattleAgentSubsystem and spawns the agent (local path); in a lockstep session (IsLockstepSession(), session-driven — clients always ride the lockstep stack; server/standalone read the network GameMode's bEnableNetworkSync) routing goes through the server-driven AgentComponent.Spawn lockstep command path; per frame performs entity↔component↔actor transform sync per the sync modes (including the bFreeYaw turret mode and FF fast-forward mapping); after snapshot restore re-links to the rebuilt entity by FAgentController.LockstepNetID. Exposes four static transform helpers for foot/capsule-center conversion.
继承 Inheritance
公开方法 Public Methods
Agent 版本的实体↔组件↔Actor 变换同步(Blueprint 名 "Sync Transform Entity To Actor",按 LocationSyncMode / RotationSyncMode / ScaleSyncMode 执行,遵循 bFreeYaw 与绑定时的相对变换;每 tick 自动调用——仅在需要自定义同步时机时手动调用)。前置:三轴同步模式非全 None 且相对变换已捕获;实体、owner、片段均有效。按 EffectiveSyncMode(FF 时 ComponentToEntity 映射为 EntityToActor)分方向执行:旋转(组件→实体写 FRotating,实体→组件/Actor 写目标变换)、位置(实体跟随组件保持 InitialRelativeLocation 偏移,或组件/Actor 跟随实体)、缩放。锁步会话下跳过任意轴的 ComponentToEntity 写回(agent 变换由锁步 Agent.SetTransform 下发);ComponentToEntity 写实体时清除线速度并置 FMoving.bComponentDrivenPosition 防止 MoveProcessor 对抗。bFreeYaw 时仅同步倾斜、保留目标自身偏航(不覆盖 DesiredRotationQuat)。UpdateFastForwardState 每帧调用以切换 Owner 的 ReplicateMovement。
Agent version of entity↔component↔actor transform sync (Blueprint name "Sync Transform Entity To Actor", runs per LocationSyncMode / RotationSyncMode / ScaleSyncMode, honoring bFreeYaw and the bind-time relative transform; called automatically every tick — call manually only for custom sync timing). Preconditions: not all three sync modes are None, relative transforms captured, entity/owner/fragments valid. Branches on EffectiveSyncMode (FF maps ComponentToEntity to EntityToActor): rotation (component→entity writes FRotating; entity→component/actor writes the target transform), location (entity follows the component keeping the InitialRelativeLocation offset, or component/actor follows the entity), scale. In lockstep sessions any-axis ComponentToEntity write-back is skipped (the agent transform arrives via the lockstep Agent.SetTransform); ComponentToEntity writes to the entity clear linear velocity and set FMoving.bComponentDrivenPosition so MoveProcessor does not fight the position. With bFreeYaw only tilt is synced, the target keeps its own yaw (DesiredRotationQuat untouched). UpdateFastForwardState runs each frame to toggle the Owner's ReplicateMovement.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InDeltaTime | float | 增量时间提示(0 = 使用上一 tick 的值);当前实现未使用该参数。Delta time hint (0 = use the value from the last tick); currently unused by the implementation. |
Output
无返回值。副作用:按同步方向写 FLocating/FRotating/FScaling fragment 或 SetWorldTransform/SetActorTransform;写 FMoving 速度与组件驱动标志;切换 Owner ReplicateMovement。
No return value. Side effects: writes FLocating/FRotating/FScaling fragments or SetWorldTransform/SetActorTransform per sync direction; writes FMoving velocity and the component-driven flag; toggles the Owner's ReplicateMovement.
从实体句柄反查绑定的组件:经世界上下文取 UMassAPISubsystem,校验句柄有效后读实体 FVisualizing.BindingComponentPtr。任何环节失败(世界无效、MA 缺失、句柄无效、无 FVisualizing、指针为空)返回 nullptr。
Looks up the bound component from an entity handle: resolves UMassAPISubsystem from the world context, validates the handle, then reads FVisualizing.BindingComponentPtr on the entity. Returns nullptr when any step fails (invalid world, missing MA, invalid handle, no FVisualizing, null pointer).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
WorldContext | UObject* | 世界上下文(DefaultToSelf)。World context (DefaultToSelf). |
EntityHandle | FEntityHandle | 要查找的实体句柄。The entity handle to look up. |
Output
返回绑定组件指针,未找到或无效时 nullptr。
Returns the bound component, or nullptr when not found or invalid.
手动初始化并生成实体(仅当 InitializationMode 为 Manual 时由外部调用)。已初始化时警告并返回 true。锁步会话走服务器驱动路径:有权威时调用 RequestLockstepSpawn() 返回 true,客户端返回 false 等待指令。本地路径:构建模板(CreateTemplateFromConfig)→ 生成(SpawnAgentFromTemplate),成功返回 true。
Manually initializes the component and spawns the entity (only when InitializationMode is Manual). Already-initialized: warns and returns true. Lockstep sessions route through the server-driven path: with authority calls RequestLockstepSpawn() and returns true; clients return false and wait for the command. Local path: builds the template (CreateTemplateFromConfig) → spawns (SpawnAgentFromTemplate), true on success.
Input
无参数。
No parameters.
Output
返回初始化是否成功;失败原因见 Warning 日志。
Returns whether initialization succeeded; failure reasons are in Warning logs.
步骤 1:从 AgentConfigAsset 经 UMassBattleAgentSubsystem::MakeAgentTemplateDataFromDataAsset 构建实体模板数据;模板可在 Blueprint 中修改后再生成。配置资产缺失、子系统获取失败或模板构建失败时返回无效模板(并输出 Warning)。
Step 1: builds entity template data from AgentConfigAsset via UMassBattleAgentSubsystem::MakeAgentTemplateDataFromDataAsset; the template can be modified in Blueprint before spawning. Returns an invalid template (with Warning logs) when the config asset is missing, the subsystem cannot be fetched, or template creation fails.
Input
无参数。
No parameters.
Output
返回 FEntityTemplateData;失败时 IsValid() 为 false。
Returns FEntityTemplateData; IsValid() false on failure.
步骤 2:以组件当前世界变换为生成点调用 SpawnAgentFromTemplateAtTransform 生成 agent 并绑定组件。使用组件的 TeamIndex、LaunchVelocity 与 Multipliers。
Step 2: spawns an agent at the component's current world transform via SpawnAgentFromTemplateAtTransform and binds the component. Uses the component's TeamIndex, LaunchVelocity and Multipliers.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
TemplateData | const FEntityTemplateData& | 实体模板(来自 CreateTemplateFromConfig 或修改后)。Entity template (from CreateTemplateFromConfig or modified). |
Output
返回生成的实体句柄(有效才算成功)。副作用:绑定 fragment、广播 OnAgentInitialized、同步队伍/子类型标签。
Returns the spawned entity handle (valid on success). Side effects: binds fragments, broadcasts OnAgentInitialized, syncs team/subtype tags.
指定生成点/期望 UID 的生成实现。已初始化时警告并返回现有句柄;模板、子系统、owner 无效时返回无效句柄。以组件位置为脚部原点,按 FCollider(半径/半高×ScaleMult 缩放、相对旋转)与 Move.Z.GroundHeightOffset 计算胶囊中心偏移;经 SpawnAgentsByTemplateRectangular(数量 1、CustomRotation)生成。生成后:把实体位置校正到组件局部上方偏移;写 FVisualizing.BindingActorPtr/BindingComponentPtr(bIsBindingActorSwappable=false,永久 actor 不入池);FAgentEventRT.EventReceiveActor 缺省填 owner;捕获初始相对变换;广播 OnAgentInitialized;调用 SyncAgentTagsAndController 同步标签。
Spawn implementation with explicit transform and expected UID. Already-initialized: warns and returns the existing handle; invalid template/subsystems/owner: invalid handle. Uses the component location as the foot origin and computes the capsule-center offset from FCollider (radius / half-height × ScaleMult, relative rotation) and Move.Z.GroundHeightOffset; spawns via SpawnAgentsByTemplateRectangular (count 1, CustomRotation). After spawn: corrects the entity position to the component-local up offset; writes FVisualizing.BindingActorPtr/BindingComponentPtr (bIsBindingActorSwappable=false, permanent actors never pooled); fills FAgentEventRT.EventReceiveActor with the owner when empty; captures initial relative transforms; broadcasts OnAgentInitialized; calls SyncAgentTagsAndController.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
TemplateData | const FEntityTemplateData& | 实体模板。Entity template. |
SpawnTransform | const FTransform& | 生成变换(脚部/地面层)。Spawn transform (foot/ground level). |
ExpectedUniqueID | int32 | 期望 UID(-1 = 由生成器分配)。Expected UID (-1 = allocated by the spawner). |
Output
返回生成的实体句柄;生成失败或实体无效时返回无效句柄(含 Warning 日志)。副作用:绑定、实体位置校正、事件广播、标签同步。
Returns the spawned entity handle; invalid handle (with Warning logs) on spawn failure or invalid entity. Side effects: binding, entity position correction, event broadcast, tag sync.
惰性访问器:缓存命中直接返回;否则经 GetWorld() 取 UMassBattleAgentSubsystem 并缓存。
Lazy accessor: returns the cache on hit; otherwise fetches UMassBattleAgentSubsystem from GetWorld() and caches it.
Input
无参数。
No parameters.
Output
返回子系统指针(世界缺失时可能为 nullptr)。副作用:写缓存。
Returns the subsystem pointer (may be nullptr without a world). Side effect: fills the cache.
从 owner 的 possess 链获取所属玩家索引:owner 为 APawn 且存在 APlayerState 时返回 PlayerState::GetPlayerId();否则返回 -1。
Gets the owning player index from the owner's possess chain: when the owner is an APawn with an APlayerState, returns PlayerState::GetPlayerId(); otherwise -1.
Input
无参数。
No parameters.
Output
返回玩家索引;-1 = 无玩家归属。
Returns the player index; -1 = no player ownership.
返回锁步 Owner ID 用于 spawn 延迟跟踪。玩家 agent 返回 GetOwningPlayerIndex();非玩家 agent(未来)可 override 返回服务器分配的 owner ID。
Returns the lockstep owner ID for spawn deferral tracking. Player agents return GetOwningPlayerIndex(); non-player agents (future) may override to return a server-assigned owner ID.
Input
无参数。
No parameters.
Output
返回 owner ID。
Returns the owner ID.
锁步 Owner 是否已准备好 spawn。当前实现恒返回 true —— 任何 actor 注册即就绪;玩家"等 resync"由 ProcessPendingLockstepSpawns 的 IsClientAwaitingResync 检查兜底(PlayerId < 0 时自动跳过)。非玩家 agent 可 override。
Whether the lockstep owner is ready for spawn. The current implementation always returns true — any actor is ready once registered; player "wait for resync" is handled by the IsClientAwaitingResync check in ProcessPendingLockstepSpawns (skipped automatically for PlayerId < 0). Non-player agents may override.
Input
无参数。
No parameters.
Output
返回是否就绪(当前恒 true)。
Returns readiness (currently always true).
以组件当前变换生成锁步 agent,等价于 SpawnLockstepAgent_Internal(ExpectedUniqueID, nullptr)(无变换覆写)。锁步指令执行端在同一 ExecuteTick 双端调用,UID 本地分配。
Spawns a lockstep agent at the component's current transform — equivalent to SpawnLockstepAgent_Internal(ExpectedUniqueID, nullptr) (no transform override). Called on both peers at the same ExecuteTick on the lockstep command-execution side; the UID is allocated locally.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
ExpectedUniqueID | int32 | 期望 UID,默认 -1。Expected UID, default -1. |
Output
返回是否生成成功。
Returns whether the spawn succeeded.
在显式变换处生成锁步 agent,等价于 SpawnLockstepAgent_Internal(ExpectedUniqueID, &SpawnTransform)。变换覆写路径会从载荷覆写实体变换以获得位级一致状态。
Spawns a lockstep agent at an explicit transform — equivalent to SpawnLockstepAgent_Internal(ExpectedUniqueID, &SpawnTransform). The override path forces the entity transform from the payload for bit-identical state.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
ExpectedUniqueID | int32 | 期望 UID。Expected UID. |
SpawnTransform | const FTransform& | 生成变换。Spawn transform. |
Output
返回是否生成成功。
Returns whether the spawn succeeded.
锁步生成的内部实现,三条路径:① 已初始化且 UID 匹配期望(或期望 < 0)时直接复用现有绑定;② late-join 链接:期望 UID ≥ 0 且快照中已有该实体时,按 FAgentController.LockstepNetID/UID 查实体、传送 owner Character(实体权威同步模式下)、InitializeWithEntity 绑定、分配流场、注册 UID 映射;③ 正常生成:CreateTemplateFromConfig → SpawnAgentFromTemplateAtTransform,随后若实体 UID 与期望不符则重映射(Fail loud 于 UID 冲突)、以最终 UID 重设 FDeterminism.RandomStream、注册 UID 映射、盖章本地 PC 缓存、重应用控制模式。全程保存/恢复用户配置的同步模式(内部 deinit/init 会清零)。失败路径输出 [SPAWN] Error 日志。
Internal lockstep spawn with three paths: ① already-initialized with matching UID (or expected < 0): reuses the existing binding; ② late-join link: with expected UID ≥ 0 and the entity already present from snapshot, looks up the entity by UID, teleports the owner Character (entity-authoritative sync modes only), binds via InitializeWithEntity, assigns the flow field, registers the UID mapping; ③ normal spawn: CreateTemplateFromConfig → SpawnAgentFromTemplateAtTransform, then if the entity UID differs from the expected one, remaps (fails loud on UID collision), re-seeds FDeterminism.RandomStream with the final UID, registers the UID mapping, stamps local PC caches, re-applies control mode. The user-configured sync modes are saved/restored around the internal deinit/init cycle (which resets them). Failure paths log [SPAWN] Error.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
ExpectedUniqueID | int32 | 期望 UID(late-join 链接 / 正常生成 / UID 协调)。Expected UID (late-join link / normal spawn / UID reconciliation). |
OverrideTransform | const FTransform* | 变换覆写;nullptr = 使用组件当前变换。Transform override; nullptr = use the component's current transform. |
Output
返回是否成功。副作用:绑定/重绑、UID 重映射、随机流重播种、流场分配、PC 缓存盖章、注册表写入。
Returns success. Side effects: binding/rebinding, UID remap, random-stream re-seed, flow-field assignment, PC cache stamping, registry writes.
仅服务器入口:构建并广播 AgentComponent.Spawn 锁步指令。载荷:IntPayload = [LockstepNetID, PlayerSlot, PlayerId, TeamIndex]、NamePayload = [DataAsset 路径]、FloatPayload = [位置 XYZ, 四元数 XYZW]。经 AMassBattleNetworkGameModeBase::SendLockstepCommandToClients 设置 IssuedTick/ExecuteTick/ServerExecSequence 并广播 + 本地入队。无权威、缺配置或子系统缺失时静默返回。
Server-only entry: builds and broadcasts the AgentComponent.Spawn lockstep command. Payload: IntPayload = [LockstepNetID, PlayerSlot, PlayerId, TeamIndex], NamePayload = [DataAsset path], FloatPayload = [location XYZ, quaternion XYZW]. Goes through AMassBattleNetworkGameModeBase::SendLockstepCommandToClients, which sets IssuedTick/ExecuteTick/ServerExecSequence, broadcasts and enqueues locally. Returns silently without authority, config, or subsystems.
Input
无参数。
No parameters.
Output
无返回值。副作用:广播一条锁步生成指令。
No return value. Side effect: broadcasts one lockstep spawn command.
快照恢复后的重链实现。前置:存在 AgentConfigAsset 且 LockstepNetID ≥ 0,否则置 bPendingRebind = true 返回。快照重建后实体 UID 与预分配值不同,故遍历 GlobalUIDToHandle 按 FAgentController.LockstepNetID 定位重建实体;未找到则置 bPendingRebind = true 等待每帧重试。找到后:同步 OwningAgentUniqueID 与 FAgentController.ComponentPtr,保存同步模式 → DeinitializeFromEntity → (实体权威/组件驱动模式下)传送 owner Character 到实体位置 → InitializeWithEntity → 恢复同步模式、开启 tick、分配流场、重应用控制模式。
Rebind implementation after snapshot restore. Preconditions: AgentConfigAsset present and LockstepNetID ≥ 0, otherwise sets bPendingRebind = true and returns. Because the rebuilt entity UID differs from any pre-allocated value, it iterates GlobalUIDToHandle to locate the entity by its FAgentController.LockstepNetID; not found sets bPendingRebind = true for per-frame retry. On success: syncs OwningAgentUniqueID and FAgentController.ComponentPtr, saves sync modes → DeinitializeFromEntity → (entity-authoritative / component-driven modes) teleports the owner Character to the entity → InitializeWithEntity → restores sync modes, enables ticking, assigns the flow field, re-applies control mode.
Input
无参数。
No parameters.
Output
无返回值。副作用:重绑、PC 缓存盖章、流场分配、owner 传送。
No return value. Side effects: rebinding, PC cache stamping, flow-field assignment, owner teleport.
若组件 owner 是本地玩家的 pawn(经 possess 链推导:GetFirstPlayerController 的 pawn 等于 owner),向 AMassBattleNetworkPlayerControllerBase 盖章 ControlledMassBattleCharacter / AgentUniqueID / AgentHandle / bControlledAgentActive。非本地 pawn 或无网络 PC 时无操作。
When the component's owner is the local player's pawn (derived from the possess chain: the first PlayerController's pawn equals the owner), stamps ControlledMassBattleCharacter / AgentUniqueID / AgentHandle / bControlledAgentActive onto the AMassBattleNetworkPlayerControllerBase. No-op otherwise.
Input
无参数。
No parameters.
Output
无返回值。副作用:本地 PC 的四个缓存字段写入。
No return value. Side effect: writes the four cache fields on the local PC.
为 agent 分配本地流场:取世界中第一个 AFlowField(TActorIterator),写入 FNavigation.FlowFieldToUse 与 FNavigating.FlowFieldToUsePtr/FlowFieldToUse_Previous,随后调用 UMassBattleSubsystem::ResolveAgentRuntimeObjectPtrs 解析运行时指针。无流场或实体无效时无操作。
Assigns the local flow field to the agent: takes the first AFlowField in the world (TActorIterator), writes FNavigation.FlowFieldToUse and FNavigating.FlowFieldToUsePtr/FlowFieldToUse_Previous, then calls UMassBattleSubsystem::ResolveAgentRuntimeObjectPtrs. No-op without a flow field or with an invalid entity.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InAgentHandle | FEntityHandle | 目标 agent 实体。The target agent entity. |
Output
无返回值。副作用:寻路 fragment 的流场指针写入。
No return value. Side effect: flow-field pointers written into navigation fragments.
应用控制模式配置——为蓝图兼容保留的遗留钩子:角色移动/复制控制已迁移到蓝图,C++ 实现为空操作。可安全调用,无任何效果。
Applies the control mode configuration — legacy hook kept for Blueprint compatibility: character-movement / replication control has moved to Blueprint, so the C++ implementation is a no-op. Safe to call, does nothing.
Input
无参数。
No parameters.
Output
无返回值,无副作用。
No return value, no side effects.
从组件(脚部)世界变换派生 agent 实体变换:位置经 StaticGetAgentCenterLocationFromFoot 抬升到胶囊中心,旋转保持不变。
Derives the agent-entity transform from the component's (foot) world transform: the location is lifted to the capsule center via StaticGetAgentCenterLocationFromFoot, rotation unchanged.
Input
无参数。
No parameters.
Output
返回实体级变换。无副作用。
Returns the entity-level transform. No side effects.
计算实体胶囊中心到脚部的偏移:半高×Abs(合旋转上向量 Z) + 半径 − GroundHeightOffset,其中合旋转 = 实体四元数 × 碰撞体相对旋转,半径/半高按 Multipliers.ScaleMult 缩放。组件或配置资产缺失时返回 0。
Computes the entity capsule-center-to-foot offset: half-height × Abs(combined-rotation up Z) + radius − GroundHeightOffset, where the combined rotation is the entity quaternion × the collider relative rotation, and radius/half-height are scaled by Multipliers.ScaleMult. Returns 0 without a component or config asset.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
AgentComponent | const UMassBattleAgentComponent* | 源组件(提供 Collider 配置与乘数)。Source component (provides Collider config and multipliers). |
EntityQuat | const FQuat& | 实体当前朝向。The entity's current orientation. |
Output
返回偏移量(世界单位,沿实体上向量)。无副作用。
Returns the offset in world units (along the entity up vector). No side effects.
从脚部变换推导胶囊中心位置:脚部位置 + 实体朝向旋转 (0, 0, 中心到脚偏移)。
Derives the capsule-center location from the foot transform: foot location + entity rotation applied to (0, 0, center-to-foot offset).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
AgentComponent | const UMassBattleAgentComponent* | 源组件。Source component. |
FootTransform | const FTransform& | 脚部变换。Foot transform. |
Output
返回胶囊中心位置。无副作用。
Returns the capsule-center location. No side effects.
把"胶囊中心"变换换算为"actor 脚部"变换:中心位置沿脚部朝向的胶囊中心偏移下移。组件或配置资产缺失时原样返回。
Converts a capsule-center transform into an actor-foot transform: the location is lowered along the foot orientation by the capsule-center offset. Returns the input unchanged without a component or config asset.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
AgentComponent | const UMassBattleAgentComponent* | 源组件。Source component. |
FootTransform | const FTransform& | 输入变换(被视为脚部)。Input transform (treated as the foot). |
Output
返回上移后的变换。
Returns the raised transform.
把 agent 胶囊中心变换换算为 actor 变换:先下移到脚部(StaticGetAgentCenterToFootOffset),再按脚部路径抬升(StaticGetActorTransformForAgentFoot)——两步组合得到 actor 级脚部变换。组件缺失时原样返回。
Converts an agent capsule-center transform into an actor transform: first lowers to the foot (StaticGetAgentCenterToFootOffset), then raises via the foot path (StaticGetActorTransformForAgentFoot) — the two steps yield the actor-level foot transform. Returns the input unchanged without a component.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
AgentComponent | const UMassBattleAgentComponent* | 源组件。Source component. |
AgentCenterTransform | const FTransform& | agent 胶囊中心变换。Agent capsule-center transform. |
Output
返回 actor 级变换。无副作用。
Returns the actor-level transform. No side effects.
用既有实体初始化组件(对象池/重绑路径):已绑定其它实体时直接返回;同实体重入时允许刷新。写入 FVisualizing.BindingComponentPtr/BindingActorPtr(修复快照后的过期指针)、FAgentEventRT.EventReceiveActor;保存并恢复用户同步模式后捕获初始相对变换;盖章本地 PC 缓存;清 bPendingRebind;广播 OnAgentInitialized。
Initializes the component with an existing entity (pooling/rebind path): returns when bound to a different entity; re-entry with the same entity refreshes. Writes FVisualizing.BindingComponentPtr/BindingActorPtr (fixes stale pointers after snapshot restore) and FAgentEventRT.EventReceiveActor; captures initial relative transforms around a save/restore of the user sync modes; stamps local PC caches; clears bPendingRebind; broadcasts OnAgentInitialized.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
InEntityHandle | FEntityHandle | 要绑定的实体。The entity to bind. |
Output
无返回值。副作用:fragment 绑定指针写入、相对变换捕获、事件广播。
No return value. Side effects: fragment binding pointers, relative-transform capture, event broadcast.
解绑实体:实体仍有效时清 FVisualizing.BindingComponentPtr(仅当指向本组件)与 BindingActorPtr/FAgentEventRT.EventReceiveActor(仅当指向本 owner —— 防止 owner 销毁后残留悬垂指针导致 ProcessEventQueues 崩溃);清零句柄与 bIsMassInitialized;重置同步模式为 None;失效相对变换标志。
Unbinds the entity: while the entity is valid, clears FVisualizing.BindingComponentPtr (only when it points at this component) and BindingActorPtr/FAgentEventRT.EventReceiveActor (only when they point at this owner — prevents dangling pointers crashing ProcessEventQueues after owner destruction); zeroes the handle and bIsMassInitialized; resets sync modes to None; invalidates the relative-transform flags.
Input
无参数。
No parameters.
Output
无返回值。副作用:上述解绑与复位。
No return value. Side effects: the unbinding and resets above.
加载后迁移钩子:调用 Multipliers.MigrateLegacyMultipliers() 把旧版浮点乘数迁移到新版 FVector2D 范围(旧值非默认且范围仍为默认时,拷贝旧值至 X=Y,旧值重置为 1)。
Post-load migration hook: calls Multipliers.MigrateLegacyMultipliers() to migrate legacy float multipliers to the new FVector2D ranges (when the legacy value is non-default and the range is still default, copies the legacy value to X=Y and resets the legacy to 1).
Input
无参数。
No parameters.
Output
无返回值。副作用:乘数迁移。
No return value. Side effect: multiplier migration.
① 调用基类(基类已执行 SetIsReplicated + ID 预分配 + 网络校验);② 锁步会话路径:owner 为 ACharacter 时调用 ApplyControlModeConfiguration(现为空操作钩子);服务器 + Auto 模式且未被门控 1 拦截(owner 未复制时不注册——指令在客户端永远找不到组件)时向 GameMode 注册待生成(RegisterPendingLockstepSpawn),在 tick 边界冲刷;随后返回(生成由锁步指令驱动);③ 非锁步:已初始化或未配置资产则休眠(等池化调用 InitializeWithEntity);Auto 模式下仅本地控制或服务器拥有的 Pawn 才调用 ManualInitialize()。
① Calls the base (which already ran SetIsReplicated + ID pre-allocation + network validation); ② lockstep-session path: calls ApplyControlModeConfiguration (now a no-op hook) when the owner is an ACharacter; server + Auto mode and not gate-1 blocked (non-replicated owner never registers — the command would never find its component on clients) registers with the GameMode (RegisterPendingLockstepSpawn) for flushing at the tick boundary, then returns (spawn is driven by the lockstep command); ③ non-lockstep: returns when already initialized or without a config asset (dormant, waiting for pooling to call InitializeWithEntity); in Auto mode only locally-controlled or server-owned pawns call ManualInitialize().
Input
无参数。
No parameters.
Output
无返回值。副作用:锁步注册 / 自动生成 / 休眠分流。
No return value. Side effects: lockstep registration / auto spawn / dormant split.
① 基类先注销宿主注册表;② 未初始化则返回;③ 对象池路径(bDestroyEntityOnEndPlay == false):仅 DeinitializeFromEntity,实体保留复用;④ 非锁步会话(单机):本地标 PendingDestroy 标志并入销毁队列;⑤ 锁步会话:服务器广播 AgentComponent.Despawn 锁步指令(双端同一 ExecuteTick 销毁),本地仅解绑。
① Base unregisters the host registry first; ② returns when not initialized; ③ object-pool path (bDestroyEntityOnEndPlay == false): only DeinitializeFromEntity, the entity stays alive for reuse; ④ non-lockstep session (standalone): marks PendingDestroy locally and enqueues destruction; ⑤ lockstep session: the server broadcasts the AgentComponent.Despawn lockstep command (both peers destroy at the same ExecuteTick), local side only unbinds.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
EndPlayReason | EEndPlayReason::Type | 结束播放原因。End-play reason. |
Output
无返回值。副作用:销毁实体(本地)或广播 Despawn 指令(网络)并解绑。
No return value. Side effects: entity destruction (local) or Despawn command broadcast (network) plus unbinding.
声明 OwningPlayerIndex 参与复制,并转发父类(LockstepNetID)。
Declares OwningPlayerIndex for replication and forwards to the parent (LockstepNetID).
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
OutLifetimeProps | TArray<FLifetimeProperty>& | 复制属性列表。Replicated property list. |
Output
无返回值。副作用:追加 OwningPlayerIndex。
No return value. Side effect: appends OwningPlayerIndex.
成员变量 Members
初始化模式:Auto(BeginPlay 自动生成)/ Manual(调用 ManualInitialize)。枚举定义于 MassBattleEnums.h;工具提示文本提及的 "Disabled" 值在枚举中不存在(提示文本滞后)。
Initialization mode: Auto (spawn in BeginPlay) / Manual (call ManualInitialize). Enum defined in MassBattleEnums.h; the "Disabled" value mentioned in the tooltip text does not exist in the enum (stale tooltip).
单位配置数据资产,模板构建的数据源。未设置时组件处于休眠状态(等待池化系统调用 InitializeWithEntity)。
Agent configuration data asset, the data source for template building. When unset the component stays dormant (waiting for the pooling system to call InitializeWithEntity).
队伍索引,生成时写入 agent。
Team index, written to the agent at spawn.
发射速度,生成时传给生成器。
Launch velocity, passed to the spawner at spawn.
生成器乘数(见 MassBattleStructs.h 的 FSpawnerMult):血/速/伤/缩放四组乘数,新版为 [X=min, Y=max] 范围、每实体生成时随机取值;旧版浮点字段仅序列化保留,PostLoad 时经 MigrateLegacyMultipliers 一次性迁移。
Spawner multipliers (see FSpawnerMult in MassBattleStructs.h): four groups — health/speed/damage/scale — as [X=min, Y=max] ranges picked per entity at spawn; the legacy float fields are serialization-only and migrated once by MigrateLegacyMultipliers in PostLoad.
为 true 时仅同步倾斜(俯仰/翻滚),偏航角自由 —— 适用于随载具倾斜但独立瞄准的炮塔。仅当 RotationSyncMode 为 ComponentToEntity / EntityToComponent / EntityToActor 时生效;不影响实体的 DesiredRotationQuat(行为/AI 仍可控制偏航)。
When true, only syncs tilt (pitch/roll), leaving yaw free — for turrets that tilt with their parent vehicle but aim independently. Effective only when RotationSyncMode is ComponentToEntity / EntityToComponent / EntityToActor; does not touch the entity's DesiredRotationQuat (behavior/AI can still control yaw).
EndPlay 时是否销毁实体。false = 对象池路径,仅解绑、实体保留复用。
Whether to destroy the entity on EndPlay. false = object-pool path: unbind only, entity kept for reuse.
实体绑定完成事件(无参动态多播委托)。生成/重绑成功时广播。
Entity-bound event (parameterless dynamic multicast delegate). Broadcast on successful spawn/rebind.
两端锁步 spawn 时本地分配的实体 UID(不复制 —— 锁步保证两端相等),兼作 agent 的全局 UID。快照重绑时从实体 FDeterminism.UniqueID 同步。
Entity UID allocated locally on both peers at lockstep spawn time (NOT replicated — lockstep keeps both ends equal); doubles as the agent's global UID. Synced from the entity's FDeterminism.UniqueID on snapshot rebind.
复制玩家索引,生成/绑定时设置,用于跨客户端 Character 查找。仅对玩家拥有的 agent 有效。
Replicated player index, set during spawn/bind, used for cross-client Character lookup. Only valid for player-owned agents.
CC 模式 EnhancedInput 同步 AgentTransform 的限频标记:每 MassBattle tick 最多发送一次变换。
Rate-limit marker for Enhanced Input AgentTransform sync in CC mode: at most one transform per MassBattle tick.
惰性缓存的 agent 生成器子系统指针。
Lazily-cached agent spawner subsystem pointer.
管线角色 Pipeline Role
本地路径:BeginPlay(Auto)→ ManualInitialize → CreateTemplateFromConfig(经 UMassBattleAgentSubsystem::MakeAgentTemplateDataFromDataAsset)→ SpawnAgentFromTemplate → SpawnAgentsByTemplateRectangular(生成器)写 FVisualizing 绑定 → 广播 OnAgentInitialized → SyncAgentTagsAndController 同步标签。锁步路径:BeginPlay 服务器侧经 RegisterPendingLockstepSpawn 注册,GameMode 在确定性 tick 边界经 ProcessPendingLockstepSpawns(含 IsClientAwaitingResync 检查)冲刷并广播 AgentComponent.Spawn;双端在同一 ExecuteTick 执行 SpawnLockstepAgent_Internal(UID 本地分配)。快照恢复后,resync 重链 pass 调用 RebindToEntity(按 FAgentController.LockstepNetID 扫描 GlobalUIDToHandle)。每帧 TickComponent → SyncTransform 执行三轴同步;销毁时服务器广播 AgentComponent.Despawn。
Local path: BeginPlay (Auto) → ManualInitialize → CreateTemplateFromConfig (via UMassBattleAgentSubsystem::MakeAgentTemplateDataFromDataAsset) → SpawnAgentFromTemplate → SpawnAgentsByTemplateRectangular (spawner) writes FVisualizing bindings → broadcasts OnAgentInitialized → SyncAgentTagsAndController syncs tags. Lockstep path: on the server BeginPlay registers via RegisterPendingLockstepSpawn; the GameMode flushes at the deterministic tick boundary via ProcessPendingLockstepSpawns (including the IsClientAwaitingResync check) and broadcasts AgentComponent.Spawn; both peers execute SpawnLockstepAgent_Internal at the same ExecuteTick (UID allocated locally). After snapshot restore the resync re-link pass calls RebindToEntity (scans GlobalUIDToHandle by FAgentController.LockstepNetID). Each frame TickComponent → SyncTransform runs the three-axis sync; on destruction the server broadcasts AgentComponent.Despawn.
补充说明 Notes
头文件中的注释 (ApplyCharacterTransformToAgent removed …) 说明:组件→实体变换同步已由锁步 Agent.SetTransform 指令驱动,原函数被移除。另注意 InitializationMode 的 Tooltip 提到 "Disabled (pooling)",但 EAgentInitMode 枚举当前只有 Auto/Manual 两个值 —— 提示文本滞后于枚举。
The header comment (ApplyCharacterTransformToAgent removed …) notes that component→entity transform sync is now driven by the lockstep Agent.SetTransform command and the old function was removed. Also note the InitializationMode tooltip mentions "Disabled (pooling)", but EAgentInitMode currently has only Auto/Manual — the tooltip text lags behind the enum.