Gameplay tags

Mass Forge provides opt-in, counted Gameplay Tags for actorless and represented Mass entities. Projects use their normal Unreal Gameplay Tags dictionary; the plugin does not impose combat-specific tag names.

Setup

1. Define project tags under Project Settings > Gameplay Tags.
2. Add Mass Forge Gameplay Tag Trait to the Mass Entity Config.
3. Optionally place initial tags in StartingTags.
4. Use Add Mass Forge Gameplay Tag, Remove Mass Forge Gameplay Tag, or Query Mass Forge Gameplay Tag at a safe point. Use Queue Add Mass Forge Gameplay Tag or Queue Remove Mass Forge Gameplay Tag when the caller may overlap Mass processing.

The compact fragment stores at most 32 distinct exact tags per entity. Each tag has an unsigned count from 1 to 255, allowing independent systems and future effect stacks to share ownership. Adding an existing tag increments its count. Removing the final count releases the slot. Overflow, over-removal, invalid tags, missing traits, invalid entities, and full capacity return distinct result values.

Query Mass Forge Gameplay Tag returns a structured result, the exact count, and whether the requested match exists. Exact matching checks only the selected tag. Hierarchical matching also treats an owned child as matching its parent; for example, owning State.Control.Stunned satisfies a query for State.Control.

Get Owned Mass Forge Gameplay Tags enumerates every exact tag and count in stable lexical order. The same array appears in the unified entity inspection snapshot.

Successful count changes publish On Gameplay Tag Changed with entity, tag, previous count, and new count.

The two Queue nodes return a receipt immediately. Success means the bounded world queue accepted the request, not that the mutation has already happened. Keep the positive Request Id, bind On Gameplay Tag Request Completed on the Gameplay Tag Subsystem, and match the completion ID before consuming the final structured change. Rejected submissions use ID 0 and never publish a completion. Accepted requests execute FIFO, revalidate the complete entity generation, and publish the ordinary change event before their completion event.

Configure Max Queued Gameplay Tag Changes Per Frame and Max Pending Queued Gameplay Tag Changes under Project Settings > Mass Forge > Global Attribute Schemas > Runtime. Queue overflow returns Gameplay Tag Queue Full; spread or shed the burst instead of retrying in a tight loop.

Effect-granted tags

Mass Forge Instant Effect assets can add or remove counted tags alongside attribute modifiers. The plugin projects the entire effect first, so a missing tag fragment, absent tag, insufficient removal count, count overflow, or full 32-slot capacity rejects every attribute and tag change. Successful effect results include the ordered tag changes; failures expose Gameplay Tag Failure, the failed tag, and the exact tag result.

Tag-only effects are supported. This is useful for marks, immediate state transitions, cleanses, and ability self/target state changes. Ability transactions include costs and every referenced attribute/tag modifier in the same atomic boundary; failure also restores reserved cooldowns and charges. See INSTANT_EFFECTS_GUIDE.md.

Persistent lifecycle integration

Persistent Effect assets can require target tags, reject matching immunity tags, grant counted tags for exactly as long as an instance remains active, and cancel classified active effects. Independent sources contribute independent counts; expiration or removal of one instance decrements only one contribution. Refresh and extend reconcile the reused handle's grants, while replace and cancellation clean up every retired handle.

Add both the Gameplay Tag Trait and Persistent Effects Trait to participating entities. Use EffectTags to classify effects and CancelEffectsWithTags for hierarchical dispel/cleanse behavior. The persistent application result identifies requirement, blocker, and counted-tag transaction failures without partial state. See PERSISTENT_EFFECTS_GUIDE.md.

Ability gates

Every Mass Forge Ability Data Asset can configure:

• RequiredSourceTags: all must match the activating entity.
• BlockedSourceTags: any match rejects the activating entity.
• RequiredTargetTags: all must match the target.
• BlockedTargetTags: any match rejects the target.

Target tag rules automatically make a valid target mandatory. Required tags on an entity without the Gameplay Tag Trait return Missing Gameplay Tag Fragment. A missing requirement returns Missing Required Tag; a blocker returns Blocked By Tag. The activation result identifies the exact failed tag and whether it came from the source or target.

Ability tag checks happen before cooldown/charge reservation, costs, or effects, so rejection changes no state. Hierarchical matching is used, letting an ability require a broad parent category while project tags remain specific.

Safe access and current scope

Direct tag mutation and query are rejected while Mass is processing. Queue direct count changes through the dedicated Add/Remove nodes; use a queued Instant Effect when the tag change must share one atomic transaction with attributes. Persistent effects and abilities provide transactional lifecycle grants, immunity gates, and cancellation. Durable entity-state snapshots preserve exact counted tags, and the owner-only network state stream replicates their authoritative baseline. Direct local tag mutations are never silently turned into RPCs; remote players must use the owner-bound network request component.