Targeting (Auto-Attack + Selected Target)

Enrolls entities as auto-attackers and, on a cadence, drives each to acquire a target and attack. Attach any entity explicitly (turret / pet / specific NPC), or set AutoAttachPlayers to auto-enroll players. Detach is automatic on entity removal. The mechanism is genre-neutral; WHO is hostile and WHAT an attack does are seams (ITargetHostility / IAttackAction).

• bool Attach(long entityId)

  Enrolls an entity as an attacker (idempotent).

• int Count { get; }

  Number of live attackers (diagnostics).

• bool Detach(long entityId)

  Stops driving an entity.

WHO each entity has SELECTED — the server-authoritative answer that did not exist (GAP-09). The gap this closes. A game could only carry a target id inside AbilityRequest.TargetData's opaque bytes, which means the client asserts its own target and the server never knows it: range and visibility cannot be validated once in one place, a target-of-target frame is impossible, and no server-side consumer — the auto-attack driver, a threat table, an NPC brain — can read "who is this player fighting". This is the tab-target selection every MMO, RTS, sports game and card game needs, expressed generically: an id, validated, with events. Selection is NOT hostility. You select a party member to heal them and a shopkeeper to talk to them, so what may be selected is ITargetPolicy (permissive by default) and never ITargetHostility, which answers the different question of what may be auto-attacked.

• bool Clear(long actorEntityId)

  Clears an actor's selection and announces it.

• int Count { get; }

  Number of live selections (diagnostics).

• bool Select(long actorEntityId, long targetEntityId)

  Validates and stores a selection, announcing it to the actor (and to observers when RevealTargets is on).

• event Action<long, long> SelectionChanged

  Raised as (actor, target) whenever a selection changes, with 0 for cleared. The seam every server-side consumer reads: the auto-attack driver's SelectedTargetSelector, an NPC brain, a threat feed, an ability resolver.

• bool TryGetTarget(long actorEntityId, out long targetEntityId)

  The entity an actor currently has selected.

Targeting tuning — defaults live here, never inline in the service (rule 4).

• bool AutoAttachPlayers { get; set; }

  When true, every player entity is auto-enrolled as an attacker on world entry (the survivors-like / auto-shooter default). When false, the game enrolls attackers explicitly via Attach (turrets, sentries, specific NPCs, pets).

• float ConeDegrees { get; set; }

  Firing arc, degrees. 360 = all directions (the attacker can hit any target around it — the auto-shooter default); < 360 = only targets within this cone of the attacker's facing (turrets, directional weapons).

• double CooldownSeconds { get; set; }

  Seconds between attacks per attacker — the global fire rate.

• ushort CooldownStatId { get; set; }

  Per-attacker fire-rate stat (0 = use the global CooldownSeconds). When set, the attacker's value of this stat is its cooldown in seconds — so per-weapon fire rates and fire-rate upgrades ride the ordinary Stats wire (a Hosting bridge reads it via IAttackCadenceProvider). Mirrors AbilityDefinition.CooldownStatId.

• bool ExcludeNonCombatants { get; set; }

  Exclude the framework's own transient NON-COMBATANT entity classes — in-flight projectiles and loot pickups — from being valid targets, so stock auto-fire never shoots a bolt or a dropped coin. Enforced by the Hosting composition when Loot/Projectiles are present; a game's ITargetHostility then only expresses real faction/team rules. Default true (the sensible default); set false to restore the classic "any un-owned entity is a target" behavior.

• int MaxUpdatesPerTick { get; set; }

  Cap on attacker evaluations per server tick — a crowd of attackers degrades re-acquisition rate instead of the tick (rule 11: unbounded work gets a budget).

• float Range { get; set; }

  Acquisition range, world units.

Tuning for the player-facing SELECTED TARGET (GAP-09) — separate from TargetingOptions because the two are unrelated: that one tunes the auto-attack driver's acquisition, this one tunes what a client is allowed to select. Defaults live here, never inline (rule 4).

• bool AllowSelfTarget { get; set; }

  Whether selecting the actor itself is allowed. Default true — self-target is how a heal, a buff, or a "inspect me" verb is addressed in most games; a game where it is meaningless can refuse it here instead of writing a policy.

• bool DriveAutoAttack { get; set; }

  Whether the auto-attack driver attacks the SELECTED target in preference to the one it would acquire on its own (SelectedTargetSelector). The tab-target shape: click a mob and your swings land on it. The selection still has to be hostile and in range, so it never turns into "attack your own healer", and automatic acquisition remains the fallback. Default false, because an auto-shooter wants nearest-first regardless of what the player has clicked.

• bool Enabled { get; set; }

  Whether the selected-target wire is served at all. Off = the piece stays the zero-wire auto-attack driver it has always been, and nothing is registered.

• float MaxRange { get; set; }

  Furthest a target may be selected, world units. 0 = no extra limit, i.e. anything the actor can SEE (its interest set) may be selected — which is the right default, because interest radius is already the game's "what exists for you" answer and a second radius that disagrees with it just makes nameplates unclickable.

• int MaxRevalidationsPerTick { get; set; }

  Cap on stored selections revalidated per server tick. A target that dies or despawns is cleared immediately by the world event; this sweep catches the slower cases (walked out of range, changed zone), so degrading it under load costs latency, never correctness (rule 11).

• bool RevealTargets { get; set; }

  Whether an actor's target is broadcast to the entities that can see it (target-of-target frames, "the boss is looking at the healer" tells). Default false: who you have selected is information, and leaking it is a competitive disadvantage a shooter or a card game must opt into rather than discover. The ACTOR is always told its own target regardless.

The selected target, client side. Ask to select an entity; the SERVER decides and answers, and MyTarget only ever holds what it accepted — so a click on something out of view, out of range, or refused by the game's policy simply does not take, and a target that dies or walks away clears itself without the client having to notice. The piece carries no presentation: subscribe to MyTargetChanged and drive your own target frame, nameplate highlight, or selection ring. When the server reveals targets, TargetOf answers for any visible entity too — that is the target-of-target frame. Remove this package and selection simply stops; nothing else breaks.

• long MyTarget

  The entity this client currently has selected, or 0 for none.

• event Action<long> MyTargetChanged

  Raised with the newly selected entity (0 = cleared) whenever the SERVER's answer changes — including when it clears the target because it died, left view, or changed zone.

• event Action<long, long> TargetRevealed

  Raised as (actor, target) for any entity whose selection the server revealed. Silent unless the game turned TargetSelection:RevealTargets on.

• long TargetOf(long entityId)

  The last known target of any entity (0 when unknown or none) — target-of-target.

• void Select(long entityId)

  Asks the server to select an entity. Optimistic UI is deliberately NOT applied: MyTarget changes when the answer arrives, so what you draw is always what the server agreed to.

• void Clear()

  Asks the server to clear the selection (always accepted).