UMassAPISubsystem

子系统生命周期入口。实现(MassAPISubsystem.cpp):调用父类、声明 UMassEntitySubsystem 依赖(InitializeDependency)、触发 GetEntityManager() 惰性缓存、创建 SharedCommandBuffer,并输出初始化日志。

Subsystem lifecycle entry. Implementation (MassAPISubsystem.cpp): calls the parent, declares the UMassEntitySubsystem dependency (InitializeDependency), triggers the GetEntityManager() lazy cache, creates SharedCommandBuffer, and logs initialization.

子系统生命周期出口。释放缓冲区前先向 EntityManager FlushCommands 剩余命令,然后重置全部缓存指针并调用父类,输出日志。

Subsystem lifecycle exit. Flushes remaining commands to the EntityManager before releasing the buffer, then resets all cached pointers, calls the parent, and logs.

每帧 tick 入口。实现:TRACE_CPUPROFILER_EVENT_SCOPE_STR("MassAPISubsystemTick");若 EntityManager 可用则调用 FlushCommandBuffer() 刷新共享命令缓冲。

Per-frame tick entry. Implementation: TRACE_CPUPROFILER_EVENT_SCOPE_STR("MassAPISubsystemTick"); flushes the shared command buffer via FlushCommandBuffer() when the EntityManager is available.

UTickableWorldSubsystem 要求的 profiling 统计 ID,RETURN_QUICK_DECLARE_CYCLE_STAT 生成。

The profiling stat ID required by UTickableWorldSubsystem, produced by RETURN_QUICK_DECLARE_CYCLE_STAT.

静态访问器。无参版本取 GWorld 的子系统;WorldContext 版本经 GEngine->GetWorldFromContextObject 解析世界。世界无效时返回 nullptr(不崩溃)。

Static accessor. The no-arg version fetches the subsystem from GWorld; the WorldContext version resolves the world via GEngine->GetWorldFromContextObject. Returns nullptr when the world is invalid (does not crash).

静态访问器的引用版本:失败即 checkf 断言崩溃——用于「子系统必须存在」的不变式场景。

Reference version of the static accessor: fails via checkf assertion — for invariant paths where the subsystem must exist.

惰性获取实体管理器,任何函数(含 const)都可安全调用。缓存命中直接返回;否则依次解析 CurrentWorld(GetWorld())→ UMassEntitySubsystem → GetMutableEntityManager(),全部写入 mutable 缓存成员。取不到时返回 nullptr。

Lazily gets the entity manager; safe to call from any function, including const ones. Fast path returns the cache; otherwise resolves CurrentWorld (GetWorld()) → UMassEntitySubsystem → GetMutableEntityManager(), writing all into mutable cache members. Returns nullptr when unavailable.

取子系统自有的延迟命令缓冲 SharedCommandBuffer。警告(源码注释):仅限 processor 上下文之外使用;processor 内请用 Context.Defer()。未初始化时 checkf 断言。

Returns the subsystem-owned deferred command buffer SharedCommandBuffer. WARNING (source comment): use outside processor contexts only; inside processors use Context.Defer(). Asserts via checkf when not initialized.

取 API 拥有的持久命令缓冲的共享指针。

Returns the shared pointer to the API-owned persistent command buffer.

把 API 拥有的命令缓冲刷新到实体管理器。实现:EntityManager 与 SharedCommandBuffer 均可用时调用 EM->FlushCommands(SharedCommandBuffer)。所有 Defer() 操作后应调用它。

Flushes the API-owned command buffer to the entity manager. Implementation: calls EM->FlushCommands(SharedCommandBuffer) when both the EntityManager and SharedCommandBuffer are available. Call it after all Defer() ops for the current phase.

FlushCommandBuffer 的废弃别名(源码注释标注),直接委托。

Deprecated alias for FlushCommandBuffer (per source comment); delegates directly.

composition 过滤:HasAll = A 包含 B 的全部;HasAny = A 包含 B 的任一。经 HAS_ALL/ANY_COMPOSITION 版本宏实现。

