SoundHostConfig.h

USTRUCT ×4 UENUM ×1

Source/MassBattle/Public/Fragments/SoundHostConfig.h

概述 Overview

音效宿主配置与运行时 fragment 集合。三个配置结构由浅入深:FSoundConfig(通用音效配置)、FSoundConfig_Attack(攻击专用,额外带生成原点 EPlaySoundOrigin_Attack)、FSoundConfig_Final(宿主实体实际携带的 fragment,由前两者转换而来并追加运行时状态:随机流、生成者/附着句柄、池状态、UAudioComponent 指针)。配套模拟层音效并发控制(简化版 FSoundConcurrencyConfig + 规则枚举 ESoundConcurrencyRule),在确定性宿主生成 drain 段裁决:满员时拒绝新宿主(PreventNew)或逐出旧宿主(StopOldest/StopLowestPriority),逐出遵守 MinPlayTime 保护。另有命令缓冲条目 FSoundOptCommand。

Sound-host config and runtime fragment collection. Three config structs of increasing depth: FSoundConfig (generic sound config), FSoundConfig_Attack (attack-specific, adds spawn origin EPlaySoundOrigin_Attack), FSoundConfig_Final (the fragment actually carried by host entities; converted from either of the former, with runtime state appended: random stream, owner/attach handles, pool state, UAudioComponent pointer). Paired with simulation-layer sound concurrency (simplified FSoundConcurrencyConfig + rule enum ESoundConcurrencyRule), adjudicated at the deterministic host-spawn drain: at max count the new host is either rejected (PreventNew) or an existing host is evicted (StopOldest/StopLowestPriority), eviction honoring MinPlayTime. Also defines the command-buffer entry FSoundOptCommand.

ESoundConcurrencyRule UENUM

并发满员时的处理规则。按 Sound 资产(SoftSound)分组,与引擎语义一致——共用同一资产的配置共享一个计数。

Resolution rule when a concurrency group is at max count. Grouped per sound asset (SoftSound), matching engine semantics — all configs sharing one asset share one counter.

值 Value	说明 Description
`PreventNew`	满员拒绝新宿主(不生成)。Reject the new host at max count.
`StopOldest`	满员回收最老宿主播新的(默认)。Evict the oldest host and play the new one (default).
`StopLowestPriority`	满员回收最低优先级宿主。Evict the lowest-priority host.

FSoundConcurrencyConfig USTRUCT

模拟层音效并发配置(简化版 UE FSoundConcurrencySettings)。规则在确定性宿主生成 drain 段裁决——逐出遵守 MinPlayTime(播放不足该时长的宿主绝不被掐,防碎片化听感);无满足候选时拒绝新宿主(PreventNew 兜底)。

Simulation-layer sound concurrency config (simplified UE FSoundConcurrencySettings). Rules are adjudicated at the deterministic host-spawn drain — eviction honors MinPlayTime (hosts that played less than that are never cut, preventing fragment-soup audio); when no candidate satisfies it, the new host is rejected (PreventNew fallback).

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`MaxCount`	`int32`	`-1`	每音效资产最大并发宿主数;-1 = 不限(默认,现有配置零改动行为不变)。Max concurrent hosts per sound asset; -1 = unlimited (default, zero-change for existing configs).
`ResolutionRule`	`ESoundConcurrencyRule`	`StopOldest`	满员时的处理规则。Resolution when the group is at MaxCount.
`RetriggerTime`	`float`	`0.0f`	同属主最小触发间隔(秒);0 = 不限。防高频刷音(攻击连发)。Min interval (s) between triggers of the same owner; 0 = unlimited. Anti-spam for rapid attacks.
`MinPlayTime`	`float`	`1.0f`	可被逐出的最小播放时长(秒);对所有逐出规则生效;无满足候选时拒绝新宿主(PreventNew 兜底)。0 = 无保护。Min played time (s) before a host may be evicted; applies to ALL eviction rules; when no candidate satisfies it the new host is rejected (PreventNew fallback). 0 = no protection.
`bLimitToOwner`	`bool`	`false`	true = 按属主(OwnerEntity)分组计数;false = 按资产分组(所有属主共享)。true = count per owner (OwnerEntity); false = count per asset group (all owners share).
`Priority`	`float`	`0.0f`	配合 `StopLowestPriority` 使用的优先级(0-100)。Priority (0-100) for StopLowestPriority.

方法 Methods

IsEnabled bool (const)

并发控制是否生效:MaxCount > 0 或 RetriggerTime > 0。

Whether concurrency control is active: MaxCount > 0 OR RetriggerTime > 0.

