MassAPIWorldContextPin.h
Source/MassAPIUncooked/Public/MassAPIWorldContextPin.h
概述 Overview
MassAPI 智能 K2 节点「可选 WorldContext 透传引脚」的共享助手(编辑器专用,整个文件位于 #if WITH_EDITOR 内,cook 后不参与打包)。引脚仅在勾选节点的 bShowWorldContext 细节面板复选框时存在;未勾选时,节点展开出的内部调用保持 DefaultToSelf 行为——默认关闭即零行为变化。提供三件东西:统一引脚名(命名空间 MassAPIWorldContext 的 PinName)、外科手术式建脚/删脚(CreateOn / SyncPinOn),以及在编译期把节点代理引脚接到内部调用的连线宏 MASSAPI_LINK_WC。被全部 Operation 系列 K2 节点(Set/Has/Clear Flag、Get/Set/Has Fragment、Has Tag 等)共用。
Shared helpers for the optional WorldContext pass-through pin on MassAPI smart K2 nodes (editor-only: the entire file sits inside #if WITH_EDITOR and never ships in cooked builds). The pin only exists while the node's bShowWorldContext detail checkbox is checked; when absent, the spawned internal calls keep their DefaultToSelf behavior — default-off is a zero-behavior change. It provides three things: the shared pin name (PinName in the MassAPIWorldContext namespace), surgical pin add/remove (CreateOn / SyncPinOn), and the compile-time wiring macro MASSAPI_LINK_WC that links the node's proxy pin to the spawned internal call. Shared by all Operation-series K2 nodes (Set/Has/Clear Flag, Get/Set/Has Fragment, Has Tag, etc.).
命名空间函数 Namespace Functions
返回统一引脚名 "WorldContext"(函数局部 static FName,进程内只构造一次)。所有建脚、找脚、连线都经此取名字,保证节点侧代理引脚与内部调用侧输入引脚同名可配。
Returns the shared pin name "WorldContext" (a function-local static FName, constructed once per process). Pin creation, lookup and wiring all take the name from here, so the node-side proxy pin and the internal-call-side input pin are name-compatible.
Input
无参数。
No parameters.
Output
返回 FName("WorldContext")。无副作用。
Returns FName("WorldContext"). No side effects.
在节点上创建 WorldContext 输入引脚:CreatePin(EGPD_Input, PC_Object, UObject::StaticClass(), PinName()),默认值 "self"。创建后按显示规则重排位置:若节点引脚数 > 1,把引脚从数组移除,再找输入侧第一个 exec 引脚,插到它正后方(纯节点无 exec 时保持置顶,即插到索引 0)。引脚显示顺序即 Pins 数组顺序。创建成功打一条 LogTemp 日志([MassAPI] WorldContext pin created on %s)。
Creates the WorldContext input pin on the node: CreatePin(EGPD_Input, PC_Object, UObject::StaticClass(), PinName()) with default value "self". It then repositions it per the display rule: if the node has more than one pin, the pin is removed from the array and re-inserted directly after the first input exec pin (pure nodes without exec keep it at the top, i.e. index 0). Pin display order follows the Pins array order. A LogTemp line ([MassAPI] WorldContext pin created on %s) logs the creation.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Node | UEdGraphNode* | 目标 K2 节点。Target K2 node. |
Output
返回新建的 UEdGraphPin*。副作用:节点 Pins 数组新增(并重排)该引脚;打一条日志。
Returns the new UEdGraphPin*. Side effects: the node's Pins array gains (reordered) the pin; one log line emitted.
按 bShowWorldContext 的当前值外科手术式增删引脚——复刻插件内已验证的 bDeferred 模式:需要而缺失时直接 CreateOn;不需要而存在时 BreakAllPinLinks() + RemovePin。不走整节点重建(ReconstructNode 往返)。典型调用点是节点 PinDefaultValueChanged 处理器:细节面板复选框变化即刻反映为引脚增删。
Surgically adds/removes the WorldContext pin to match bShowWorldContext — mirroring the plugin's proven bDeferred pattern: CreateOn directly when needed but missing; BreakAllPinLinks() + RemovePin when present but unwanted. NO full ReconstructNode round-trip. The typical call site is the node's PinDefaultValueChanged handler: a details-checkbox change reflects as an immediate pin add/remove.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
Node | UEdGraphNode* | 目标 K2 节点。Target K2 node. |
bShow | bool | 期望状态(true = 引脚应存在;false = 应移除)。已匹配时无操作。Desired state (true = pin should exist; false = should be removed). No-op when already in sync. |
Output
无返回值。副作用:增删节点引脚;移除时先断开该引脚全部连线。
No return value. Side effects: adds/removes the node pin; removal breaks all of the pin's links first.
编译期连线宏:把节点的 WorldContext 代理引脚(若显示)接到展开出的内部调用 CallNode 的 WorldContext 输入。展开为——当 OwnerNode->bShowWorldContext 为真:ProxyPin(MassAPIWorldContext::PinName()) 取代理引脚,在 CallNode 上 FindPin(PinName(), EGPD_Input) 取内部输入,二者 Link。仅在 HNCH(超节点编译处理器)内展开——宏直接引用 OwnerNode / ProxyPin / Link,这些只在编译处理器上下文中可用。
Compile-time wiring macro: wires the node's WorldContext proxy pin (if shown) to the spawned internal call CallNode's WorldContext input. Expands to — when OwnerNode->bShowWorldContext is true: take the proxy via ProxyPin(MassAPIWorldContext::PinName()), take the internal input via FindPin(PinName(), EGPD_Input) on CallNode, then Link them. Expand inside an HNCH (hyper-node compiler handler) only — the macro references OwnerNode / ProxyPin / Link directly, which exist only in compiler-handler context.
Input
| 参数 Param | 类型 Type | 说明 Description |
|---|---|---|
CallNode | UK2Node*(宏内任意带 WorldContext 输入引脚的调用节点)UK2Node* (any call node inside the macro that has a WorldContext input pin) | 本次展开生成的内部调用节点。The internal call node produced by the current expansion. |
Output
无返回值。副作用:代理引脚与内部调用的 WorldContext 引脚建立连线;节点未勾选 bShowWorldContext 或任一引脚缺失时无操作。
No return value. Side effect: a link is created between the proxy pin and the internal call's WorldContext pin; no-op when bShowWorldContext is unchecked or either pin is missing.
管线角色 Pipeline Role
本头是编辑器侧 K2 节点基建,被 13 个 Operation 系列节点 cpp 包含(1.19.20 发布树 grep 验证):OperationFlag 六个(Set/Has/Clear Flag 及 ByName 变体)、OperationFragment 六个(Get/Set/Has/Remove Fragment、ForEachEntityHandle、ForEachMatchingEntities)、OperationTag 一个(HasTag)。使用模式(以 K2Node_SetMassFlag.cpp 为实例验证):① PinDefaultValueChanged 处理器在属性名等于 bShowWorldContext 时调用 MassAPIWorldContext::SyncPinOn(this, bShowWorldContext),复选框变化即刻增删引脚;② 编译展开处对各内部调用节点逐个展开 MASSAPI_LINK_WC(SetFunctionNode) 完成连线。各消费节点页:OperationFlag/K2Node_SetMassFlag、OperationFragment/K2Node_GetMassFragment、OperationTag/K2Node_HasMassTag。
This header is editor-side K2 node infrastructure, included by 13 Operation-series node cpp files (grep-verified in the 1.19.20 release tree): six in OperationFlag (Set/Has/Clear Flag plus the ByName variants), six in OperationFragment (Get/Set/Has/Remove Fragment, ForEachEntityHandle, ForEachMatchingEntities), and one in OperationTag (HasTag). Usage pattern (verified on K2Node_SetMassFlag.cpp): ① the PinDefaultValueChanged handler calls MassAPIWorldContext::SyncPinOn(this, bShowWorldContext) when the changed property is bShowWorldContext, so checkbox toggles add/remove the pin immediately; ② each compiler expansion site expands MASSAPI_LINK_WC(SetFunctionNode) per spawned internal call to wire it. Consumer node pages: OperationFlag/K2Node_SetMassFlag, OperationFragment/K2Node_GetMassFragment, OperationTag/K2Node_HasMassTag.
补充说明 Notes
bShowWorldContext 复选框本身声明在各消费节点类上(如 K2Node_HasMassFragment.h 中 bool bShowWorldContext = false;),默认关闭——关闭状态下内部调用保持 DefaultToSelf,引脚不存在,节点行为与本特性引入前完全一致。整个文件在 #if WITH_EDITOR 内,不参与打包构建。
The bShowWorldContext checkbox itself is declared on each consumer node class (e.g. bool bShowWorldContext = false; in K2Node_HasMassFragment.h), default-off — with it off, internal calls keep DefaultToSelf, the pin does not exist, and node behavior is byte-for-byte what it was before the feature. The entire file sits inside #if WITH_EDITOR and takes no part in packaged builds.