Composition filters: HasAll = A contains all of B; HasAny = A contains any of B. Implemented via the HAS_ALL/ANY_COMPOSITION version macros.

按 FEntityQuery 的单个条件匹配 composition:MatchQueryAll 仅 All 条件(列表为空自动通过);MatchQueryAny 仅 Any; MatchQueryNone 仅 None;四参 MatchQuery 为三者 AND 组合。

Matches a composition against a single condition of an FEntityQuery: MatchQueryAll checks All only (empty list auto-passes); MatchQueryAny Any only; MatchQueryNone None only; the four-arg MatchQuery ANDs all three.

按实体的 archetype 句柄取 composition,再执行 All/Any/None 三条件 AND 匹配。EntityManager 不可用时 checkf 断言。

Fetches the composition from the entity's archetype handle, then ANDs the All/Any/None conditions. Asserts via checkf when the EntityManager is unavailable.

按实体的 FEntityFlagFragment 匹配查询的旗标条件:六个位掩码缓存全零时直接通过;否则读取实体的低位/高位旗标,All 要求低位与高位都全覆盖、Any 要求任一端命中、None 要求两端全无。实体无旗标 fragment 时按 0 处理。

Matches an entity's flag conditions against its FEntityFlagFragment: passes immediately when all six cached bitmasks are zero; otherwise reads the entity's low/high flags — All requires full coverage on both ends, Any requires a hit on either end, None requires none on either. Entities without the flag fragment are treated as 0.

完整逐实体匹配(composition + 旗标):先查实体活跃与 archetype 有效,再依次 MatchQueryComposition 与 MatchQueryFlag。

Full per-entity match (composition + flags): first checks the entity is active and its archetype valid, then runs MatchQueryComposition and MatchQueryFlag in order.

逐实体完整 composition + 旗标匹配(All/Any/None)。源码注释说明:聚合级(block/cell)composition 是并集,只能剪掉「必不可能」的单元,永远不能确认实体匹配 All 或按 None 排除,因此必须保留此完整逐实体检查。该版本供 trace 收集热循环使用,有意省略 IsValid(grid 每帧从活实体重建,消费方会重新校验)。

Per-entity FULL composition + flags match (All/Any/None). Source comments explain that aggregation-level (block/cell) composition is a UNION that can only prune "impossible" cells — it can never confirm an entity matches All nor exclude by None, so this full per-entity check is required for correctness. This version is for the trace gather hot loop and intentionally skips IsValid (the grid is rebuilt from live entities every frame; consumers re-validate).

运行时实体句柄检查:EntityManager 的 IsEntityValid 且 IsEntityBuilt 同时为真。EntityManager 不可用时 checkf 断言。

Runtime entity handle check: true when the EntityManager reports both IsEntityValid and IsEntityBuilt. Asserts via checkf when the EntityManager is unavailable.

立即预留实体句柄但不创建数据——在实体完全构建前需要一个可引用的句柄时使用。预留实体保持非活跃,直到调用 BuildEntity。EntityManager 不可用时 checkf 断言。

Reserves an entity handle without creating its data immediately — useful when you need a referenceable handle before the entity is fully constructed. The reserved entity stays inactive until BuildEntity is called. Asserts via checkf when the EntityManager is unavailable.

用模板立即构建实体。实现(MassAPISubsystem.cpp):Quantity <= 0 直接返回空;对模板 Sort() 后 CreateArchetype(失败返回空)、BatchCreateEntities、再批量写入初值——5.6+ 经 BatchSetEntityFragmentValues,≤5.5 经 MassAPIImpl::ApplyInitialFragmentValuesBatch 逐实体结构体拷贝。BuildEntity 委托 BuildEntities(1, …) 取首元素,失败返回默认(空)句柄。

Immediately builds entities from a template. Implementation (MassAPISubsystem.cpp): returns empty for Quantity <= 0; Sort()s the template, CreateArchetypes (empty on failure), BatchCreateEntities, then batched initial-value writes — via BatchSetEntityFragmentValues on 5.6+, or per-entity struct copies through MassAPIImpl::ApplyInitialFragmentValuesBatch on ≤5.5. BuildEntity delegates to BuildEntities(1, …) and takes the first element, returning a default (empty) handle on failure.

