UMassAPIFuncLib

立即执行 MassAPI 命令缓冲区中已排队的全部延迟命令:经 GetPtr(WorldContext) 取子系统并调用 FlushCommandBuffer()。需让排队的延迟操作当帧生效时调用。

Immediately applies all deferred commands queued in the MassAPI command buffer: fetches the subsystem via GetPtr(WorldContext) and calls FlushCommandBuffer(). Call it when queued deferred operations must take effect within the same frame.

IsValid 委托子系统的有效且活跃检查;两个比较操作符直接复用 FEntityHandle 的 == / !=。

IsValid delegates the subsystem's valid-and-active check; the two comparison operators reuse FEntityHandle's == / !=.

销毁单实体或批量实体,支持延迟。延迟单实体:压入 FMassDeferredDestroyCommand,刷新时实体有效才销毁并触发回调;立即路径直接 DestroyEntity 后回调。批量延迟:压入闭包,刷新时 BatchDestroyEntities 并对每个句柄触发回调;立即路径直接批量销毁后逐个回调。子系统中途不可用时静默返回(批量版本还要求数组非空)。

Destroys single or batched entities, with a deferred option. Deferred single: pushes an FMassDeferredDestroyCommand; on flush destroys only if valid, then fires the callback. Immediate path destroys then fires. Deferred batch: pushes a closure that runs BatchDestroyEntities and fires the callback per handle; immediate path destroys the batch then fires per handle. Returns silently when the subsystem is unavailable mid-flight (the batch version also requires a non-empty array).

基于模板数据的构建三件套。单实体延迟:立即 ReserveEntity,模板 Sort() 后快照 descriptors 压入 FMassDeferredCreateCommand(失败释放预留),刷新时 build + 写初值 + 回调,返回预留句柄;立即路径 BuildEntity 后回调。批量(数量)延迟:批量预留、批量 build 命令、逐个回调;立即路径 BuildEntities 后逐个回调。数组版本:每个模板建一个实体,空模板释放预留/返回空句柄;立即路径对空数据追加默认句柄。

Build trio from template data. Deferred single: immediately ReserveEntity, Sort() the template and snapshot descriptors into an FMassDeferredCreateCommand (releasing the reservation on failure); on flush build + initial values + callback, returning the reserved handle. Immediate path calls BuildEntity then fires. Deferred batch: batch-reserve, one build command, per-handle callbacks; immediate calls BuildEntities then fires per handle. Array version: one entity per template; empty templates release the reservation / append default handles on the immediate path.

单实体查询匹配(委托 MassAPI->MatchQuery);批量版本把数组按查询拆分为匹配/不匹配两组(不匹配组含无效实体;子系统不可用时全部进不匹配组)。

Single-entity query match (delegates MassAPI->MatchQuery); the batch version splits the array into matching/unmatching groups (invalid entities go to unmatching; all go unmatching when the subsystem is unavailable).

查询计数与结果获取。实现(MassAPIFuncLib.cpp):Query.GetNativeQuery(EntityManager) 建原生查询;无旗标条件时快速路径(计数直接 GetNumMatchingEntities,获取直接转换);有旗标条件时慢路径——取全部匹配句柄后逐个按低/高位旗标过滤。GetMatchingEntities 警告:结果集可能巨大而拖累性能,批量获取仅建议原型期使用;正式逻辑请改用 GetNumMatchingEntities(数量查询)或 ForEach 循环。

Query count and result fetch. Implementation (MassAPIFuncLib.cpp): builds a native query via Query.GetNativeQuery(EntityManager); fast path when no flag conditions (count via GetNumMatchingEntities, fetch by direct conversion); slow path with flag conditions — fetch all matching handles then filter per-entity by low/high flags. GetMatchingEntities warns: the result set may be huge and hurt performance — batch fetch is for prototyping only; prefer GetNumMatchingEntities (count) or the ForEach loop for real logic.

ForEach 游标迭代四件套(BlueprintInternalUseOnly,供 K2 节点内部使用)。Begin 版本:取子系统(不可用返回 -1),分配 NextForEachId++ 作为游标 ID,把实体列表(查询匹配结果或传入数组的拷贝)存入子系统的 EntityForEachStates 并置索引 0。Advance 版本:按 ID 取游标,越界/不存在时移除游标并返回 false;否则填充 OutElement / OutIndex 并推进索引。迭代完成自动清理游标状态。