Input

无参数。

No parameters.

Output

返回两字段的或运算结果;无副作用。

Returns the OR of the two fields; no side effects.

FSoundConfig USTRUCT

通用音效生成配置(非 fragment,挂在其它配置结构内)。策划在 EntityConfig 中可调;带概率参数 SpawnProbability(按指定行为的 Agent 数量插值)与行为状态关联。除 Concurrency 外,配置字段均受 bEnable EditCondition 控制;bDespawnWhenNoParent 额外要求 bAttached == true。

Generic sound spawn config (not a fragment; embedded in other config structs). Designer-tunable in EntityConfig; carries a probability parameter SpawnProbability (interpolated by the count of agents with the specified behavior) and a behavior-state association. Except Concurrency, the config fields are gated by the bEnable EditCondition; bDespawnWhenNoParent additionally requires bAttached == true.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`bEnable`	`bool`	`true`	是否启用该音效。Whether the sound is enabled.
`SoftSound`	`TSoftObjectPtr<USoundBase>`	`nullptr`	音效资产软引用(编辑器显示名 "SoundAsset")。Sound asset soft reference (editor display name "SoundAsset").
`Sound`	`TObjectPtr<USoundBase>`	`nullptr`	解析后的音效资产(运行时填充,非 UPROPERTY 配置)。Resolved sound asset (filled at runtime; not a config UPROPERTY).
`Transform`	`FTransform3f`	`Identity`	生成偏移量。Spawn offset.
`bAttached`	`bool`	`false`	是否附着到实体。Whether the sound is attached.
`bDespawnWhenNoParent`	`bool`	`true`	附着点失效后自毁。仅当 `bEnable` 且 `bAttached` 均为 true 时可编辑。Destroy when the attachment point becomes invalid. Editable only when both `bEnable` and `bAttached` are true.
`bLockstepNetworked`	`bool`	`false`	该宿主是否参与网络同步(snapshot/hash/resync)。同步与不同步宿主在池中共存——弹池按 `FNetworkTag` 匹配槽位。受 `bEnable` EditCondition 控制。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. Gated by the `bEnable` EditCondition.
`Delay`	`float`	`0`	延时生成(秒)。Spawn delay (seconds).
`Volume`	`float`	`1`	音量。Volume.
`LifeSpan`	`float`	`5`	生成后存活时长(秒),负值为无限长。Lifespan after spawn (seconds); negative = infinite.
`RadiusThreshold`	`float`	`10000.0f`	3D 音效:与监听者距离大于该值则不播放。For 3D sounds: not played when farther than this from the listener.
`BindToAnimIndex`	`int32`	`-1`	绑定到特定动画索引。>= 0 时仅在使用该动画索引时生成;-1 对所有动画生成。Bind to a specific animation index: >= 0 spawns only with that animation index; -1 spawns for all animations.
`SpawnProbability`	`FVector4f`	`(0, 1, 10000, 1)`	生成概率参数 (X=AgentCountMin, Y=SpawnProbabilityAtMin, Z=AgentCountMax, W=SpawnProbabilityAtMax)。AgentCount 是具有指定行为的 Agent 数量,不是 Agent 总数。Spawn probability params (X=AgentCountMin, Y=SpawnProbabilityAtMin, Z=AgentCountMax, W=SpawnProbabilityAtMax). AgentCount is the number of agents with the specified behavior, not the total.
`AgentBehaviorState`	`EAgentBehaviorState`	`None`	该音效关联的 Agent 行为状态,用于概率计算。The agent behavior state this sound is associated with, used for probability calculations.
`Concurrency`	`FSoundConcurrencyConfig`	—	模拟层并发控制。Simulation-layer concurrency control.

FSoundConfig_Attack USTRUCT

攻击专用音效配置:字段与 FSoundConfig 相同,差别为:① 额外带生成原点 SpawnOrigin(EPlaySoundOrigin_Attack:2D / 自身 3D / 目标 3D);② AgentBehaviorState 默认值为 Attacking。

