Animation.h

USTRUCT ×4

Source/MassBattle/Public/Fragments/Animation.h

概述 Overview

动画系统的 fragment 集合。包含:共享配置 FAnimShared(按值去重、跨 archetype 共享的动画参数与动画槽列表)、运行时状态 FAnimating(逐帧推进的动画状态机,含三级 LOD 独立混合状态)、数据载体 FAnimData(单个动画槽的 5 槽位数据)与 FAnimsData(8 类动画各自的槽列表)、每级 LOD 状态 FPerLevelAnimState,以及命名空间 AnimationHelpers 的转换/随机选取工具。

Animation fragment collection: shared config FAnimShared (value-deduplicated, archetype-shared animation parameters and slot lists), runtime state FAnimating (per-frame animation state machine with per-LOD blend state), data carriers FAnimData (5-slot animation data) and FAnimsData (per-category slot lists), per-level state FPerLevelAnimState, plus the AnimationHelpers namespace with conversion / random-pick utilities.

FPerLevelAnimState USTRUCT

特定 LOD 级别的隔离动画状态(非 fragment,非 UPROPERTY)。允许不同 LOD 独立模拟不同的混合逻辑。含 3 个动画槽的索引/播放速率/当前帧/起止帧/循环标志,2 个 Lerp 权重(0-255 表示 0.0-1.0),以及 Level 3 专用的「基础层是否蒙太奇」标志。

Isolated animation state for a specific LOD level (not a fragment, no UPROPERTYs). Allows independent simulation of different blend logics per LOD. Holds per-slot index / playrate / current frame / start-end frames / loop flag for 3 animation slots, 2 Lerp weights (0-255 maps to 0.0-1.0), and a Level-3-only "base layer is montage" flag.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`Index0` / `Index1` / `Index2`	`uint8`	`255` (INVALID_ANIM_INDEX)	三个动画槽的索引。Animation index per slot.
`PlayRate0` / `PlayRate1` / `PlayRate2`	`float`	`1.0f`	各槽播放速率。Play rate per slot.
`CurrentFrame0` / `CurrentFrame1` / `CurrentFrame2`	`float`	`0.0f`	各槽当前帧(浮点,可插值)。Current frame per slot (float, interpolatable).
`StartFrame0` / `StartFrame1` / `StartFrame2`	`uint16`	`0`	各槽起始帧。Start frame per slot.
`EndFrame0` / `EndFrame1` / `EndFrame2`	`uint16`	`0`	各槽结束帧。End frame per slot.
`bLoop0` / `bLoop1` / `bLoop2`	`bool`	`false`	各槽是否循环。Loop flag per slot.
`Lerp0` / `Lerp1`	`uint8`	`0`	混合权重,0-255 表示 0.0-1.0。Blend weight; 0-255 represents 0.0-1.0.
`bBaseLayerIsMontage`	`bool`	`false`	Level 3 专用:基础层是否处于蒙太奇追踪。Level-3-only: whether the base layer is montage-tracked.

FAnimData USTRUCT

单个动画类别的 5 槽位数据。每个槽为 FVector4f:(AnimIndex, PlayLength, StartFrame, EndFrame);X 为 -1 表示该槽未使用。提供 operator== 按槽逐项比较。

5-slot data for a single animation category. Each slot is an FVector4f: (AnimIndex, PlayLength, StartFrame, EndFrame); X = -1 marks the slot unused. Provides operator== comparing per-slot.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`Anim0` … `Anim4`	`FVector4f`	`(-1, 0, 0, 0)`	五个动画槽,格式 (AnimIndex, PlayLength, StartFrame, EndFrame);X=-1 表示未使用。Five animation slots as (AnimIndex, PlayLength, StartFrame, EndFrame); X=-1 means unused.

方法 Methods

operator== FORCEINLINE bool

按槽逐项比较两个 FAnimData,全部相等才为真。供 FAnimShared 去重判断使用。