ForEach cursor iteration quartet (BlueprintInternalUseOnly, used internally by the K2 nodes). Begin versions: fetch the subsystem (return -1 when unavailable), claim NextForEachId++ as the cursor ID, store the entity list (query matches, or a copy of the passed array) in the subsystem's EntityForEachStates with index 0. Advance versions: look up the cursor by ID; on missing/overrun remove the cursor and return false; otherwise fill OutElement / OutIndex and advance. Iteration end cleans up the cursor automatically.

模板转换:GetTemplateData 取子系统与 EntityManager,经 Template.GetTemplateData 编译蓝图模板为运行时数据(失败返回空句柄);Conv_TemplateToTemplateData 是 BlueprintAutocast 转换器,直接委托前者;IsEmpty_TemplateData 检查底层数据为空或无效(Data->IsEmpty(),空句柄视为空)。

Template conversion: GetTemplateData fetches the subsystem and EntityManager, compiling the Blueprint template into runtime data via Template.GetTemplateData (empty handle on failure); Conv_TemplateToTemplateData is a BlueprintAutocast converter delegating to it; IsEmpty_TemplateData checks the underlying data is empty or invalid (Data->IsEmpty(); empty handles count as empty).

实体快照:把活跃实体的完整 composition(全部 tag、带当前值的 fragment、共享/常量共享 fragment)与旗标(拆解为 Flags 数组以支持与 GetTemplateData 往返)捕获为蓝图友好的 FEntityTemplate。实现细节(SnapshotEntityToTemplate):FEntityFlagFragment 被跳过并从位掩码拆解;单实体版本输出 bSuccess(子系统/管理器/实体不可用时记警告并置 false);批量版本跳过无效实体并记警告(结果数组可能短于输入)。

Entity snapshot: captures a live entity's full composition (all tags, fragments with current values, shared/const-shared fragments) plus flags (decomposed into the Flags array for round-trip compatibility with GetTemplateData) into a Blueprint-friendly FEntityTemplate. Implementation details (SnapshotEntityToTemplate): FEntityFlagFragment is skipped and decomposed from the bitmask; the single version outputs bSuccess (warns and sets false when the subsystem/manager/entity is unavailable); the batch version skips invalid entities with a warning (the result may be shorter than the input).

双精度 → 浮点精度的自动转换器:Conv_DoubleToFloat(double → float)、Conv_VectorToVector3f、Conv_QuatToQuat4f、Conv_RotatorToRotator3f、Conv_TransformToTransform3f、Conv_Vector2DToVector2f、Conv_Vector4ToVector4f。实现均为对应类型的强制转换。

Auto-cast converters from double-precision to float-precision: Conv_DoubleToFloat (double → float), Conv_VectorToVector3f, Conv_QuatToQuat4f, Conv_RotatorToRotator3f, Conv_TransformToTransform3f, Conv_Vector2DToVector2f, Conv_Vector4ToVector4f. Implementations are plain casts between the corresponding types.

统一设置实体上的 Fragment / SharedFragment / ConstSharedFragment,节点自动适配 InFragment 连接的结构的类型。蓝图函数体 checkNoEntry();实际逻辑在 Generic_SetFragment_Entity_Unified。分派:普通 Fragment——延迟时压入 FMassDeferredSetCommand 闭包(刷新时 AddFragmentInstanceListToEntity + 回调),立即时已有则 SetEntityFragmentValues 覆写、没有则 AddFragment,成功后回调;Shared/ConstShared——延迟不支持(记警告并置 bSuccess=false),立即时先移除旧值再经 GetOrCreateSharedFragment(内存) 去重添加;其它类型记警告。执行器 execSetFragment_Entity_Unified 用 P_GET_PROPERTY(FDelegateProperty) 读委托并做二进制安全转换。

Unified set of a Fragment / SharedFragment / ConstSharedFragment on an entity; the node auto-adapts to the type of the struct connected to InFragment. The Blueprint-facing body is checkNoEntry(); the real logic lives in Generic_SetFragment_Entity_Unified. Dispatch: plain Fragment — deferred pushes an FMassDeferredSetCommand closure (on flush AddFragmentInstanceListToEntity + callback), immediate overwrites via SetEntityFragmentValues when present or AddFragment when absent, callback on success; Shared/ConstShared — deferred unsupported (warning + bSuccess=false), immediate removes the old value then adds via GetOrCreateSharedFragment(memory); anything else logs a warning. The executor execSetFragment_Entity_Unified reads the delegate via P_GET_PROPERTY(FDelegateProperty) and converts it binary-safely.