变参立即构建:参数按类型自动分派——Tag 进标签位集;Fragment 进位集并收集初值;SharedFragment / ConstSharedFragment 经 GetOrCreateSharedFragment(值) 去重后进入共享值。随后 CreateArchetype(失败记警告日志并返回空)、BatchCreateEntities、批量写初值。用法:BuildEntities(10, FEnemyTag{}, FHealthFragment{100.0f}, FTeamSharedFragment{1})。不支持的类型触发编译期 static_assert。单实体版本取数组首元素。

Variadic immediate build: arguments auto-dispatch by type — Tags into the tag bit set; Fragments into the bit set with collected initial values; SharedFragment / ConstSharedFragment deduped via GetOrCreateSharedFragment(value) into shared values. Then CreateArchetype (warning log + empty on failure), BatchCreateEntities, and batched initial-value writes. Usage: BuildEntities(10, FEnemyTag{}, FHealthFragment{100.0f}, FTeamSharedFragment{1}). Unsupported types fail a compile-time static_assert. The single-entity version takes the array's first element.

延迟批量构建(Context 与 CommandBuffer 两个重载):立即 BatchReserveEntities 并把预留句柄追加进 OutEntities,随后向命令缓冲压入一条 FMassDeferredCreateCommand,刷新时创建 archetype(失败释放全部预留)、BatchCreateReservedEntities 构建、批量写初值。

Deferred batch build (Context and CommandBuffer overloads): immediately BatchReserveEntities and append the reserved handles to OutEntities, then push one FMassDeferredCreateCommand; on flush it creates the archetype (releasing all reservations on failure), BatchCreateReservedEntities, and batched initial-value writes.

延迟构建单实体。模板版本:立即 ReserveEntity,快照 composition/初值后压入 FMassDeferredCreateCommand(刷新时创建 archetype、失败 ReleaseReservedEntity、BuildEntity、写初值),返回预留句柄。变参版本:先构建临时 FMassEntityTemplateData(Tag 用 AddTag,Fragment 用 AddFragment 值),再委托模板版本——使全部 fragment+tag 合并为一条原子创建命令。Context 版本委托 Context.Defer()。

Deferred single-entity build. Template versions: immediately ReserveEntity, snapshot composition/initial values, push a FMassDeferredCreateCommand (on flush: create archetype, ReleaseReservedEntity on failure, BuildEntity, write initial values), return the reserved handle. The variadic version builds a temporary FMassEntityTemplateData first (Tags via AddTag, Fragments via AddFragment value), then delegates to the template version — so ALL fragments+tags land in ONE atomic create command. The Context version delegates via Context.Defer().

立即销毁(DestroyEntity):实体不活跃则直接返回,否则 Manager->DestroyEntity。延迟版本把 DestroyEntity 命令压入 Context/CommandBuffer,刷新时执行。

Immediate destroy (DestroyEntity): returns when the entity is inactive, otherwise Manager->DestroyEntity. The deferred versions push a DestroyEntity command into the Context/CommandBuffer, executed on flush.

从 FMassEntityTemplateData 的共享值中按类型取回常量共享 / 可变共享 fragment 指针。用于 spawn 时缓存模板中的值,而不经过逐实体 fragment 槽(如注册为 const-shared 且故意无逐实体对应物的 fragment)。未找到返回 nullptr。

Pulls a const-shared / mutable shared fragment pointer of type T back out of a FMassEntityTemplateData's shared values. Useful when caching values from a template at spawn-time without going through the per-agent fragment slot (e.g. fragments registered as const-shared with no per-agent counterpart). Returns nullptr when absent.

在 FMassEntityTemplateData 内替换(或新增)类型 T 的 const-shared fragment:从零重建模板,复制全部 tag/fragment/共享值(跳过既有 T),再经 EntityManager 的 const-shared 去重存储加入新值。用于每次 spawn 需要微调(如把 ScaleMult 烘焙进 RenderShared.Transform)且后续 spawn 管线仍从该 SharedTemplate 副本读取的场景。保留模板名以维持调试一致性。

