UMassEntityFlagsTrait
Source/MassAPI/Public/MassEntityFlagsTrait.h
概述 Overview
FEntityFlagFragment 的官方工作流封装 trait。引擎的官方配置资产 UMassEntityConfigAsset 只能挂 trait、不能挂裸 fragment——本 trait 在模板构建时向实体追加 FEntityFlagFragment 并写入所选初始旗标,使配置驱动的生成(MassSpawner / MassEntityConfigAsset)获得与 FEntityTemplate.Flags 完全一致的初始旗标语义。旗标位本身无内建语义——语义由消费方定义(MassBattle 的 EBattleFlags 是完整的命名覆层范例)。运行时读走 UMassAPISubsystem::GetEntityFlags,写走 SetEntityFlag 等——原位翻位,零原型(archetype)迁移。
The official-workflow wrapper trait for FEntityFlagFragment. The engine's official config asset UMassEntityConfigAsset lists TRAITS only — raw fragments cannot be attached there. This trait appends FEntityFlagFragment to the template with the selected initial flags, so config-driven spawns (MassSpawner / MassEntityConfigAsset) get the same initial-flags semantics as FEntityTemplate.Flags. Flag bits carry NO built-in meaning — the consumer defines semantics (MassBattle's EBattleFlags is a full named-overlay example). Runtime reads go through UMassAPISubsystem::GetEntityFlags, writes through SetEntityFlag etc. — in-place bit flips, zero archetype migration.
继承 Inheritance
方法 Methods
trait 的核心覆写(实现内联于头文件):先经 BuildContext.AddFragment_GetRef<FEntityFlagFragment>() 取得(或复用已存在的)旗标 fragment,再把 InitialFlags 列表逐一经 FEntityFlagFragment::SetFlag 折进两个 int64 半区——索引语义:0-63 → Flags,64-127 → FlagsHigh(映射由 SetFlag 完成)。与其余旗标写入方幂等:AddFragment_GetRef 不会重复添加同型 fragment。
The trait's core override (implemented inline in the header): first obtains the flag fragment via BuildContext.AddFragment_GetRef<FEntityFlagFragment>() (reusing one if already present), then folds each entry of InitialFlags into the two int64 halves via FEntityFlagFragment::SetFlag — index semantics: 0-63 → Flags, 64-127 → FlagsHigh (the mapping is done by SetFlag). Idempotent with other flag writers: AddFragment_GetRef never duplicates a fragment type.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
BuildContext | FMassEntityTemplateBuildContext& | 模板构建上下文,提供 AddFragment_GetRef(类型定义自 MassEntityTemplateRegistry.h,基类仅前向声明)。Template build context providing AddFragment_GetRef (its type is defined in MassEntityTemplateRegistry.h; the trait base only forward-declares it). |
World | const UWorld& | 当前世界,基类签名的一部分;本实现未使用。Current world, part of the base-class signature; unused by this implementation. |
Output
无返回值。副作用:实体模板获得 FEntityFlagFragment,其 Flags/FlagsHigh 按 InitialFlags 置位。
No return value. Side effects: the entity template gains FEntityFlagFragment with Flags/FlagsHigh bits set per InitialFlags.
成员变量 Members
| 名称 Name | 类型 Type | 默认值 | 说明 Description |
|---|---|---|---|
InitialFlags | TArray<EEntityFlags> | 空 | 生成时置位的初始旗标(protected + EditAnywhere,Category="Mass")。EEntityFlags 是泛型位名(定义于 MassAPIEnums.h),语义由消费方定义。Initial flags set at build time (protected + EditAnywhere, Category="Mass"). EEntityFlags provides generic bit names (defined in MassAPIEnums.h); meaning is defined by the consumer. |
管线角色 Pipeline Role
位置:实体模板编译期。挂载本 trait 的 UMassEntityConfigAsset 被官方生成链(MassSpawner 等)编译成实体模板时,引擎回调 UMassEntityTraitBase::BuildTemplate 虚函数,本类覆写即在其中注入 FEntityFlagFragment(fragment 本体与 FEntityTemplate 定义于 MassAPIStructs.h)。生成之后的运行期读写全部走 UMassAPISubsystem(MassAPISubsystem.h):GetEntityFlags / GetEntityFlagsHigh 读,SetEntityFlag / SetEntityFlagDefer(命令缓冲 / 执行上下文两个重载)延迟写。命名覆层范例:EBattleFlags(MassBattleStructs.h)把泛型位映射为战斗语义名。发布树中无其它 C++ 代码直接引用 UMassEntityFlagsTrait(已 grep 验证)——它是面向配置资产创作的类型。
Position: entity-template compile time. When an UMassEntityConfigAsset carrying this trait is compiled into an entity template by the official spawn chain (MassSpawner etc.), the engine calls back the UMassEntityTraitBase::BuildTemplate virtual; this class's override injects FEntityFlagFragment there (the fragment itself and FEntityTemplate are defined in MassAPIStructs.h). All post-spawn runtime access goes through UMassAPISubsystem (MassAPISubsystem.h): reads via GetEntityFlags / GetEntityFlagsHigh, deferred writes via SetEntityFlag / SetEntityFlagDefer (two overloads: command buffer / execution context). Named-overlay example: EBattleFlags (MassBattleStructs.h) maps the generic bits to battle-semantic names. No other C++ code in the release tree references UMassEntityFlagsTrait directly (grep-verified) — it is a type authored through config assets.
补充说明 Notes
编辑器显示名(DisplayName)为 "Entity Flags"。BuildTemplate 与 InitialFlags 均为 protected——trait 由模板构建系统驱动,不供游戏代码直接调用。头文件依赖的 MassEntityTemplateRegistry.h 仅为取得 FMassEntityTemplateBuildContext 完整定义(基类只做前向声明)。
Editor display name (DisplayName) is "Entity Flags". Both BuildTemplate and InitialFlags are protected — the trait is driven by the template build system, not called directly by game code. The header's dependency on MassEntityTemplateRegistry.h exists only to get the full definition of FMassEntityTemplateBuildContext (the base class merely forward-declares it).