Per-slot comparison of two FAnimData; true only when all slots match. Used for FAnimShared deduplication.

Input

参数 Param	类型 Type	说明 Description
`Other`	`const FAnimData&`	待比较对象。The object to compare against.

Output

返回是否全部槽位相等。无副作用。

Returns whether all slots are equal. No side effects.

FAnimsData USTRUCT

8 类动画(Idle/Move/Fall/Appear/Attack/Hit/Death/Other)各自的槽列表。出生或播放时自动随机选择有效索引(见 AnimationHelpers::PickRandomIndex)。

Slot lists for 8 animation categories (Idle/Move/Fall/Appear/Attack/Hit/Death/Other). A valid index is auto-picked randomly at spawn or at montage start (see AnimationHelpers::PickRandomIndex).

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`IdleAnimData`	`FAnimData`	—	待机动画槽列表,出生时随机选择。Idle animation slots; randomly picked at spawn.
`MoveAnimData`	`FAnimData`	—	移动动画槽列表,出生时随机选择。Move animation slots; randomly picked at spawn.
`FallAnimData`	`FAnimData`	—	坠落动画槽列表,播放时随机选择。Fall animation slots; randomly picked at play.
`AppearAnimData`	`FAnimData`	—	出现动画槽列表,播放时随机选择。Appear animation slots; randomly picked at play.
`AttackAnimData`	`FAnimData`	—	攻击动画槽列表,播放时随机选择。Attack animation slots; randomly picked at play.
`HitAnimData`	`FAnimData`	—	受击动画槽列表,播放时随机选择。Hit animation slots; randomly picked at play.
`DeathAnimData`	`FAnimData`	—	死亡动画槽列表,播放时随机选择。Death animation slots; randomly picked at play.
`OtherAnimData`	`FAnimData`	—	其它动画槽列表,播放时随机选择。Other animation slots; randomly picked at play.

方法 Methods

operator== FORCEINLINE bool

逐类别比较 8 组 FAnimData。

Compares all 8 FAnimData groups.

Input

参数 Param	类型 Type	说明 Description
`Other`	`const FAnimsData&`	待比较对象。The object to compare against.

Output

返回是否全部类别相等。无副作用。

Returns whether all categories are equal. No side effects.

FAnimShared USTRUCT

动画共享配置 fragment(FA_MassBattleBaseSharedFragment 派生,可变共享)。持有仍生效的配置(不再含旧的单索引/播放速率/软指针字段);相同值元组只保留一份实例,跨所有内容匹配的 archetype 的每个 Agent 共享。由 Reaction / Behavior / Render 处理器经 Context.GetSharedFragment<FAnimShared>() 读取;在 DataAsset 上通过 AnimShared 属性设置,旧版 FAnimation 数据在 PostLoad 自动迁移。