Attack-specific sound config: same fields as FSoundConfig except: ① it adds the spawn origin SpawnOrigin (EPlaySoundOrigin_Attack: 2D / 3D at self / 3D at target); ② AgentBehaviorState defaults to Attacking.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`bEnable`	`bool`	`true`	是否启用该音效。Whether the sound is enabled.
`SoftSound`	`TSoftObjectPtr<USoundBase>`	`nullptr`	音效资产软引用。Sound asset soft reference.
`Sound`	`TObjectPtr<USoundBase>`	`nullptr`	解析后的音效资产(运行时填充)。Resolved sound asset (filled at runtime).
`Transform`	`FTransform3f`	`Identity`	生成偏移量。Spawn offset.
`bAttached`	`bool`	`false`	是否附着到实体。Whether the sound is attached.
`bDespawnWhenNoParent`	`bool`	`true`	附着点失效后自毁。仅当 `bEnable` 且 `bAttached` 均为 true 时可编辑。Destroy when the attachment point becomes invalid. Editable only when both `bEnable` and `bAttached` are true.
`bLockstepNetworked`	`bool`	`false`	该宿主是否参与网络同步(snapshot/hash/resync)。受 `bEnable` EditCondition 控制。Whether this host participates in network sync (snapshot/hash/resync). Gated by the `bEnable` EditCondition.
`SpawnOrigin`	`EPlaySoundOrigin_Attack`	`PlaySound2D`	生成原点:2D / 自身 3D / 目标 3D。Spawn origin: 2D / 3D at self / 3D at target.
`Delay`	`float`	`0`	延时生成(秒)。Spawn delay (seconds).
`Volume`	`float`	`1`	音量。Volume.
`LifeSpan`	`float`	`5`	生成后存活时长(秒),负值为无限长。Lifespan after spawn (seconds); negative = infinite.
`RadiusThreshold`	`float`	`10000.0f`	3D 音效:与监听者距离大于该值则不播放。For 3D sounds: not played when farther than this from the listener.
`BindToAnimIndex`	`int32`	`-1`	绑定到特定动画索引;-1 对所有动画生成。Bind to a specific animation index; -1 spawns for all animations.
`SpawnProbability`	`FVector4f`	`(0, 1, 10000, 1)`	生成概率参数(见 `FSoundConfig`)。Spawn probability params (see `FSoundConfig`).
`AgentBehaviorState`	`EAgentBehaviorState`	`Attacking`	关联的 Agent 行为状态(默认 `Attacking`)。Associated agent behavior state (defaults to `Attacking`).
`Concurrency`	`FSoundConcurrencyConfig`	—	模拟层并发控制。Simulation-layer concurrency control.

FSoundConfig_Final USTRUCT

音效宿主实体实际携带的 fragment(FA_MassBattleBaseFragment 派生)。由 FSoundConfig 或 FSoundConfig_Attack 转换构造(转换时 EPlaySoundOrigin_Attack 的 3D 两值归一为 EPlaySoundOrigin::PlaySound3D),并追加运行时状态。含 RandomStream(生成概率 / 随机延迟用,确定性种子)、池状态与 UAudioComponent 指针。经 MASS_FRAGMENT_ACCEPT_NOT_TRIVIALLY_COPYABLE 声明。

