Mass Forge architecture guide

Ownership boundary

Mass Forge owns generation-safe entity handles and the attributes, effects, damage, tags, abilities, projectiles, queues, persistence, and diagnostics built on them. A game project owns spawning policy, movement/navigation, AI decisions, factions, player framework, presentation, UI, balance, and any supported multiplayer model.

Mass Forge adds attributes, effects, damage, abilities, and inspection to Unreal Engine Mass entities without making Actors or per-entity UObjects authoritative. This guide explains which layer owns each responsibility, how data reaches runtime fragments, and which entry path to use when extending the plugin.

System at a glance

Project settings + validated Data Assets
                  |
                  v
        Entity Config traits
                  |
                  v
    compact fragments / shared graphs
          |                 |
          v                 v
 automatic Mass processors  world subsystems and bounded queues
          |                 |
          +--------+--------+
                   v
       committed entity state and result events
                   |
                   v
  optional Actors, UI, audio, VFX, AI, and inspection

The upper layers compile designer-facing names and asset references. The entity-processing layer uses stable slots, fixed-capacity storage, and numeric iteration. Presentation consumes results afterward and is never the source of simulation truth.

Ownership boundaries

Concern	Authoritative owner	Important boundary
Attribute definitions	Global schema Data Assets selected in project settings	A stable domain/name identity compiles to a runtime slot; deployed renames require migration
Per-entity values	Mass fragments	Actors and UI are views or request sources, not value owners
Derived values and regeneration	Automatic Mass processors	Authoring data is compiled before entity iteration
Instant transactions	Attribute subsystem	All modifiers and counted-tag changes for one target commit atomically
Persistent lifetime	Persistent Effect subsystem plus compact entity fragments	The world subsystem owns definitions, contexts, handles, and deadline scheduling
Damage policy and calculation	Damage subsystem	Project policy may veto; committed attribute/tag changes use the shared transaction path
Mass projectiles	Projectile fragment, processor, and subsystem	Compact motion remains on Mass entities; optional damage commits only after a queued impact reaches a Mass-idle boundary
Ability grants, clocks, and lifecycle requests	Ability fragment plus Ability subsystem	One shared bounded FIFO handles Activate/Grant/Revoke/Cancel/Interrupt; one activation transaction spans its source and at most one target
Durable entity persistence	Entity State subsystem plus project-owned SaveGame	Format 4 commits attributes, exact tags, grants, cooldowns, charges, regeneration timing, active Persistent Effects, and one active cast/channel together; external lifecycle targets require an explicit stable-reference remap
Unsafe external calls	Deferred-command coordinator	Queue acceptance is not execution success; completion events carry the final result
Presentation and ordinary Actors	Blueprint libraries, receiver/provider interfaces, and project code	Representation may appear, disappear, or change without changing Mass identity
Debugging	On-demand inspection subsystem and editor-only inspector	No continuously mirrored debug UObject is stored per entity

Modules and folder layout

• MassForge is the Runtime module. Public headers contain the supported C++ surface; private code contains subsystem, processor, trait, and automation implementations.
• MassForgeEditor is Editor-only. It owns schema and gameplay-asset Details customizations, the Entity Config wizard, Project Health, the Entity Inspector, the Event History browser, and editor automation.
• MassForgeSamples is the shipped Runtime showcase module. It owns the six playable sample modes and their reusable sample-facing presentation layer; it depends on the core while the core never depends on it.
• MassForgeSamplesEditor is the shipped Editor showcase companion. It owns the Showcase Browser and play-session telemetry monitor described in SHOWCASES_GUIDE.md.
• Content is optional and reserved for curated, namespaced distributable content. Core runtime behavior does not depend on example assets.
• Config contains packaging filters. Docs, Resources, the README, and changelog are shipped and hash-audited with the plugin. Maintainer-only Scripts and Examples verification fixtures remain in the source repository and are excluded from customer packages.

The runtime depends on Unreal's MassGameplay family. Simulation LOD interoperability uses the engine's MassLOD module; Mass Forge does not define a competing LOD classifier.

Schemas and attributes

UMF_MassForgeAttributesSchemaSettings selects one global schema for each storage domain:

• UMF_VitalAttributesSchemaData maps up to 16 Vital attributes.
• UMF_CombatAttributesSchemaData maps up to 48 Combat attributes.
• UMF_SupportAttributesSchemaData maps up to 32 Support attributes.

Each schema entry has a stable slot, name, display metadata, default, and optional clamp. UMF_AttributesTrait creates FMF_VitalAttributesFragment, FMF_CombatAttributesFragment, and FMF_SupportAttributesFragment, then copies schema defaults into the fixed arrays when the Entity Config template is built.