Replaces (or adds) a const-shared fragment of type T inside a FMassEntityTemplateData: rebuilds the template from scratch, copying every tag/fragment/shared value except any pre-existing T, then dedupes the new value through the entity manager's const-shared store. For per-spawn tweaks (e.g. ScaleMult baked into RenderShared.Transform) that must land on a SharedTemplate copy the rest of the spawn pipeline still reads from. Carries over the template name for debug parity.

存在性检查家族:模板版本要求 static_assert 类型正确(CTag/CFragment/CChunkFragment/CSharedFragment/CConstSharedFragment);非模板版本接受 const UScriptStruct*(可为 null,蓝图中类型为变量时使用)。实现均取实体 archetype 的 composition,经 CONTAINS_* 版本宏检查对应位集;archetype 无效返回 false。所有版本在 EntityManager 不可用时 checkf 断言。

Presence-check family: template versions static_assert the type (CTag/CFragment/CChunkFragment/CSharedFragment/CConstSharedFragment); non-template versions take a const UScriptStruct* (nullable; for when the type is a variable, e.g. from Blueprints). Implementations fetch the entity's archetype composition and check the matching bit set via the CONTAINS_* version macros; invalid archetypes return false. All versions checkf-assert when the EntityManager is unavailable.

按值拷贝 / 指针 / 引用三种取 fragment 的方式。值与引用版本在实体缺该 fragment 时 checkf 断言;指针版本未找到返回 nullptr。全部经 Manager->GetFragmentDataPtr<T>。

Three ways to fetch a fragment: by value, by pointer, by reference. The value and reference versions checkf-assert when the entity lacks the fragment; the pointer version returns nullptr. All go through Manager->GetFragmentDataPtr<T>.

可变共享 fragment 的取值三件套,经 Manager->GetSharedFragmentDataPtr<T>;值/引用版本缺失时 checkf 断言,指针版本返回 nullptr。

Value/pointer/reference fetch trio for mutable shared fragments via Manager->GetSharedFragmentDataPtr<T>; value/reference assert on absence, pointer returns nullptr.

常量共享 fragment 的取值三件套,经 Manager->GetConstSharedFragmentDataPtr<T>;值/引用版本缺失时 checkf 断言,指针版本返回 nullptr。

Value/pointer/reference fetch trio for const-shared fragments via Manager->GetConstSharedFragmentDataPtr<T>; value/reference assert on absence, pointer returns nullptr.

向实体添加 tag:立即版本 Manager->AddTagToEntity;Context 版本压入 Context.Defer().AddTag<T>;CommandBuffer 版本 CommandBuffer.AddTag<T>。processor 内使用安全。

Adds a tag to an entity: immediate via Manager->AddTagToEntity; Context version pushes Context.Defer().AddTag<T>; CommandBuffer version CommandBuffer.AddTag<T>. Safe inside processors.

向实体添加 fragment:立即版本经 AddFragmentInstanceListToEntity(FInstancedStruct 或值两种签名;已有该 fragment 时引擎记警告并忽略,原值不变);延迟版本 Context/CommandBuffer 各带默认值或指定值两种——带值版本压入 FMassCommandAddFragmentInstances。

Adds a fragment to an entity: immediate versions via AddFragmentInstanceListToEntity (taking either an FInstancedStruct or a value; when the entity already has the fragment the engine logs a warning and ignores, keeping the old value); deferred versions on Context/CommandBuffer with default or explicit value — the value versions push FMassCommandAddFragmentInstances.

立即添加共享/常量共享 fragment:先经 MASSAPI_GET_OR_CREATE_SHARED 版本宏去重,再 AddSharedFragmentToEntity(或 const 版本)。返回引擎的添加结果——实体已持有不同值的同类 fragment 时返回 false。版本差异:5.6+ 走引擎实体级添加 API;≤5.5 引擎无实体级共享片段添加,AddSharedFragment 记警告日志(共享片段须在 build/模板时提供)并返回 false,AddConstSharedFragment 同样返回 false;后者整个函数在 UE 5.4 被编出(5.5+ 守卫)。

