ActorHostConfig.h

USTRUCT ×3

Source/MassBattle/Public/Fragments/ActorHostConfig.h

概述 Overview

Actor 宿主(Actor host)的生成配置集合。包含两级结构:作者配置 FActorSpawnConfig / FActorSpawnConfig_Attack(策划在 EntityConfig 中填写,含概率、延迟、动画绑定等参数)与 运行时 Final fragment FActorSpawnConfig_Final(经转换构造注入,附加随机流、归属实体句柄与生成生命周期状态,由宿主处理器逐帧推进)。文件末尾的 FActorOptCommand 是宿主 UObject 操作(spawn/despawn)的命令缓冲记录。

Actor-host spawn configuration collection. Two tiers: authored config FActorSpawnConfig / FActorSpawnConfig_Attack (designer-filled in EntityConfig, with probability, delay, animation binding, etc.) and the runtime Final fragment FActorSpawnConfig_Final (injected via converting constructors, adding a random stream, ownership handles and spawn lifecycle state advanced by host processors). FActorOptCommand at the end of the file is the command-buffer record for host UObject ops (spawn/despawn).

FActorSpawnConfig USTRUCT

通用 Actor 生成配置(非 fragment,供各类宿主配置数组使用,如 FAppear::SpawnActor / FDeath::SpawnActor)。不含 SpawnOrigin 字段(无 origin 需求场景)。

Generic actor spawn config (not a fragment; used in host config arrays such as FAppear::SpawnActor / FDeath::SpawnActor). Has no SpawnOrigin field (for scenarios without an origin need).

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`bEnable`	`bool`	`true`	是否启用生成。Enable spawning.
`SoftActorClass`	`TSoftClassPtr<AActor>`	—	要生成的 Actor 类的软引用。Soft reference to the Actor class to spawn.
`ActorClass`	`TSubclassOf<AActor>`	`nullptr`	硬引用 Actor 类(非蓝图编辑,运行时由软引用解析填充)。Hard actor class reference (not editable; resolved from the soft reference at runtime).
`Transform`	`FTransform3f`	`Identity`	相对于实体的生成偏移量。Spawn offset transform relative to the entity.
`bAttached`	`bool`	`false`	生成的 Actor 是否附着到实体拥有者。Whether the spawned Actor is attached to the entity's owner.
`Delay`	`float`	`0`	开始生成前的延时(秒)。Delay in seconds before spawning starts.
`LifeSpan`	`float`	`-1`	生成后 Actor 的存活时长(秒),负值为无限长。Lifespan of the spawned Actor in seconds; negative means infinite.
`BindToAnimIndex`	`int32`	`-1`	绑定动画索引:>= 0 时仅在使用该动画索引时生成;-1 则对所有动画生成。Animation index binding: >= 0 spawns only when that animation index is used; -1 spawns for all animations.
`bDespawnWhenNoParent`	`bool`	`true`	如果已附着,父级附着实体丢失时自毁 Actor。仅 `bEnable` 与 `bAttached` 均为 true 时可编辑。If attached, despawn the Actor when the parent attachment entity is lost. Editable only when both `bEnable` and `bAttached` are true.
`SpawnProbability`	`FVector4f`	`(0, 1, 10000, 1)`	生成概率参数:X=AgentCountMin, Y=SpawnProbabilityAtMin, Z=AgentCountMax, W=SpawnProbabilityAtMax。AgentCount 指具有指定行为的 Agent 数量。Spawn probability parameters: X=AgentCountMin, Y=SpawnProbabilityAtMin, Z=AgentCountMax, W=SpawnProbabilityAtMax. AgentCount counts agents with the specified behavior.
`AgentBehaviorState`	`EAgentBehaviorState`	`None`	该 Actor 关联的 Agent 行为状态,用于概率计算。Agent behavior state this actor is associated with, used for probability calculations.
`bLockstepNetworked`	`bool`	`false`	该宿主是否参与网络同步(snapshot/hash/resync)。同步与不同步宿主在池中共存——弹池按 `FNetworkTag` 匹配槽位。仅 `bEnable` 为 true 时可编辑。Whether this host participates in network sync (snapshot/hash/resync). Sync and non-sync hosts coexist in pools — slots are matched by `FNetworkTag` at pop time. Editable only when `bEnable` is true.

FActorSpawnConfig_Attack USTRUCT

攻击命中时刻使用的 Actor 生成配置,与 FActorSpawnConfig 字段完全一致,额外多出 SpawnOrigin(生成位置源,如自身/目标位置)。用于 FAttack::SpawnActor。

