Ability target selection

Mass Forge separates target selection from target validation. Selection adapters produce stale-safe Mass entity handles; an Ability Data Asset's targeting policies, tags, requirements, cooldowns, and costs decide whether a chosen pair can activate.

Selection answers “which candidates?” while a Targeting Policy and Can Activate answer “is this source-target pair allowed now?” Keeping those stages separate lets player input, AI, and area effects reuse the same authored gameplay rules.

All built-in outputs use Mass Forge Ability Target Selection. The result contains a bounded candidate array, total pre-truncation match count, truncation flag, and provider diagnostics where applicable. A candidate carries its entity handle, optional represented Actor, location, distance, and trace miss distance.

Radius selection

Use Find Mass Forge Ability Targets in Radius with:

• A valid Mass source entity.
• An explicit world-space origin and finite non-negative radius.
• A result limit from 1 to 256; 32 is the default.
• Optional XY-only distance and source exclusion.

The adapter searches entities with Unreal's standard FTransformFragment, so it works for actorless Mass entities. Results are nearest-first. Equal distances are tie-broken by entity index and serial number, making the retained set deterministic even when the output limit truncates a larger match set.

This convenience scan is linear in the number of transform-bearing entities. Use a project spatial index through the custom-provider route for frequent high-volume queries.

Trace selection

Trace for Mass Forge Ability Targets performs an actorless-capable thick line-segment query against Mass transform locations. Set the segment start/end, a perpendicular Trace Radius, and the same 1–256 result bound. Results are ordered along the segment, then by miss distance and entity identity.

This is a geometric point trace. It does not test world collision, entity radius, cover, or line of sight. For a normal Blueprint or collision-system trace, pass its Hit Result to Get Mass Forge Ability Target from Hit. That adapter resolves the hit Actor through UMassActorSubsystem and returns both its represented Mass handle and Actor. An Actor without current Mass representation is rejected explicitly.

Represented-Actor ability nodes

When both participants are represented Actors, use:

• Can Activate Mass Forge Ability from Actors
• Activate Mass Forge Ability from Actors
• Queue Mass Forge Ability Activation from Actors

The source Actor must currently represent a valid Mass entity. The target Actor may be null for a targetless ability; a supplied target must also have valid representation. After resolution, these nodes use the exact same validation, transaction, queue, and failure contracts as the entity-handle nodes. Queued requests store entity handles and revalidate them at execution time.

Ordinary player Actors that do not represent Mass entities cannot own Mass Forge abilities through these nodes. They can still affect Mass entities through the Actor-to-Entity damage and Instant Effect adapters described in the combat integration guide.

Custom C++ and Blueprint providers

Implement Mass Forge Ability Target Provider on a C++ UObject or Blueprint class when selection comes from a spatial database, formation, threat table, encounter manager, party system, or other project-owned source. Mass Forge Ability Target Provider Component is a drop-in Blueprint-spawnable host intended for one manager Actor, not every Mass entity.

The provider query supplies the world, valid source entity, optional represented source Actor, origin, trace end, radius, result limit, source-exclusion flag, and optional named scalar parameters. Return a stable provider ID, result/reason, and ordered entity handles.

Call Select Mass Forge Ability Targets with Provider rather than trusting the raw provider array. Mass Forge:

• Rejects invalid providers, cross-world provider objects, invalid requests, and recursive provider evaluation.
• Rejects unnamed provider responses.
• Removes stale or unset handles and reports their count.
• Removes duplicates and reports their count.
• Optionally removes the source entity.
• Preserves the provider's order for valid targets.
• Enforces the request's 1–256 bound and reports truncation.
• Resolves each retained candidate's Mass transform or represented-Actor location when one is available.

Provider response fields are Blueprint-writeable, so an override can construct the response directly. Providers must be deterministic and side-effect free; they should select, not activate abilities or mutate entity state.

Production flow

1. Select candidates with a radius, trace, collision hit, or custom provider.
2. Run Can Activate Mass Forge Ability for the candidate you intend to use. This reevaluates the ability's current targeting policies and gameplay rules.
3. Activate directly while Mass is idle, or enqueue the activation when the caller may overlap Mass processing.
4. Treat every handle as a snapshot reference. Selection success does not reserve the entity or guarantee it remains valid.

Selection is read-only and returns Mass Is Processing rather than racing a Mass phase. There is no queued selection path; schedule the read after Mass work or perform high-volume selection inside a project Mass processor/provider.

Mass Forge does not automatically activate an ability once per radius result. Doing so would silently choose project-specific cost, cooldown, ordering, and multi-target atomicity semantics. Area abilities should select targets, define their intended payment policy, and then apply an authored area effect or explicit project batch operation.

Looping through selected candidates is explicitly non-atomic across the list: every target receives an independent detailed result, and a later failure does not roll back earlier successful targets. See the transaction and event contract before implementing an area, chain, or project-owned all-or-nothing batch.

See TARGETING_POLICIES_GUIDE.md for reusable validation policies and DEFERRED_COMMANDS_GUIDE.md for safe activation ordering.