Animation shared config fragment (derived from FA_MassBattleBaseSharedFragment, mutable). Holds only the still-active configuration (no deprecated single-index / play-rate / soft-pointer fields); one instance per distinct value tuple, shared across every agent of every archetype with matching content. Read by Reaction / Behavior / Render processors via Context.GetSharedFragment<FAnimShared>(); set on the DataAsset via the AnimShared property, old authored FAnimation data is auto-migrated at PostLoad.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`AnimBlendSpeed`	`float`	`6`	动画过渡速度(如 Idle 与 Move 之间)。Animation blend speed (e.g. between Idle and Move).
`AngularSpeedBlendMultiplier`	`float`	`0.f`	角速度对运动混合的贡献权重(ClampMin=0)。Contribution of angular speed to locomotion blending (ClampMin=0).
`IdleRandomTimeOffset`	`FVector2f`	`(0, 0)`	待机动画起始时间随机偏移范围(Min, Max)。Random time offset range for the Idle animation start time (Min, Max).
`MoveRandomTimeOffset`	`FVector2f`	`(0, 0)`	移动动画起始时间随机偏移范围(Min, Max)。Random time offset range for the Move animation start time (Min, Max).
`BS_IdleMove`	`FVector2f`	`(0, 150)`	Idle-Move 混合空间起止点的移动速度值(待机速度, 移动速度)。Movement speeds at the start/end of the Idle-Move blend space (IdleSpeed, MoveSpeed).
`bMoveCanReverse`	`bool`	`true`	Agent 倒退移动时移动动画能否倒放。Whether the move animation can reverse when the agent moves backwards.
`FallingAnimDelay`	`float`	`0.1f`	进入坠落动画前必须在空中持续的秒数。与物理 Falling 状态解耦——物理在离地瞬间进入 Falling,本项仅控制动画切换迟滞,避免小台阶/斜坡上的动画抖动。Seconds the agent must remain airborne before the Falling animation kicks in. Decoupled from the physics Falling state — physics enters Falling instantly on takeoff; this is pure animation hysteresis against flicker on small bumps/slopes.
`AnimData`	`FAnimsData`	—	8 类动画的槽数据列表。Slot data lists for the 8 animation categories.
`DeterministicHash`	`int32`	`0`	确定性 CRC32 种子。模板构建时从 asset path(`GetPathName`)赋值。Deterministic CRC32 seed. Set from the asset path (`GetPathName`) at template-build.

方法 Methods

operator== FORCEINLINE bool

逐字段比较(含 AnimData 嵌套比较),供共享 fragment 去重判断使用。注意 DeterministicHash 不参与比较。

Field-by-field comparison (including nested AnimData); used for shared-fragment deduplication. Note DeterministicHash is excluded.

Input

参数 Param	类型 Type	说明 Description
`Other`	`const FAnimShared&`	待比较对象。The object to compare against.

Output

返回是否全部字段相等。无副作用。

Returns whether all fields are equal. No side effects.

FAnimating USTRUCT

动画运行时状态 fragment(FA_MassBattleBaseFragment 派生)。持有三级 LOD 的独立状态(Level1State/Level2State/Level3State)与最终混合结果 AnimBlendResult、动画状态机(AnimState/PreviousAnimState)、选中的动画槽索引、蒙太奇播放速率,以及 Team / 受击发光 / 消融 / 元素特效强度等渲染输入。内置自旋锁 Lock/Unlock(并行段修改时使用),并提供完整的拷贝构造/赋值。经 MASS_FRAGMENT_ACCEPT_NOT_TRIVIALLY_COPYABLE 声明为不可平凡拷贝(含 std::atomic 成员)。