Actor spawn config used at the attack hit moment; fields identical to FActorSpawnConfig plus SpawnOrigin (spawn location source, e.g. AtSelf / AtTarget). Used by FAttack::SpawnActor.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`SpawnOrigin`	`ESpawnOrigin`	`AtSelf`	生成 Actor 的位置源(例如在自身位置、在目标位置)。Location source for spawning the Actor (e.g. AtSelf, AtTarget).
`bEnable` 等其余字段	同 `FActorSpawnConfig`	同左	字段与 `FActorSpawnConfig` 完全相同(bEnable / SoftActorClass / ActorClass / Transform / bAttached / Delay / LifeSpan / BindToAnimIndex / bDespawnWhenNoParent / SpawnProbability / AgentBehaviorState / bLockstepNetworked)。Fields identical to `FActorSpawnConfig` (bEnable / SoftActorClass / ActorClass / Transform / bAttached / Delay / LifeSpan / BindToAnimIndex / bDespawnWhenNoParent / SpawnProbability / AgentBehaviorState / bLockstepNetworked).

FActorSpawnConfig_Final USTRUCT

Actor 宿主运行时 fragment(FA_MassBattleBaseFragment 派生)。由 FActorSpawnConfig 或 FActorSpawnConfig_Attack 经转换构造注入——FActorSpawnConfig_Attack 来源时额外拷贝 SpawnOrigin。前部为配置字段,后部(RandomStream 起)为运行时状态:随机流、归属实体句柄、生成生命周期标志与对象池字段。经 MASS_FRAGMENT_ACCEPT_NOT_TRIVIALLY_COPYABLE 声明为不可平凡拷贝(含 TObjectPtr 成员)。

