Combat and cross-ownership effect guide

Mass Forge provides two complementary layers: project-authored Instant Effects for direct state changes, and reusable Damage Definitions for common deterministic combat formulas against Mass entities. Neither layer hard-codes an attribute name, player class, or despawn implementation.

This guide covers the four Blueprint dispatch nodes that connect Mass entities and ordinary Actors without project-specific casts.

Before dispatching

For a Mass target:

1. Define the target attribute in a Mass Forge schema. Vital.Health is a common example, not a required name.
2. Add Mass Forge Attributes Trait to the target Entity Config.
3. Create a Mass Forge Instant Effect and add the desired attribute or Gameplay Tag modifiers.

For an ordinary Actor target such as a player:

1. Add Mass Forge Effect Receiver Component to the Actor or implement Mass Forge Effect Receiver directly on the Actor.
2. Bind the component's On Effect Received event.
3. Translate the generic effect and context into the Actor's project-owned health, GAS, inventory, or other system.

The stock receiver component is an adapter, not a second attribute store. Its Accept Effects switch can reject incoming effects temporarily. A direct Actor interface implementation is useful when acceptance needs custom synchronous logic.

Choosing the node

Source	Target	Blueprint node
Mass entity	Mass entity	Apply Mass Forge Entity-to-Entity Effect
Actor/player	Mass entity	Apply Mass Forge Actor-to-Entity Effect
Mass entity	Actor/player	Apply Mass Forge Entity-to-Actor Effect
Actor/player	Actor/player	Apply Mass Forge Actor-to-Actor Effect

The entity nodes work for actorless and represented entities. The Actor nodes accept ordinary Actors and represented Mass Actors. A represented Actor target is automatically routed to its Mass entity before any Actor receiver is considered.

Each node accepts an optional Context advanced pin. Set Source Id to a weapon, hazard, ability, or other stable logical identity. Add Origin, optional hit data, and custom scalar Parameters when needed. Mass Forge resolves source and target identities and stamps the selected effect identity while preserving the authored payload.

Dispatch precedence

An Actor target is resolved in this order:

1. represented Mass entity;
2. receiver interface implemented directly by the Actor;
3. exactly one Actor Component implementing the receiver interface.

This order prevents a represented entity from receiving the same effect twice. If an Actor has multiple receiver components, dispatch returns Multiple Receiver Components rather than guessing or double-applying. An Actor with no supported route returns Unsupported Target.

Reading the receipt

Every cross-ownership node returns a Mass Forge Effect Dispatch Receipt:

• Result reports routing success or the exact routing failure;
• Route identifies Mass Entity, Actor Interface, or Component Interface;
• Resolved Source Entity is populated for an entity source or represented Actor source;
• Resolved Entity is the resolved target entity for the Mass route;
• Applied Context is the fully resolved context delivered to the selected route;
• Entity Application contains every attribute/tag result for a Mass target;
• Receiver Object identifies the Actor or Actor Component used by a receiver route.

Success means the selected route accepted and completed the immediate dispatch. Entity Application Failed means routing succeeded but the Mass effect transaction failed; inspect Entity Application.Result and its detailed fields. Receiver Rejected means the ordinary Actor adapter deliberately declined the effect.

Blueprint recipes

Actorless Mass entity damages another actorless entity

Use Apply Mass Forge Entity-to-Entity Effect with both generation-checked handles and a damage Instant Effect. The source handle is copied into Applied Context.Source Entity; no Actor is required.

Represented Mass entity damages another represented entity

Use the same entity-to-entity node. Mass Forge resolves the optional source and target Actors into the applied context, while the Mass handles remain authoritative.

Player damages an actorless entity

Use Apply Mass Forge Actor-to-Entity Effect with the player as Source Actor and the Mass handle as Target Entity. If the player also represents a Mass entity, the receipt exposes that resolved source handle automatically.

Player damages a represented Mass entity

Use Apply Mass Forge Actor-to-Actor Effect with the player and represented target Actor. The target's Mass handle is resolved and the effect runs through the atomic Mass path.

Actorless Mass entity damages a player

Add Mass Forge Effect Receiver Component to the player, bind On Effect Received, and call Apply Mass Forge Entity-to-Actor Effect. The event receives the actorless source handle, effect asset, source ID, origin, and parameters.

Represented Mass entity damages a player

Use the same entity-to-Actor node. The applied context contains both the source entity and its represented Actor when representation is currently available.

Add project-owned factions and friendly-fire rules

Mass Forge does not prescribe Team 0, Team 1, or a fixed faction hierarchy. Put your own counted Gameplay Tags on the Entity Configs, such as Faction.Player, Faction.Guard, or Faction.Monster, and choose one of these policy paths:

1. For the common same-faction rule, add Mass Forge Gameplay Tag Damage Policy Component to one world manager or Game State.
2. Populate Faction Tags with the exact tags your project owns.
3. Leave Auto Register enabled. When two Mass endpoints share one configured tag, the component returns Deny with policy ID GameplayTagFriendlyFire and reason SharedFaction.
4. Actor-only sources and entities without a configured faction make the component Abstain, allowing later project policies to decide.

For alliances, ownership, safe zones, PvP flags, or asymmetric rules, subclass Mass Forge Damage Policy Component in Blueprint and override Evaluate Mass Forge Damage Policy. Read the resolved source/target handles and return Deny, Allow, or Abstain. A denial is visible in Mass Forge Damage Application Result through Blocking Policy Id, Blocking Policy Reason, and Evaluated Policy Count.

The shipped Battle Simulator makes the reusable path inspectable: its arena root carries FactionDamagePolicy, configured with the sample Mint and Berry tags. Replace those sample tags with project-owned tags rather than adopting the sample taxonomy.

Safety and ownership boundaries

• Entity handles are validated by index and serial number. Stale sources return Invalid Source; stale targets return Invalid Target.
• Actors must belong to the same world as the call. Cross-world endpoints are rejected.
• The four convenience nodes are immediate operations. If a Mass entity call may overlap Mass processing, use the existing queued entity Instant Effect node and provide the same context; completion is reported by request ID.
• Receiver events are synchronous and run on the caller's game-thread path. Keep them bounded and avoid recursively dispatching the same effect.
• Damage Definitions provide opt-in mitigation, critical, shield, tag-gate, self-damage, minimum-damage, and first-death policies for Mass targets. Post-death handling can keep the entity, request project-managed deactivation, or queue Mass-entity destruction. Mass Forge supplies the policy extension point and a configurable tag-based friendly-fire component; the actual faction tags, alliances, ownership, represented-Actor lifecycle, and presentation remain project integrations.

Verification

MassForge.Effects.CrossOwnershipDispatch creates real Mass entities, real representation mappings, ordinary Actors, and the receiver component in an isolated world. It verifies all six recipes above plus disabled receivers, duplicate receiver components, invalid sources, invalid targets, resolved routes, and applied source/target context. MassForge.Damage.DeterministicPolicyAndAtomicCommit verifies configurable shared-faction denial, opposing-faction damage, stable policy diagnostics, registration bounds, and atomic health behavior.

For effect authoring, atomicity, parameters, and attribute-backed magnitudes, continue with the Instant Effects guide.

For the configurable damage formula and Blueprint nodes, continue with the Damage system guide.