Optional MassForge entity presentation

Historical adapter boundary: the receipts below cover MassForge0.2 and their recorded core revision. The current TODO delivery/source candidates exclude this optional adapter and do not certify it against the latest MassForge release. The current core is separately verified without MassForge; these recipes remain a reference for a future adapter verification pass.

InterfaceForgeMass is a separate integration plugin under Integrations/InterfaceForgeMass. It requires InterfaceForge and MassForge; neither the core UI plugin nor default Outpost/Emberwatch project requires it. The inspected MassForge0.2 API and UE5.8.3 Win64 are the tested integration boundary. Eight current source/exact Development-package reports pass with both providers at normal/enlarged scale, plus native lifetime tests and two clean saved Blueprint compilations. Runtime evidence records exact commands and limits. Physical controller tests remain deferred; no multiplayer or older-engine integration claim is made.

Show a represented actor or actorless entity

1. Construct Object from Class → IFMassEntitySource, using your owning screen/controller as Outer. Retain it in a variable while the view is open.
2. Make a MFAttributeId with Domain Vital, Name Health (or your project's actual attribute). Call Observe Actor with the player/world context, represented Actor, attribute, display Title and Fixed Maximum. Its result is MassForge's actual representation result: Success, Different World, Not Represented, Stale Representation, and other explicit failures.
3. For actorless entities, call Observe Entity with a MFEntityHandle obtained in the same world. The handle contains Index and SerialNumber, but no world identity. Always supply the originating world; a copied bare index or handle from another world is unsafe.
4. Call Get Entity Model → Initialize Entry on a normal custom IFEntry/IFEntryWidget. Alternatively Get UI Model, name Entity, returns the same stable presentation object through IFDataSource. On Entry Refreshed reads Title, Detail, Fraction, Enabled and Unavailable Reason with your usual public widgets.
5. If your schema has a maximum attribute, set Maximum Attribute before observing; Name None uses Fixed Maximum. A configured but missing maximum produces an unavailable state, rather than silently inventing a valid reading.
6. On screen cleanup/selection removal, call Stop Observing, then release the entry and your retained source reference. The registry also uses weak references, so it does not keep discarded sources alive.

flowchart LR
    A[Game selection or actor] --> B[Observe Actor / Observe Entity]
    B --> M[Stable IFPresentationData]
    E[MassForge attribute events] --> C[World registry: coalesced dirty handles]
    C --> M
    M --> W[Your Blueprint IFEntry]
    W -->|Release| R[Stop Observing]

The registry has a hard512-source bound. Native attribute changes mark only watched entity identities dirty, coalescing repeated changes. A shared half-second lifetime check reads only registered handles; no widget ticks or whole-population query are introduced. Reads that report Mass Is Processing retain the previous fraction and expose a pending state, then retry in a later safe view tick. Destroyed/stale generations disable the retained model. Index reuse never retargets an old source automatically; explicit rebinding is required.

Forward actions without implementing gameplay

The source is read-only by default. Set Forward Actions true and bind On Action Requested only if your project wants entries to send selection/commands. Request UI Action rejects empty actions, missing consumers, released/stale entities and invalid worlds. An accepted return means the request was forwarded, not that gameplay completed.

Your callback owns action validation and network authority. Route mutations through the game's existing server/ownership rules. The adapter never grants resources, applies damage, spawns entities or implements inventory. In multiplayer, displaying local replicated entity data does not authorize a client mutation or certify MassForge replication behavior.

Equivalent standalone implementation

The optional Examples/ForgeMassExamples project supplies a small original Watchpost interface. Lyra/Orin select a scout; Hold/Ward change health, Withdraw destroys its entity, and Reinforce explicitly rebinds the retained entry to a new generation. -IFMassStandalone supplies ordinary mutable IFPresentationData to the same saved screen and entry. It compares providers inside a host that still requires MassForge; it is not proof of plugin absence.

The default Outpost and Emberwatch project independently runs without MassForge. Its readout/action Blueprint entries use the same Initialize Entry / On Entry Refreshed / Release Entry / Request UI Action contracts. A project can replace its source with a Blueprint IFDataSource and Notify Data Changed, without changing the entry's parent class. Watchpost authoring documents the actual saved graphs, responsive layout and command routing.

Dependencies and current limitations

Copy the optional integration into a project's Plugins folder only when MassForge and InterfaceForge are installed; enable it explicitly. Do not add it to the default standalone project. Private SDK validation copies under Evidence are excluded from distribution and contain no reference content assets. Only original bridge code is intended to ship in this integration.

Attribute view state includes Uninitialized, Ready, Waiting for Mass, Invalid Entity, Unavailable Attribute, Invalid World, Capacity Reached and Released. This bridge observes configured scalar attributes; abilities/effects/tags/inspection sections require explicit provider extensions, not a claim that every MassForge system is already mapped. Current-core runtime evidence verifies the actual saved example and lifecycle on UE5.8.3 Win64/MassForge0.2. Physical controls, non-Windows platforms and multiplayer behavior remain unverified.