统一设置模板数据中的 Fragment / SharedFragment / ConstSharedFragment(存在则覆盖,不存在则添加)。逻辑在 Generic_SetFragment_Template_Unified:写时复制——按目标类型分派重建(普通 Fragment 复制全部类型与初值后添加/覆写目标;共享版本跳过旧 T 后经 Manager 去重添加),最后整体替换 TemplateData。Chunk fragment 不支持按值设置(记警告并中止)。

Unified set of a Fragment / SharedFragment / ConstSharedFragment in Template Data (overrides when present, adds otherwise). Logic in Generic_SetFragment_Template_Unified: copy-on-write — rebuilds dispatching on the target type (plain Fragment copies all types and initial values then adds/overwrites the target; shared versions skip the old T and add deduped via the Manager), finally replacing TemplateData wholesale. Chunk fragments cannot be set by value (warns and aborts).

统一读取实体上的 Fragment / SharedFragment / ConstSharedFragment。逻辑在 Generic_GetFragment_Entity_Unified:按类型分派——Fragment 经 GetFragmentDataStruct、Shared 经 GetSharedFragmentDataStruct、ConstShared 经 GetConstSharedFragmentDataStruct,视图有效则 CopyScriptStruct 拷入输出并置 bSuccess=true;Chunk fragment 不支持经句柄读取(记警告);未知类型记警告。执行器先 InitializeStruct 初始化输出内存。

Unified read of a Fragment / SharedFragment / ConstSharedFragment from an entity. Logic in Generic_GetFragment_Entity_Unified: dispatches by type — Fragment via GetFragmentDataStruct, Shared via GetSharedFragmentDataStruct, ConstShared via GetConstSharedFragmentDataStruct; on a valid view it CopyScriptStructs into the output and sets bSuccess=true; Chunk fragments cannot be retrieved via entity handle (warns); unknown types warn. The executor InitializeStructs the output memory first.

统一从模板数据读取 Fragment / SharedFragment / ConstSharedFragment。逻辑在 Generic_GetFragment_Template_Unified:Fragment 在初值列表中按类型查找;Shared / ConstShared 在共享值中按类型查找;找到且有效则拷贝并置 bSuccess=true。Chunk fragment 无值可取(记警告);模板为空或类型非法记警告。

Unified read of a Fragment / SharedFragment / ConstSharedFragment from Template Data. Logic in Generic_GetFragment_Template_Unified: Fragments searched by type in the initial values; Shared / ConstShared searched in the shared values; on a valid find it copies and sets bSuccess=true. Chunk fragments have no retrievable value (warns); empty templates or invalid types warn.

从实体移除 Fragment / SharedFragment / ConstSharedFragment。延迟路径仅支持普通 Fragment 与 Tag(压入 FMassDeferredRemoveCommand,刷新时校验后移除并回调);Shared/ConstShared 延迟不支持(记警告返回 false)。立即路径按类型分派:Fragment 移除后返回 true;Shared/ConstShared 返回引擎结果;Chunk 不支持(记警告);未知类型记警告。

Removes a Fragment / SharedFragment / ConstSharedFragment from an entity. The deferred path supports plain Fragments and Tags only (pushes an FMassDeferredRemoveCommand, validates then removes and fires on flush); deferred Shared/ConstShared is unsupported (warns, returns false). The immediate path dispatches by type: Fragments remove then return true; Shared/ConstShared return the engine result; Chunk unsupported (warns); unknown types warn.

从模板数据移除 Fragment / SharedFragment / ConstSharedFragment。写时复制重建(逻辑在 MassAPIFuncLib.cpp):复制全部内容,按目标类型跳过匹配项(Chunk 在类型复制循环中处理);未知类型记警告并中止。Tag 不受影响(注释说明 Tags 不被此函数移除)。

Removes a Fragment / SharedFragment / ConstSharedFragment from Template Data. Copy-on-write rebuild (logic in MassAPIFuncLib.cpp): copies everything, skipping matches of the target type (Chunk handled in the type-copy loop); unknown types warn and abort. Tags are unaffected (per source comment, Tags are not removed by this function).

