Transaction and event contract

Mass Forge uses explicit, bounded transaction scopes. Atomic means every state write inside the named scope succeeds together or none of those writes remain. It does not mean unrelated calls, an arbitrary list of entities, project-owned Actor state, or later lifecycle work are silently included.

Supported atomic scopes

Operation	Atomic state boundary	Outside the boundary
Raw attribute change	One attribute on one Mass entity.	Other calls, even in the same frame.
Instant Effect	Every authored attribute and counted Gameplay Tag modifier on one recipient entity. Repeated modifiers for one attribute use projected authored order.	Other effect calls and ordinary Actor receiver callbacks.
Damage	Health, optional Shield, and the first-death tag on one Mass target.	Kill listeners and the later keep/deactivate/destroy policy are post-commit consequences; a destruction-queue failure does not undo lethal damage.
Ability activation	Reserved charge, individual/shared cooldown, costs on the source, self/target Instant Effects, and self/target Persistent Effect applications or cancellations across the source and one target.	Later channel pulses, unrelated activations, and any third or subsequent target.
Channel pulse	All self/target Instant Effects authored for that one pulse.	Earlier/later pulses and the original activation cost.
Persistent Effect application	The selected target's stacking decision, cancellations, lifecycle tags, persistent modifiers, and optional initial pulse.	Future periodic pulses, expiration, and other entities.
Snapshot restore	Every restorable attribute in one entity snapshot after version/schema validation.	Other entities and project-owned save data.

Every atomic operation prevalidates against projected copies or captures reversible state before publishing success. A failure returns its detailed result without publishing provisional success events. Ability rollback also restores provisional persistent handles, cancellations, tag counts, attributes, cooldowns, charges, and handle allocation.

Multi-entity rule

One ability may atomically coordinate exactly its source and one target because its payment and outcome policy are authored together. Mass Forge deliberately has no implicit transaction over an arbitrary target-selection array.

Radius, trace, collision-hit, and custom-provider selection are read-only. If a Blueprint or project system loops through ten selected candidates, each activation, effect, or damage call is a separate transaction. Candidate one can succeed and candidate two can fail; earlier successful targets are not rolled back. Queued requests are also independent, even when submitted consecutively in the same frame.

Choose the policy explicitly for an area or chain mechanic:

• Independent outcomes: submit one operation per target and retain every receipt. This permits partial success and is the normal scalable choice.
• Preflight then execute: validate every target first, then submit in deterministic order. State can still change between validation and execution, so this reduces predictable failures but is not atomic.
• Project-owned all-or-nothing batch: implement a bounded native coordinator that captures and validates all participating state, commits it without callbacks, and publishes only after success. Do not emulate this by applying public operations and trying to reverse them; listeners may already have observed those commits.

An area ability must also decide whether cost/cooldown is paid once or once per target, how targets are ordered, and what happens when one becomes stale. Mass Forge does not guess these game-specific rules.

Event visibility

For one successful Instant Effect, all attribute and tag fragments are committed before the first OnAttributeChanged, OnGameplayTagChanged, or OnInstantEffectApplied listener runs. Authored result arrays retain operation order, while a listener reading current state sees the final transaction state rather than a partially applied intermediate value.

Ability activation extends that protection across the source and target. Attribute, tag, and Persistent Effect events are buffered while the transaction is provisional. The committed lifecycle flag, costs, cooldowns, charges, self/target attributes and tags, and persistent state are all visible before buffered listeners run. A rollback discards the buffered events.

Callbacks may query the complete committed state, enqueue follow-up work, cancel the exact active lifecycle, or begin a replacement lifecycle. Identity checks prevent the outer execution frame from continuing against a callback-created replacement. Work enqueued from a completion callback cannot recursively flush the coordinator; it starts on the next eligible safe tick.

Direct operations invoked by a listener are new transactions. They never join or retroactively extend the transaction whose event triggered the callback.

Deterministic publication order

Within an Instant Effect, changed-attribute events follow authored modifier order, changed-tag events follow authored tag order, and the complete Instant Effect event follows them. No-op attribute writes do not emit a changed-value event.

Within an ability commit, buffered attribute events are released first, then counted-tag events, then Persistent Effect application/removal/stack/pulse events, followed by ability activation and committed-lifecycle events. This order describes observation after state is complete; it is not the order in which consumers should recreate gameplay state.

The world coordinator processes Entity State Restores → Attribute Snapshot Restores → Attribute Changes → Gameplay Tag Changes → Instant Effects → Persistent Effects → Projectile Impacts → Damage → Death Handling → Ability Lifecycles → Ability Requests. Requests are FIFO inside each queue. Each request is its own transaction, so a later request observes earlier successful commits. Snapshot attribute events precede restore completion, and a same-tick raw change observes the restored base state. The deterministic gameplay ordering contract defines same-boundary restore, projectile, pulse, expiration, cancellation, lifecycle, and death precedence.

Actor adapters

A represented Actor resolves to its current Mass entity and uses the same Mass transaction as the entity-handle API. An ordinary Actor receiver is project-owned code called through the receiver interface/component. Mass Forge can report acceptance or rejection, but it cannot snapshot or roll back arbitrary Actor, Blueprint, inventory, animation, or external-system state. Combine cross-system state only in a project coordinator with an explicit compensation or authoritative commit design.

Verification contract

The automation suite proves:

• an invalid modifier or tag operation leaves a multi-attribute Instant Effect unchanged and publishes no provisional events;
• the first direct attribute listener sees all attributes in the completed Instant Effect;
• an ability listener sees source cost, every target attribute, and committed lifecycle state together;
• late ability failure restores source/target attributes, tags, persistent effects, cooldowns, shared cooldowns, charges, and provisional events;
• callback-enqueued work waits for a later coordinator tick;
• callback cancellation/replacement cannot let an old lifecycle frame mutate the replacement;
• two queued operations against one target commit independently in FIFO order.

Treat a change to any boundary above as a public behavioral change: update tests, this guide, the relevant system guide, the changelog, and the versioning decision together.