Fragment actually carried by sound host entities (derived from FA_MassBattleBaseFragment). Constructed by conversion from FSoundConfig or FSoundConfig_Attack (the two 3D values of EPlaySoundOrigin_Attack normalize to EPlaySoundOrigin::PlaySound3D), appending runtime state: a RandomStream (deterministically seeded, for spawn probability / random delay), pool state and the UAudioComponent pointer. Declared via MASS_FRAGMENT_ACCEPT_NOT_TRIVIALLY_COPYABLE.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`bEnable`	`bool`	`true`	是否启用该音效。Whether the sound is enabled.
`SoftSound`	`TSoftObjectPtr<USoundBase>`	`nullptr`	音效资产软引用。Sound asset soft reference.
`Sound`	`TObjectPtr<USoundBase>`	`nullptr`	解析后的音效资产(运行时填充)。Resolved sound asset (filled at runtime).
`Transform`	`FTransform3f`	`Identity`	生成偏移量。Spawn offset.
`bAttached`	`bool`	`false`	是否附着到实体。Whether the sound is attached.
`bDespawnWhenNoParent`	`bool`	`true`	附着点失效后自毁。仅当 `bEnable` 且 `bAttached` 均为 true 时可编辑。Destroy when the attachment point becomes invalid. Editable only when both `bEnable` and `bAttached` are true.
`bLockstepNetworked`	`bool`	`false`	该宿主是否参与网络同步。受 `bEnable` EditCondition 控制。Whether this host participates in network sync. Gated by the `bEnable` EditCondition.
`SpawnOrigin`	`EPlaySoundOrigin`	`PlaySound2D`	生成原点(`EPlaySoundOrigin` 全量枚举)。Spawn origin (`EPlaySoundOrigin` full enum).
`Delay`	`float`	`0`	延时生成(秒)。Spawn delay (seconds).
`Volume`	`float`	`1`	音量。Volume.
`LifeSpan`	`float`	`5`	生成后存活时长(秒),负值为无限长。Lifespan after spawn (seconds); negative = infinite.
`RadiusThreshold`	`float`	`10000.0f`	3D 音效:与监听者距离大于该值则不播放。For 3D sounds: not played when farther than this from the listener.
`BindToAnimIndex`	`int32`	`-1`	绑定到特定动画索引;-1 对所有动画生成。Bind to a specific animation index; -1 spawns for all animations.
`SpawnProbability`	`FVector4f`	`(0, 1, 10000, 1)`	生成概率参数(见 `FSoundConfig`)。Spawn probability params (see `FSoundConfig`).
`AgentBehaviorState`	`EAgentBehaviorState`	`None`	关联的 Agent 行为状态,用于概率计算。Associated agent behavior state, used for probability calculations.
`Concurrency`	`FSoundConcurrencyConfig`	—	模拟层并发控制。Simulation-layer concurrency control.
`ConcurrencyStartTime`	`float`	`0.0f`	播放开始时刻(SimulationTime)——`bSpawned` 置位时写入,`Reset` 时清。供 `MinPlayTime` 逐出保护。进快照注册表,不进 hash(时间戳惯例)。Playback start time (SimulationTime) — written when `bSpawned` is set, cleared on `Reset`. Feeds the MinPlayTime eviction guard. In the snapshot registry, NOT in hash (timestamp convention).
`RandomStream`	`FRandomStream`	—	确定性随机流(生成概率 / 随机延迟用)。Deterministic random stream (spawn probability / random delay).
`OwnerEntity`	`FEntityHandle`	—	生成者实体(并发按属主计数时使用)。Owner entity (used for per-owner concurrency counting).
`AttachToEntity`	`FEntityHandle`	—	附着到的实体。Entity to attach to.
`SpawnTransform`	`FTransform`	—	生成变换。Spawn transform.
`InitialRelativeTransform`	`FTransform3f`	—	初始相对变换。Initial relative transform.
`bInitialized`	`bool`	`false`	宿主已初始化。Host initialized.
`bSpawned`	`bool`	`false`	`UAudioComponent` 已生成。The `UAudioComponent` has been spawned.
`bIsPooled`	`bool`	`false`	宿主是否处于池中(`Reset` 时置 true)。Whether the host is pooled (set true by `Reset`).
`bShouldDestroy`	`bool`	`false`	置 true 时宿主实体将在下一帧被销毁。When set true, the host entity is destroyed on the next tick.
`PoolCountdown`	`float`	`15.0f`	池回收倒计时(秒)。Pool-recycle countdown (seconds).
`SpawnedSound`	`TObjectPtr<UAudioComponent>`	—	已生成的 `UAudioComponent`(非 UPROPERTY)。The spawned `UAudioComponent` (not a UPROPERTY).
`bNeedsSpawnRefresh`	`bool`	`false`	resync 后瞬态:恢复端置位,刷新段消费——只重发 UObject 音频生成 op,不重跑概率。不进任何注册表。Post-resync transient: set by restore, consumed by the refresh pass — re-issues the UObject audio spawn op WITHOUT re-running probability. Never enters any registry.

方法 Methods

FSoundConfig_Final(FSoundConfig) constructor

从通用 FSoundConfig 转换:逐字段拷贝(含 Concurrency / bLockstepNetworked),SpawnOrigin 保持默认 PlaySound2D(源无此字段)。

Converts from a generic FSoundConfig: copies every field (including Concurrency / bLockstepNetworked); SpawnOrigin stays at its default PlaySound2D (the source has no such field).

Input

参数 Param	类型 Type	说明 Description
`Config`	`const FSoundConfig&`	源通用配置。Source generic config.

Output

构造结果对象;无副作用。

Constructs the result object; no side effects.

FSoundConfig_Final(FSoundConfig_Attack) constructor

从攻击专用 FSoundConfig_Attack 转换:逐字段拷贝后按 switch 归一 SpawnOrigin——PlaySound2D → PlaySound2D;两种 3D 原点 → PlaySound3D。

Converts from an attack-specific FSoundConfig_Attack: copies every field, then normalizes SpawnOrigin via a switch — PlaySound2D → PlaySound2D; both 3D origins → PlaySound3D.

Input

参数 Param	类型 Type	说明 Description
`AttackConfig`	`const FSoundConfig_Attack&`	源攻击专用配置。Source attack-specific config.

Output

构造结果对象;无副作用。

Constructs the result object; no side effects.