统一存在性检查:实体版本按 IsChildOf 分派到 CONTAINS_FRAGMENT / CONTAINS_TAG / CONTAINS_SHARED / CONTAINS_CONST_SHARED / CONTAINS_CHUNK(注意同时覆盖 Tag);模板版本经 TEMPLATE_HAS_FRAGMENT / TEMPLATE_HAS_SHARED / TEMPLATE_HAS_CONST_SHARED 宏与 Chunk 位集检查。非法类型/空模板记警告并返回 false。

Unified presence checks: the entity version dispatches via IsChildOf to CONTAINS_FRAGMENT / CONTAINS_TAG / CONTAINS_SHARED / CONTAINS_CONST_SHARED / CONTAINS_CHUNK (note it also covers Tags); the template version uses the TEMPLATE_HAS_FRAGMENT / TEMPLATE_HAS_SHARED / TEMPLATE_HAS_CONST_SHARED macros plus a Chunk bit-set check. Invalid types / empty templates warn and return false.

Tag 六件套。实体版本要求类型是 FMassTag 派生(否则直接返回):AddTag_Entity / RemoveTag_Entity 延迟时压入 FMassDeferredAddCommand / FMassDeferredRemoveCommand(刷新时校验实体后操作并回调),立即时直接操作后回调;HasTag_Entity 委托子系统。模板版本 AddTag_Template 用 TEMPLATE_ADD_TAG、RemoveTag_Template 用 TEMPLATE_REMOVE_TAG、HasTag_Template 用 CONTAINS_TAG 检查模板 composition。添加目标已有的标签、或移除目标没有的标签,均为 no-op(幂等,无副作用)。

Tag sextet. Entity versions require the type derives from FMassTag (else early-return): AddTag_Entity / RemoveTag_Entity push FMassDeferredAddCommand / FMassDeferredRemoveCommand when deferred (validate then operate and fire on flush) or operate immediately then fire; HasTag_Entity delegates to the subsystem. Template versions use TEMPLATE_ADD_TAG / TEMPLATE_REMOVE_TAG / CONTAINS_TAG on the template composition. Adding a tag the target already has, or removing one it lacks, is a no-op (idempotent, no side effects).

旗标八件套(按 EEntityFlags)。实体版本:Set/Clear 延迟时压入 FMassDeferredSetCommand 闭包(刷新时校验实体与 FEntityFlagFragment 后修改并回调),立即时委托子系统对应方法后回调;Has 委托子系统;Get 委托 GetEntityFlags(仅低位)。模板版本:Set/Clear 先读模板中现有 FEntityFlagFragment 的低/高位,在临时 fragment 上修改后经 Generic_SetFragment_Template_Unified 写回(写时复制,『不存在则新增、存在则覆盖』);Set 在模板缺少 FEntityFlagFragment 时会按需新建该片段;Has 在模板初值中查找 fragment 并调其 HasFlag;Get 返回模板初值中 fragment 的低位掩码。所有版本越界(>= EEntityFlags_MAX)直接返回 false / 跳过。

Flag octet (by EEntityFlags). Entity versions: Set/Clear deferred push an FMassDeferredSetCommand closure (validate entity and FEntityFlagFragment, mutate and fire on flush), immediate delegate to the subsystem methods then fire; Has delegates the subsystem; Get delegates GetEntityFlags (low only). Template versions: Set/Clear read the template's existing FEntityFlagFragment low/high masks, mutate a temp fragment, write back via Generic_SetFragment_Template_Unified (copy-on-write; adds when absent, overrides when present); Set creates the FEntityFlagFragment as needed when the template lacks it; Has finds the fragment in the template initial values and calls its HasFlag; Get returns the fragment's low mask from the initial values. All versions return false / skip on out-of-range (>= EEntityFlags_MAX).

FName 版本:经 MassAPIFuncLib.cpp 的静态助手 LookupFlagByName 解析为 EEntityFlags——查 UMassAPIFlagSettings(UDeveloperSettings 派生的开发者设置)的 FlagRegistry,该注册表初始为空、由用户或集成插件填充;未注册返回 false / 静默跳过;解析成功后委托对应枚举版本(含 FEntityFlagFragment 前置要求)。

FName versions: resolve to EEntityFlags via the MassAPIFuncLib.cpp static helper LookupFlagByName, which looks up FlagRegistry on UMassAPIFlagSettings (a UDeveloperSettings-derived developer settings object; the registry starts empty and is populated by users or integrating plugins); unregistered names return false / silently skip; otherwise they delegate to the enum versions (including the FEntityFlagFragment prerequisite).