Animation runtime state fragment (derived from FA_MassBattleBaseFragment). Holds per-LOD state (Level1State/Level2State/Level3State) and the final blend result AnimBlendResult, the animation state machine (AnimState/PreviousAnimState), selected anim slot indices, montage play rate, plus render inputs (Team / hit glow / dissolve / elemental FX intensities). Ships a spin-lock (Lock/Unlock) for parallel-section mutation, plus full copy construction/assignment. Declared via MASS_FRAGMENT_ACCEPT_NOT_TRIVIALLY_COPYABLE as not-trivially-copyable (contains std::atomic).

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`Level1State` / `Level2State` / `Level3State` / `AnimBlendResult`	`FPerLevelAnimState`	—	三级 LOD 独立状态与最终混合结果。Per-LOD states and the final blend result.
`AnimState`	`EAnimState`	`Dirty`	当前动画状态。Current animation state.
`PreviousAnimState`	`EAnimState`	`Dirty`	上一帧动画状态。Previous frame's animation state.
`CurrentAnimBlendLevel`	`uint8`	`1`	当前最高混合层级(0=Base, 1=Layer1, 2=Montage)。Current highest blend level active (0=Base, 1=Layer1, 2=Montage).
`SampleRate`	`int32`	`30`	动画数据的帧采样率(每秒帧数)。Frame sample rate (fps) of the animation data.
`IdleRandomStartFrame`	`float`	`0.0f`	随机计算的待机动画起始帧。Randomly calculated start frame for the Idle animation.
`MoveRandomStartFrame`	`float`	`0.0f`	随机计算的移动动画起始帧。Randomly calculated start frame for the Move animation.
`SelectedIdleAnimIndex` … `SelectedMontageAnimIndex`	`uint8`	`255` (INVALID)	8 个已选动画槽索引(0-4,指向对应 `FAnimData`;255 = 无效):Idle/Move/Fall/Appear/Attack/Hit/Death/Montage。8 selected anim slot indices (0-4, pointing into the matching `FAnimData`; 255 = invalid): Idle/Move/Fall/Appear/Attack/Hit/Death/Montage.
`MontagePlayRate`	`float`	`1.f`	蒙太奇播放速率乘数。Montage play rate multiplier.
`bMontageLooping`	`uint8 : 1`	`0` (显式 `= 0`)	蒙太奇动画是否循环(位域,与 `bUpdateAnimState` 打包)。Whether the montage animation loops (bitfield, packed with `bUpdateAnimState`).
`bUpdateAnimState`	`uint8 : 1`	`true` (构造器置位)	同帧触发标志:是否更新动画状态。Same-frame trigger: whether to update the animation state.
`Team`	`uint8`	`0`	队伍 ID,通常用于材质着色。Team identifier, often used for material coloring.
`HitGlow`	`uint8`	`0`	受击时触发的发光强度(0-255)。Glow intensity triggered on hit (0-255).
`Dissolve`	`uint8`	`0`	消融效果进度(0=实体,255=完全消融)。Dissolve effect progress (0=solid, 255=fully dissolved).
`IceFx` / `FireFx` / `PoisonFx`	`uint8`	`0`	冰冻/火焰/中毒效果强度(0-255)。Ice / fire / poison effect intensity (0-255).
`IceFxInterped` / `FireFxInterped` / `PoisonFxInterped`	`uint8`	`0`	插值后的对应效果强度(0-255)。Interpolated effect intensity (0-255).

方法 Methods

Lock void (const)

自旋锁加锁:对 LockFlag 做 exchange(acquire 语义)忙等,直至拿到锁。并行段中修改本 fragment 前调用。

Spin-lock acquire: busy-waits on LockFlag with an acquire-semantics exchange until the lock is held. Called before mutating this fragment from parallel sections.

Input

无参数。

No parameters.

Output

无返回值。副作用:置位 LockFlag。

No return value. Side effect: sets LockFlag.

Unlock void (const)

自旋锁释放:以 release 语义将 LockFlag 清零。

Spin-lock release: clears LockFlag with release semantics.

Input

无参数。

No parameters.

Output

无返回值。副作用:清零 LockFlag。

No return value. Side effect: clears LockFlag.

FAnimating (constructor) / operator= FAnimating(const FAnimating&) / FAnimating& operator=(const FAnimating&)

完整拷贝构造/赋值,逐一拷贝全部状态字段(LockFlag 不拷贝)。默认构造器将 bUpdateAnimState 置 true。

Full copy construction/assignment copying every state field (LockFlag is not copied). The default constructor sets bUpdateAnimState to true.

Input

参数 Param	类型 Type	说明 Description
`Anim`	`const FAnimating&`	源对象。Source object.

Output

拷贝构造无返回值;赋值返回 *this。副作用:目标对象全部字段被覆盖。

The constructor returns nothing; assignment returns *this. Side effect: all target fields overwritten.

AnimationHelpers Helpers

动画数据转换辅助命名空间:归一化值与 uint8 互转、无效索引常量 INVALID_ANIM_INDEX = 255、随机槽选取与按索引取槽数据。

Helper namespace for animation data conversions: normalized-value <-> uint8 conversion, the invalid-index constant INVALID_ANIM_INDEX = 255, random slot picking and per-index slot lookup.

FloatToNormalizedUint8 FORCEINLINE uint8 (static)

将 [0,1] 浮点值钳制后映射到 0-255 整数(乘 255)。