Reset void (float InPoolIdleTTL = 15.0f)

宿主回到池状态的复位:bInitialized / bSpawned / bShouldDestroy / bNeedsSpawnRefresh 清 false,bIsPooled 置 true,PoolCountdown 置为 InPoolIdleTTL(统一池闲置倒计时,取 HostSubsystem 的 PoolIdleLifeSpan;默认值 15.0f 保证非回收调用点行为不变),ConcurrencyStartTime 复位,OwnerEntity / AttachToEntity 清空。故意不清 SpawnedSound:当 Reset() 紧跟延迟 Destroy op 排队之后被调用时(HostMonoProcessor sound 分支),AudioComponent 必须存活到 ProcessHostOpsQueues 执行 Destroy 分支(那里回收并置空 SpawnedSound);此处清空会跳过 RecycleAudioComponent 整条路径。

Resets the host to pool state: bInitialized / bSpawned / bShouldDestroy / bNeedsSpawnRefresh cleared, bIsPooled set true, PoolCountdown set to InPoolIdleTTL (the unified pool idle countdown, taken from the HostSubsystem's PoolIdleLifeSpan; the 15.0f default keeps non-recycle call sites unchanged), ConcurrencyStartTime reset, OwnerEntity / AttachToEntity cleared. Deliberately does NOT clear SpawnedSound: when Reset() runs right after queueing a deferred Destroy op (HostMonoProcessor sound branch), the AudioComponent must survive until ProcessHostOpsQueues runs the Destroy case (which recycles it to the pool and then nulls SpawnedSound itself); clearing here would skip RecycleAudioComponent entirely.

Input

参数 Param	类型 Type	说明 Description
`InPoolIdleTTL`	`float`	写入 `PoolCountdown` 的池闲置倒计时(秒),默认 `15.0f`。回收路径(`MassBattleHostMonoProcessor`)传入 `UMassBattleHostSubsystem::PoolIdleLifeSpan`。Pool idle countdown (seconds) written into `PoolCountdown`, default `15.0f`. The recycle path (`MassBattleHostMonoProcessor`) passes `UMassBattleHostSubsystem::PoolIdleLifeSpan`.

Output

无返回值。副作用:如上逐字段复位(保留 SpawnedSound)。

No return value. Side effects: per-field reset as described (keeping SpawnedSound).

FSoundOptCommand USTRUCT

命令缓冲条目:音效宿主的延迟操作(Spawn / Destroy 等,见 EUObjectOptType)。并行段收集,游戏线程串行排空,携带宿主实体与属主 UID。

Command-buffer entry: a deferred operation on a sound host (Spawn / Destroy etc., see EUObjectOptType). Gathered from parallel sections, drained serially on the game thread, carrying the host entity and owner UID.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`Entity`	`FMassEntityHandle`	—	目标宿主实体。Target host entity.
`OperationType`	`EUObjectOptType`	`Spawn`	操作类型。Operation type.
`OwnerUniqueID`	`int32`	`-1`	属主(生成者)UID,-1 = 无效。Owner (spawner) UID; -1 = invalid.

方法 Methods

FSoundOptCommand constructor ×2

默认构造与带参构造(实体 / 操作类型 / 可选属主 UID,默认 -1)。

Default constructor and parameterized constructor (entity / operation type / optional owner UID, default -1).

Input

参数 Param	类型 Type	说明 Description
`InEntity`	`FMassEntityHandle`	目标宿主实体。Target host entity.
`InOp`	`EUObjectOptType`	操作类型。Operation type.
`InOwnerUniqueID`	`int32`	属主 UID,默认 -1。Owner UID, default -1.

Output

构造结果对象;无副作用。

Constructs the result object; no side effects.

管线角色 Pipeline Role

FSoundConfig_Final 在 MassBattle 管线中的位置:宿主实体由 MassBattleHostMonoProcessor 管理(生成 / 推进 / 销毁 / 池回收,经 FSoundOptCommand 延迟操作与 ProcessHostOpsQueues 排空);bLockstepNetworked 为 true 时进快照注册表参与网络同步,false 时纯本地。ConcurrencyStartTime 进快照不进 hash(时间戳惯例)。

Position of FSoundConfig_Final in the MassBattle pipeline: host entities are managed by MassBattleHostMonoProcessor (spawn / advance / destroy / pool recycle, via FSoundOptCommand deferred ops drained by ProcessHostOpsQueues); when bLockstepNetworked is true they enter the snapshot registry for network sync, otherwise they are purely local. ConcurrencyStartTime is in the snapshot but not the hash (timestamp convention).