Blueprint calls use FMFAttributeId domain/name identities. C++ high-volume code compiles those identities into generation-checked FMFCompiledAttribute bindings before iteration and operates through numeric slots. Refreshing schemas increments the generation and invalidates old bindings instead of silently redirecting them.

Opt-in fragments and traits

Trait	Runtime storage added	Use it when
UMF_TransformTrait	Unreal's standard FTransformFragment	The entity is spawned, placed, targeted, or presented through the Blueprint-first workflow
UMF_AttributesTrait	FMF_VitalAttributesFragment, FMF_CombatAttributesFragment, FMF_SupportAttributesFragment	The entity owns any Mass Forge attribute
UMF_GameplayTagTrait	FMF_GameplayTagFragment	The entity needs counted tags, gates, immunity, or effect-owned tags
UMF_AbilityTrait	FMF_AbilityFragment	The entity grants or activates abilities, cooldowns, groups, charges, casts, or channels
UMF_PersistentEffectsTrait	FMF_PersistentEffectsFragment, FMF_PersistentAttributeModifiersFragment	The entity receives finite/infinite effects, stacking, periodic work, or reversible modifiers
UMF_RegenerationTrait	FMF_RegenerationFragment	The entity runs compiled passive regeneration or degeneration rules
UMF_DerivedAttributesTrait	FMF_DerivedAttributesSharedFragment	The archetype evaluates a shared compiled derived-attribute graph
UMF_HighVolumeEffectsTrait	FMF_HighVolumeEffectCommandFragment, FMF_HighVolumeEffectSetSharedFragment	C++ producer processors apply/remove a small context-free effect pair across large populations without lookup or allocation
UMF_ProjectileTrait	FMF_ProjectileFragment	The entity represents a Mass-owned projectile with compact launch delay, travel, arc, lifetime, impact, and presentation-channel state

Traits are deliberately opt-in. The Entity Config wizard supplies dependency-safe common presets, but profile-backed traits still require project-specific validated assets. Exact fragment bytes and preset totals are in the memory and capacity guide.

Authored Data Assets

• Attribute schemas define identity, storage, defaults, bounds, and editor metadata.
• UMF_InstantEffectData defines an ordered, atomic set of attribute and counted-tag mutations.
• UMF_PersistentEffectData adds lifetime, period, stacking, immunity, cancellation, granted tags, and reversible modifiers around optional Instant Effects.
• UMF_DamageDefinitionData defines presentation-neutral Health, Shield, power, mitigation, critical, gating, and death-handling policy.
• UMF_AbilityData defines built-in and custom requirements, costs, cooldowns, charges, targeting policies, instant/persistent payloads, an optional execution plan, and optional cast/channel behavior.
• UMF_RegenerationProfileData compiles passive linear rules into each participating entity.
• UMF_DerivedAttributeProfileData compiles a dependency-sorted formula graph into const-shared archetype data.
• UMF_AttributeSnapshotMigrationData declares explicit saved-attribute rename, move, or removal steps between schema versions.
• UMF_AbilityTargetingPolicy and its built-in range implementation validate a selected target before reservation or commit.
• UMF_AbilityCondition provides ordered, fail-closed, project-authored Blueprint/C++ admission rules that are re-evaluated at commit without adding per-entity objects.
• UMF_AbilityExecutionPlan provides bounded fail-closed Blueprint/C++ transaction descriptions; UMF_StaticAbilityExecutionPlan supplies data-only activation and channel-pulse payloads.
• UMF_EffectMagnitudeCalculation provides a shared, fail-closed Blueprint/C++ formula after built-in parameter/capture resolution; reversible persistent contributions snapshot its finite output, while periodic Instant Effects recalculate per pulse.

Data validation and Project Health reject malformed IDs, missing attributes, non-finite numeric values, incompatible references, duplicate durable Primary Asset IDs, and unsupported migration graphs before release.

Runtime subsystems