Immediately adds a shared / const-shared fragment: dedupes via the MASSAPI_GET_OR_CREATE_SHARED version macro, then AddSharedFragmentToEntity (or the const version). Returns the engine's add result — false when the entity already holds the same kind with a different value. Version notes: 5.6+ uses the engine's entity-level add APIs; on ≤5.5 the engine has no entity-level shared-fragment addition — AddSharedFragment logs a warning (shared fragments must be provided at build/template time) and returns false, and AddConstSharedFragment likewise returns false; the latter is compiled out entirely on UE 5.4 (5.5+ guard).

从实体移除 tag:立即版本 Manager->RemoveTagFromEntity;Context / CommandBuffer 版本压入延迟命令。

Removes a tag from an entity: immediate via Manager->RemoveTagFromEntity; Context / CommandBuffer versions push deferred commands.

从实体移除 fragment:模板立即版本 Manager->RemoveFragmentFromEntity;非模板立即版本(供 BP)先校验类型非空且是 FMassFragment 派生,非法返回 false,合法调用后返回 true;两个延迟版本压入命令。

Removes a fragment from an entity: template immediate via Manager->RemoveFragmentFromEntity; non-template immediate (for BP) validates the type is non-null and derived from FMassFragment, returning false when invalid; the two deferred versions push commands.

从实体移除共享/常量共享 fragment,经 ENTITY_MANAGER_REMOVE_SHARED / REMOVE_CONST_SHARED 版本宏调用引擎 API。非模板版本校验类型非空且派生正确,非法返回 false。≤5.5 引擎无实体级共享片段移除 API,宏退化为「未移除」(false);RemoveConstSharedFragment 整体为 5.5+(UE 5.4 编出)。

Removes shared / const-shared fragments via the ENTITY_MANAGER_REMOVE_SHARED / REMOVE_CONST_SHARED version macros. Non-template versions validate the type is non-null and properly derived, returning false when invalid. On ≤5.5 the engine has no entity-level shared-fragment removal API, so the macros degrade to "not removed" (false); RemoveConstSharedFragment as a whole is 5.5+ (compiled out on UE 5.4).

延迟交换 tag:Context / CommandBuffer 版本分别 Context.Defer().SwapTags<TOld, TNew> 与 CommandBuffer.SwapTags<TOld, TNew>。两个模板参数均 static_assert 必须是 tag。

Deferred tag swap: Context / CommandBuffer versions call Context.Defer().SwapTags<TOld, TNew> and CommandBuffer.SwapTags<TOld, TNew> respectively. Both template parameters are static_asserted to be tags.

模板数据存在性检查:HasTag 遍历 GetTags().ExportTypes 比对;其余四个(HasFragment / HasChunkFragment / HasSharedFragment / HasConstSharedFragment)经 CONTAINS_T_* 版本宏检查模板 composition。

Template-data presence checks: HasTag walks GetTags().ExportTypes comparing types; the other four (HasFragment / HasChunkFragment / HasSharedFragment / HasConstSharedFragment) check the template composition via the CONTAINS_T_* version macros.

模板取值家族:GetFragment 在初值列表中按类型查找并拷贝,缺失 checkf 断言(提示先 HasFragment 或改用指针版本);GetFragmentPtr / GetFragmentRef 经 GetMutableFragment<T>(指针缺失返回 nullptr,引用缺失断言);GetSharedFragment / GetConstSharedFragment 经模板查找函数,缺失断言;两个 Ptr 版本缺失返回 nullptr。

Template value family: GetFragment finds the type in the initial values and copies, checkf-asserting on absence (hinting to use HasFragment first or the pointer version); GetFragmentPtr / GetFragmentRef go through GetMutableFragment<T> (pointer returns nullptr, reference asserts); GetSharedFragment / GetConstSharedFragment use the template lookup helpers, asserting on absence; the two Ptr versions return nullptr.

模板写值家族:SetFragment 存在则覆写、不存在则 AddFragment 添加;SetSharedFragment / SetConstSharedFragment 为写时复制——从零重建模板、跳过旧 T、经 Manager 去重后添加新值,再整体移动替换。

