Processor hot-loop performance contract

Mass Forge's automatic entity processors operate only on compiled, fixed-capacity fragment data while iterating entities. Designer-facing names and assets are resolved when traits initialize entities or when a request enters a subsystem; they are not resolved again inside a processor hot loop.

This contract covers every runtime class derived directly from UMassProcessor in Source/MassForge/Public/Processors. The release verifier discovers those classes rather than relying on a manually maintained expected count.

Audited processors

Processor	Hot-loop input	Per-entity access
Mass Forge Derived Attributes Processor	Const-shared compiled rule graph	Numeric domain and stable slot indices
Mass Forge Regeneration Processor	Fixed-capacity compiled regeneration rules and optional standard Simulation LOD timing	Numeric domain and stable slot indices
Mass Forge Persistent Attribute Modifiers Processor	Fixed-capacity aggregate records	Numeric domain and stable slot indices

Each processor obtains fragment view ranges once per chunk, walks entities through FMassExecutionContext::FEntityIterator, and resolves attribute storage through ResolveAttributeSlot. Derived rules are compiled once into dependency order and shared by the archetype. Regeneration and persistent-modifier records use bounded inline arrays; they do not grow containers while processing. Regeneration optionally uses Unreal's standard Simulation LOD due-chunk filter, so non-due variable-tick chunks never enter the marked loop; due entities consume the accumulated per-entity delta.

Forbidden work inside marked hot loops

The verifier rejects the following from each bounded MF_HOT_LOOP_BEGIN / MF_HOT_LOOP_END region:

• FName construction or name/schema lookup;
• synchronous or asynchronous asset loading;
• Blueprint/native delegate broadcast or interface dispatch;
• dynamic TArray, TMap, or TSet declarations and container-growth calls;
• UObject, shared-pointer, explicit heap, or text allocation sites;
• runtime class/structure reflection; and
• logging.

The detector self-checks every forbidden-pattern family against a representative sentinel before auditing the source. Adding another UMassProcessor without a matching implementation and one bounded hot-loop region fails verification. The marked region must also retain entity-index iteration and compiled slot access.

Processor constructors may use reflected class names to declare scheduling relationships. Query configuration may declare required fragment types. Those setup operations occur outside entity iteration and are not part of the hot-loop restriction.

Runtime behavior

The processors perform arithmetic and fixed-bound scans only. Invalid floating-point inputs are skipped rather than formatted or reported from the loop. Gameplay events remain subsystem transaction output and are never broadcast by a processor. Debug snapshots are captured on demand by the inspection subsystem, outside these loops.

The verifier proves the source-level architectural boundary and strict compilation on every advertised engine. It does not replace packaged performance measurement: throughput, latency, thread time, worst-frame behavior, and complete process memory remain separate benchmark gates.

The regeneration integration's exact High, Medium, Low, Off, and no-LOD behavior is documented in the Regeneration Simulation LOD policy.

Persistent-effect lifetime scheduling is subsystem work rather than a UMassProcessor. It has its own deadline-heap/no-population-scan source gate, scaling regression, and public diagnostics described in the persistent scheduler architecture.

Extension rules

When adding a processor:

1. Compile designer names and asset references before entity iteration.
2. Store only fixed-capacity runtime state or const-shared compiled data in the queried fragments.
3. Acquire fragment views once per chunk.
4. Mark the complete entity-iteration region with the required hot-loop markers.
5. Use numeric domains, stable slots, and bounded integer loops inside that region.
6. Queue presentation or gameplay notifications for publication outside Mass processing.
7. From a complete Mass Forge source checkout, run the repository-only Scripts/Verify-MassForge.ps1 on every advertised engine baseline.