Subsystem	Responsibility
UMF_AttributeSubsystem	Schema caches, entity/Actor resolution, attribute access, guarded custom magnitude evaluation, atomic Instant Effects, versioned snapshots, compiled bindings, bounded restore/attribute/effect queues, and change/completion publication
UMF_GameplayTagSubsystem	Counted-tag access, mutation, hierarchical queries, and tag-change publication
UMF_PersistentEffectSubsystem	Apply, stack, query, remove, rollback, reversible modifiers, periodic execution, deadline scheduling, and lifecycle events
UMF_DamageSubsystem	Damage validation/calculation, project policy providers, atomic commit, queues, death policy, and bounded destruction requests
UMF_ProjectileSubsystem	Bounded projectile launch, renderer-neutral snapshots, impact queuing, optional impact-driven damage, cleanup, and resolution events
UMF_AbilitySubsystem	Grants, built-in/custom requirements, target policies, bounded execution-plan evaluation, activation, cooldowns, charges, casts/channels, AI tickets, queues, rollback, and lifecycle events
UMF_EntityStateSubsystem	Versioned durable-state capture, complete validation, atomic attribute/tag/ability restore, remaining-time reconstruction, and bounded restore completion
UMF_DeferredCommandSubsystem	The only gameplay queue/scheduler coordinator and its fixed cross-system phase order
UMF_EntityInspectionSubsystem	On-demand unified snapshots and bounded project-supplied inspection sections
UMF_GameplayEventSubsystem	Opt-in normalization, bounded history, entity watch filtering, and project-defined debug/telemetry events without changing legacy delegates
UMF_NetworkAuthoritySubsystem	Session identity, authoritative entity resolution, server definition catalog, and fail-closed request policies

Blueprint function libraries provide convenient static entry points, but state and transaction ownership remains in these world subsystems.

Owner-bound Player Controller components form the connection edge. UMF_NetworkRequestComponent authenticates and dispatches bounded client mutation requests; its optional bounded Ability-prediction ledger emits presentation-only intent and reconciles reliable authority receipts/completions without changing client gameplay state. UMF_NetworkStateComponent captures project-selected entities into an owner-only Fast Array containing filtered/quantized stable attributes, counted tags, ability/cooldown/lifecycle state, and persistent effects. It emits an immediate baseline when relevance begins, including for a late join, then refreshes a bounded round-robin subset and advances revisions only on semantic post-quantization changes.

Automatic Mass processors

All Mass Forge processors run in PrePhysics and use marked, verifier-enforced hot loops:

1. UMF_HighVolumeEffectsProcessor consumes one bounded precompiled Apply/Remove mailbox per opted-in entity before derived evaluation.
2. UMF_DerivedAttributesProcessor evaluates the const-shared graph in compiled dependency order.
3. UMF_RegenerationProcessor applies compiled passive rules after derived values and after Unreal's Simulation LOD timing update.
4. UMF_PersistentAttributeModifiersProcessor reconciles external Mass writes and reapplies active additive, multiplicative, and priority-override aggregates after regeneration.

UMF_ProjectileProcessor is an independent PrePhysics processor. It advances each FMF_ProjectileFragment through launch delay and bounded travel, then queues one impact record with UMF_ProjectileSubsystem. The subsystem resolves the optional damage payload only after Mass processing is idle, so visible travel and gameplay impact share one authoritative lifecycle without dispatching delegates or carrying UObject payloads inside the entity hot loop.

Entity loops may use only fragment views, stable slots, fixed-capacity records, and bounded numeric scans. Name lookup, asset loading, dynamic containers, allocation, reflection, logging, and event dispatch are excluded from these loops by the release verifier.

Custom magnitude assets belong to the direct/queued transaction path and never execute in a Mass processor hot loop. The High Volume Effects Trait rejects them at compilation; high-volume producers must supply already compiled numeric operations.

Direct, queued, and processor paths

Caller situation	Correct path	Result contract
Blueprint or game-thread C++ while Mass is idle	Direct Blueprint library or subsystem operation	Returns the final structured result synchronously
Callback, timer, async completion, or any caller that may overlap Mass processing	Corresponding bounded queue operation	Returns an acceptance receipt; observe the matching completion event for the final result
A Mass processor already holding fragment views	Compile IDs before execution and use the documented compiled fragment helpers	No asset lookup or delegate broadcast inside entity iteration
A producer processor applying/removing the same context-free effect across a large population	Cache the const-shared high-volume effect index and use the entity command/completion mailbox	One atomic command in flight per entity, explicit back-pressure, no per-entity event dispatch
Ordinary Actor that is represented by Mass	Actor convenience adapter	Resolves the full Mass generation and then uses the same entity operation
Ordinary Actor that is not a Mass entity	Effect receiver/provider interface where supported	Project-owned state remains a separate transaction boundary

Direct operations reject MassIsProcessing. Queued operations are bounded and revalidate entity generation plus stable definition identity at execution. Never treat a nonzero request ID as proof that gameplay was applied.

Deferred phase order

On each safe, unpaused world tick, UMF_DeferredCommandSubsystem snapshots and executes work in this order:

1. Entity State Restores
2. Attribute Snapshot Restores
3. Attribute Changes
4. Raw counted Gameplay Tag Changes
5. Instant Effects
6. Persistent Effects (queued Apply/Remove, then scheduled lifecycle work)
7. Projectile Impacts
8. Damage
9. Death Handling
10. Ability Lifecycles
11. Ability Requests (one FIFO for Activate, Grant, Revoke, Cancel, and Interrupt)

Work enqueued into the current or an earlier phase waits for the next coordinator tick. This bounds re-entrant callbacks and makes same-boundary outcomes deterministic. Persistent periods and expiration, damage/death publication, final channel pulses, and new activations follow the complete deterministic ordering contract.

Transactions and events

An Instant Effect is atomic for one Mass entity. An Ability activation may atomically span its source and one target, including costs, cooldowns, charges, tags, and authored effects. Arbitrary target arrays, separate queue entries, later channel pulses, ordinary Actor receiver state, and post-damage entity destruction are intentionally separate operations.

Subsystems finish validation and commit before publishing observable events. Re-entrant listeners therefore see the completed supported transaction, and rolled-back operations publish no provisional gameplay changes. Exact boundaries and partial-success guidance are in the transaction and event contract.

UMF_GameplayEventSubsystem is an opt-in observer over those native subsystem delegates. It copies normalized records into one bounded world-level circular history, can restrict capture to 64 generation-checked source/target handles, and accepts bounded project-defined AI/mind breadcrumbs. It does not add entity fragments, participate in transactions, or become gameplay authority. See the gameplay event history guide.

Multiplayer networking is outside the initial supported release. The gameplay subsystems remain world-owned and deterministic, but a customer project must supply and validate its own authority, replication, relevance, prediction, and late-join model before using Mass Forge state in a networked game.

Identity, representation, and lifetime

FMFEntityHandle carries both Mass index and serial number. Every public operation and deferred request validates the full generation, preventing a destroyed entity's queued work from reaching a recycled index. Actor representation is a temporary association; attaching, detaching, or changing LOD does not transfer ownership away from the Mass fragments.

World replacement invalidates world-local handles, requests, clocks, and subsystem metadata. The focused Attribute Snapshot persists only configured attributes; durable Entity State format 4 additionally preserves exact tags, grants, cooldowns, charges, regeneration partial intervals, active Persistent Effects, and one active cast/channel as portable gameplay time. Restored effects and lifecycles receive fresh handles; effect self-source context rebinds, external effect-source handles are cleared, and an external lifecycle target requires a project-owned stable key plus its recreated destination-world handle. Formats 1–3 remain supported inputs under their documented temporal-state rules. See the durable persistence guide, entity lifecycle safety, and time, travel, and save contract.

Extension boundaries

• Add project attributes through schemas, not by renaming compact slots in runtime code.
• Add reusable gameplay through validated Data Assets and existing transaction APIs.
• Add faction, ownership, safe-zone, or friendly-fire rules through the Damage Policy Provider.
• Add client ownership, loadout, rate-limit, and match-state authorization through a Network Request Policy; authorization remains separate from gameplay dispatch.
• Add project target discovery through the bounded Ability Target Provider; add target validity through Targeting Policy assets.
• Add dynamic per-activation or per-pulse effect selection through bounded Ability Execution Plans; returned payloads remain inside the source-plus-one-target atomic transaction.
• Add AI intent or other “mind” data through an Entity Inspection Provider.
• Add ordinary Actor interoperability through the Effect Receiver interface/component.
• Add a custom Mass processor only when work genuinely belongs in an entity batch; compile all names/assets first and follow the C++ high-volume guide and processor contract.

Mass Forge does not own navigation, faction storage, AI decision-making, animation, project ownership rules, player progression, UI, pooling, or game-specific combat balance. These remain project systems connected through explicit adapters and result events. The networking stack supplies session identity, authorization, owner-bound mutation transport, explicit per-connection relevance, per-attribute filtering/quantization, replicated gameplay state, late-join baselines, and opt-in presentation-only Ability prediction. Normal and hostile dedicated/listen multi-process certification passes on every supported engine baseline with 80 +/- 20 ms latency/jitter emulation; raw packet fuzzing, packet-loss recovery, and bandwidth saturation remain project-specific validation boundaries.

Recommended reading path

1. Blueprint-only quick start
2. Starter attributes and schema editor
3. Instant Effects, Persistent Effects, and Damage
4. Abilities, lifecycles, and target selection
5. Durable persistence, deferred commands, ordering, and error codes
6. Gameplay event history, C++ high-volume integration, memory/capacity, and verification