Clamps a [0,1] float and maps it to a 0-255 integer (multiplies by 255).

Input

参数 Param	类型 Type	说明 Description
`Value`	`float`	归一化值(越界自动钳制到 [0,1])。Normalized value (clamped to [0,1] automatically).

Output

返回 0-255 的 uint8。无副作用。

Returns a uint8 in 0-255. No side effects.

NormalizedUint8ToFloat FORCEINLINE float (static)

将 0-255 整数映射回 [0,1] 浮点(除以 255)。

Maps a 0-255 integer back to a [0,1] float (divides by 255).

Input

参数 Param	类型 Type	说明 Description
`Value`	`uint8`	0-255 的整数。Integer in 0-255.

Output

返回 [0,1] 浮点。无副作用。

Returns a [0,1] float. No side effects.

PickRandomIndex FORCEINLINE int32 (static)

从 FAnimData 的有效槽(X != -1)中经 FRandomStream 均匀随机选一个索引;无有效槽返回 -1。随机流初始种子为 0 时自动 Initialize(0x5EEDBEEF) 作安全网(实体漏了 SeedAtSpawn)。

Uniformly picks a slot index among the valid slots (X != -1) of an FAnimData via FRandomStream; returns -1 when none are valid. If the stream's initial seed is 0, auto-initializes with 0x5EEDBEEF as a safety net (entity skipped SeedAtSpawn).

Input

参数 Param	类型 Type	说明 Description
`Data`	`const FAnimData&`	待选取的动画槽数据。Animation slot data to pick from.
`Stream`	`FRandomStream&`	确定性随机流(消费其 `RandRange`,推进状态)。Deterministic random stream (its `RandRange` is consumed, advancing state).

Output

返回选中的槽索引(0-4);无有效槽返回 -1。副作用:可能初始化随机流;消费一次随机数。

Returns the picked slot index (0-4); -1 when no valid slot exists. Side effects: may initialize the stream; consumes one random draw.

GetDataFromIndex FORCEINLINE FVector4f (static)

按槽索引(0-4)取回 FAnimData 对应槽数据;越界返回 (-1, 0, 0, 0)。switch 直查。

Fetches the slot data of an FAnimData by index (0-4); returns (-1, 0, 0, 0) out of range. Direct switch lookup.

Input

参数 Param	类型 Type	说明 Description
`Data`	`const FAnimData&`	动画槽数据源。Animation slot data source.
`SlotIndex`	`int32`	槽索引(0-4)。Slot index (0-4).

Output

返回对应槽的 FVector4f;越界返回 (-1, 0, 0, 0)。

Returns the slot's FVector4f; (-1, 0, 0, 0) out of range.

管线角色 Pipeline Role

FAnimShared 由 Reaction / Behavior / Render 处理器经 Context.GetSharedFragment 读取(头注释声明);FAnimating 的 Lock/Unlock 由 MassBattleDebuffMonoProcessor 在修改目标实体动画状态前加锁(grep 验证)。PickRandomIndex 在出生/蒙太奇启动时选取动画槽(消费确定性随机流,推进 FDeterminism::RandomStream)。

FAnimShared is read by Reaction / Behavior / Render processors via Context.GetSharedFragment (per the header comment); FAnimating's Lock/Unlock is used by MassBattleDebuffMonoProcessor before mutating a target entity's animation state (verified by grep). PickRandomIndex picks the animation slot at spawn / montage start (consuming the deterministic random stream of FDeterminism::RandomStream).

补充说明 Notes

FAnimating 的默认构造器(FAnimating())仅设置 bUpdateAnimState = true;位域成员均带显式 = 0 默认成员初始化器(保证零初始化)。拷贝构造/赋值不拷贝 LockFlag(锁状态不可复制)。

The default FAnimating() constructor only sets bUpdateAnimState = true; every bitfield member carries an explicit = 0 default member initializer (guaranteeing zero-initialization). Copy construction/assignment does not copy LockFlag (lock state is not copyable).