Template value-write family: SetFragment overwrites when present, adds via AddFragment otherwise; SetSharedFragment / SetConstSharedFragment are copy-on-write — rebuild the template from scratch, skip the old T, add the new value deduped through the Manager, then move-replace the whole template.

模板追加家族:AddTag 仅类型;AddFragment 默认值或带值两种;AddSharedFragment / AddConstSharedFragment 经 Manager 去重后添加。已存在时按引擎语义处理。

Template append family: AddTag type only; AddFragment with default or explicit value; AddSharedFragment / AddConstSharedFragment dedupe through the Manager before adding.

模板移除家族,全部写时复制:从零重建并跳过目标类型。Tag 版本跳过 GetTags 中匹配项;Fragment 版本跳过 composition 与初值中的匹配项;共享版本跳过共享值中的匹配项。

Template removal family, all copy-on-write: rebuild from scratch skipping the target type. The tag version skips matching entries in GetTags; the fragment version skips matches in both composition and initial values; the shared versions skip matches in the shared values.

把额外的 tag/fragment 合并进模板数据:Tag 走 AddTag,Fragment 走带值 AddFragment;共享 fragment 需 EntityManager,不支持——源码注释说明请直接用 AddSharedFragment。其它类型触发 static_assert。

Merges additional tags/fragments into template data: Tags via AddTag, Fragments via value AddFragment; shared fragments need an EntityManager and are unsupported — use AddSharedFragment directly per the source comment. Other types fail a static_assert.

模板深拷贝:重建新模板并复制全部 tag、fragment(类型+初值)、共享与常量共享值。

Deep copy of template data: rebuilds a new template copying all tags, fragments (type + initial values), shared and const-shared values.

读取实体的低位(0–63)或高位(64–127)旗标掩码。实现(MassAPISubsystem.cpp):实体无效返回 0;实体缺 FEntityFlagFragment 时记警告日志并返回 0。

Reads an entity's low (0–63) or high (64–127) flag bitmask. Implementation (MassAPISubsystem.cpp): returns 0 for invalid entities; logs a warning and returns 0 when the entity lacks FEntityFlagFragment.

按 EEntityFlags 的实体旗标三件套。实现:越界(>= EEntityFlags_MAX)或实体无效直接返回 false;缺 FEntityFlagFragment 时——读返回 false,写记警告日志并返回 false;写成功返回 true(已置位/已清除也返回 true)。

Entity flag trio by EEntityFlags. Implementation: out-of-range (>= EEntityFlags_MAX) or invalid entities return false directly; when FEntityFlagFragment is missing — reads return false, writes log a warning and return false; successful writes return true (including already-set / already-clear states).

延迟旗标写操作:越界直接返回;否则向命令缓冲压入 FMassDeferredSetCommand 闭包,刷新时校验实体有效且含 FEntityFlagFragment 后调用 SetFlag/ClearFlag。Context 重载委托 Context.Defer()。

Deferred flag writes: out-of-range returns immediately; otherwise pushes an FMassDeferredSetCommand closure that, on flush, validates the entity and its FEntityFlagFragment before calling SetFlag/ClearFlag. The Context overload delegates via Context.Defer().

短名简写:枚举版本委托 HasEntityFlag/SetEntityFlag/ClearEntityFlag 及其 Defer 版本;FName 版本先经 UMassAPIFlagSettings::ResolveFlag 解析,未注册(EEntityFlags_MAX)时读返回 false、写静默跳过。

Short-name shorthands: enum versions delegate to HasEntityFlag/SetEntityFlag/ClearEntityFlag and their Defer versions; FName versions resolve via UMassAPIFlagSettings::ResolveFlag first — reads return false and writes silently skip when unregistered (EEntityFlags_MAX).

受保护的诊断助手:校验实体句柄活跃,经 EntityManager 的 CheckIfEntityIsActive 触发断言。

Protected diagnostic helper: validates that an entity handle is active, asserting via the EntityManager's CheckIfEntityIsActive.