Actor-host runtime fragment (derived from FA_MassBattleBaseFragment). Injected from FActorSpawnConfig or FActorSpawnConfig_Attack via converting constructors — the _Attack source additionally copies SpawnOrigin. The leading fields are config; the trailing block (from RandomStream) is runtime state: random stream, ownership handles, spawn lifecycle flags and pooling fields. Declared via MASS_FRAGMENT_ACCEPT_NOT_TRIVIALLY_COPYABLE as not-trivially-copyable (contains TObjectPtr members).

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`bEnable` … `bLockstepNetworked`	同 `FActorSpawnConfig_Attack`	同左	配置段:与 `FActorSpawnConfig_Attack` 相同的 13 个字段(含 `SpawnOrigin`)。Config block: same 13 fields as `FActorSpawnConfig_Attack` (including `SpawnOrigin`).
`RandomStream`	`FRandomStream`	—	概率检查的随机流(运行时)。Random stream for probability checks (runtime).
`OwnerEntity`	`FEntityHandle`	—	创建并拥有此生成配置的实体。Entity that created and owns this spawn configuration.
`HostEntity`	`FEntityHandle`	—	负责管理此已生成 Actor 的实体(如果与生成者不同)。Entity responsible for managing the spawned actor (if different from the owner).
`AttachToEntity`	`FEntityHandle`	—	要将已生成 Actor 附着到的目标实体。Target entity to attach the spawned Actor to.
`SpawnTransform`	`FTransform`	—	最终生成 Actor 的世界变换(运行时计算)。Final world transform where the Actor is spawned (computed at runtime).
`InitialRelativeTransform`	`FTransform3f`	—	如果已附着,生成 Actor 的初始相对变换。Initial relative transform of the spawned Actor if attached.
`bInitialized`	`bool`	`false`	初始化标志(运行时)。Initialized flag (runtime).
`bSpawned`	`bool`	`false`	已生成标志(运行时)。Spawned flag (runtime).
`bIsPooled`	`bool`	`false`	是否来自对象池(运行时)。Whether from the object pool (runtime).
`bShouldDestroy`	`bool`	`false`	为 true 时宿主实体将在下一帧被销毁。When true, the host entity is destroyed on the next tick.
`PoolCountdown`	`float`	`15.0f`	对象池保留倒计时(秒)。回收复用时由 `Reset(InPoolIdleTTL)` 按统一池闲置倒计时(HostSubsystem `PoolIdleLifeSpan`)重置。Pool retention countdown in seconds. On recycle-reuse it is reset by `Reset(InPoolIdleTTL)` from the unified pool idle countdown (the HostSubsystem's `PoolIdleLifeSpan`).
`SpawnedActor`	`TObjectPtr<AActor>`	`nullptr`	已生成的 Actor 实例指针(运行时,非 UPROPERTY 不序列化)。Spawned Actor instance pointer (runtime, not a UPROPERTY, not serialized).
`bNeedsSpawnRefresh`	`bool`	`false`	resync 后瞬态:恢复端置位,HostMonoProcessor 刷新段消费——只重发 UObject actor 生成 op,不重跑概率(会双消费 `RandomStream.FRand`)。不进任何注册表。Post-resync transient: set by restore, consumed by the HostMonoProcessor refresh pass — re-issues the UObject actor spawn op without re-running probability (would double-consume `RandomStream.FRand`). Never enters any registry.

方法 Methods

FActorSpawnConfig_Final (constructor) FActorSpawnConfig_Final(const FActorSpawnConfig&)

从 FActorSpawnConfig 逐字段拷贝生成;该来源无 SpawnOrigin,故 Final 的 SpawnOrigin 保持默认 AtSelf。

Field-by-field copy from FActorSpawnConfig; the source has no SpawnOrigin, so the Final's SpawnOrigin stays at the default AtSelf.

Input

参数 Param	类型 Type	说明 Description
`Config`	`const FActorSpawnConfig&`	作者配置源。Authored config source.

Output

无返回值。副作用:全字段初始化(不含 SpawnOrigin)。

No return value. Side effect: all fields initialized (excluding SpawnOrigin).

FActorSpawnConfig_Final (constructor) FActorSpawnConfig_Final(const FActorSpawnConfig_Attack&)

从 FActorSpawnConfig_Attack 逐字段拷贝生成,额外拷贝 SpawnOrigin。

Field-by-field copy from FActorSpawnConfig_Attack, additionally copying SpawnOrigin.

Input

参数 Param	类型 Type	说明 Description
`Config`	`const FActorSpawnConfig_Attack&`	攻击场景的作者配置源。Attack-scenario authored config source.

Output

无返回值。副作用:全字段初始化(含 SpawnOrigin)。

No return value. Side effect: all fields initialized (including SpawnOrigin).

Reset void (float InPoolIdleTTL = 15.0f)

复位运行时状态以复用:bInitialized/bSpawned/bShouldDestroy/bNeedsSpawnRefresh 清零、bIsPooled=true、PoolCountdown=InPoolIdleTTL、三个实体句柄清空。SpawnedActor 不在此处清理。InPoolIdleTTL 是统一池闲置倒计时(HostSubsystem 的 PoolIdleLifeSpan);默认值 15 保证非回收调用点行为不变。

Resets runtime state for reuse: clears bInitialized/bSpawned/bShouldDestroy/bNeedsSpawnRefresh, sets bIsPooled=true, PoolCountdown=InPoolIdleTTL, and clears the three entity handles. SpawnedActor is not cleaned here. InPoolIdleTTL is the unified pool idle countdown (the HostSubsystem's PoolIdleLifeSpan); the 15 default keeps non-recycle call sites unchanged.

Input

参数 Param	类型 Type	说明 Description
`InPoolIdleTTL`	`float`	池闲置倒计时初值(秒),写入 `PoolCountdown`;默认 15。回收路径传入 HostSubsystem 的 `PoolIdleLifeSpan`。Initial pool idle countdown in seconds, written into `PoolCountdown`; default 15. Recycle paths pass the HostSubsystem's `PoolIdleLifeSpan`.

Output

无返回值。副作用:运行时状态复位,池倒计时按入参重置。

No return value. Side effect: runtime state reset with the pool countdown set from the parameter.

FActorOptCommand USTRUCT

命令缓冲记录:宿主实体对 UObject Actor 的操作请求(默认 Spawn)。由宿主逻辑写入,MassBattleHostMonoProcessor 消费执行。

Command-buffer record: a host entity's operation request on a UObject Actor (default Spawn). Written by host logic, consumed by MassBattleHostMonoProcessor.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`Entity`	`FMassEntityHandle`	—	操作关联的宿主实体。Host entity associated with the operation.
`OperationType`	`EUObjectOptType`	`Spawn`	操作类型(生成/销毁等)。Operation type (spawn / destroy, etc.).
`OwnerUniqueID`	`int32`	`-1`	所属实体 UID,`-1` 为无效。Owner entity UID; `-1` = invalid.

管线角色 Pipeline Role

FActorSpawnConfig_Final 由 UMassBattleHostSubsystem 在宿主实体创建时从作者配置转换注入;FActorOptCommand 由宿主逻辑写入命令缓冲,MassBattleHostMonoProcessor 消费执行 UObject Actor 的生成/销毁;Reset() 在宿主回池复用时调用(宿主处理器与 Agent/Host 子系统路径)。网络同步宿主经 bLockstepNetworked 参与快照/hash/resync。

FActorSpawnConfig_Final is injected from authored config by UMassBattleHostSubsystem at host-entity creation; FActorOptCommand is written to the command buffer by host logic and consumed by MassBattleHostMonoProcessor to spawn/destroy UObject Actors; Reset() runs on host pool reuse (host processor and Agent/Host subsystem paths). Networked hosts participate in snapshot/hash/resync via bLockstepNetworked.