feat: add combat target runtime snapshot

Author: MikelCalvo

internal/minimal/shared_world.go

@@ -124,6 +124,14 @@ type StaticActorCombatTargetAttempt struct {
 	Actor           StaticActorSnapshot
 }
 
+type CombatTargetSnapshot struct {
+	SubjectEntityID uint64              `json:"subject_entity_id"`
+	TargetVID       uint32              `json:"target_vid"`
+	SnapshotVersion uint64              `json:"snapshot_version"`
+	HPPercent       uint8               `json:"hp_percent"`
+	Actor           StaticActorSnapshot `json:"actor"`
+}
+
 type StaticActorCombatAttackAttempt struct {
 	Accepted                    bool
 	Failure                     string
@@ -681,6 +689,45 @@ func (r *sharedWorldRegistry) SetSessionCombatTarget(entityID uint64, targetVID
 	return true
 }
 
+func (r *sharedWorldRegistry) CombatTargetSnapshot(entityID uint64) (CombatTargetSnapshot, bool) {
+	if r == nil || entityID == 0 {
+		return CombatTargetSnapshot{}, false
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	targetVID, ok := r.sessionCombatTargets[entityID]
+	if !ok || targetVID == 0 {
+		return CombatTargetSnapshot{}, false
+	}
+	subject, ok := r.playerCharacter(entityID)
+	if !ok {
+		return CombatTargetSnapshot{}, false
+	}
+	actor, ok := r.scopesLocked().VisibleStaticActorByVID(subject, targetVID)
+	if !ok || actor.Entity.ID == 0 {
+		return CombatTargetSnapshot{}, false
+	}
+	currentHP, ok := r.ensureStaticActorCombatCurrentHPLocked(actor)
+	if !ok {
+		return CombatTargetSnapshot{}, false
+	}
+	hpPercent, ok := worldruntime.BootstrapStaticActorHPPercent(actor.CombatKind, currentHP)
+	if !ok {
+		return CombatTargetSnapshot{}, false
+	}
+	actorSnapshot := staticActorSnapshot(r.topology, actor)
+	actorSnapshot.Dead = currentHP == 0
+	return CombatTargetSnapshot{
+		SubjectEntityID: entityID,
+		TargetVID:       targetVID,
+		SnapshotVersion: r.staticActorCombatSnapshot[actor.Entity.ID],
+		HPPercent:       hpPercent,
+		Actor:           actorSnapshot,
+	}, true
+}
+
 func (r *sharedWorldRegistry) ClearSessionCombatTarget(entityID uint64) {
 	if r == nil || entityID == 0 {
 		return

internal/minimal/shared_world_test.go

@@ -15597,6 +15597,38 @@ func TestSharedWorldRegistryAttemptStaticActorCombatTargetResolvesVisiblePractic
 	}
 }
 
+func TestSharedWorldRegistryCombatTargetSnapshotReportsSelectedPracticeMob(t *testing.T) {
+	topology := worldruntime.NewBootstrapTopology(1).WithRadiusVisibilityPolicy(400, 200)
+	registry := newSharedWorldRegistryWithTopology(topology)
+	subject := peerVisibilityCharacter("Subject", 0x01030101, 0x02040101, 1100, 2100, 0, 101, 201)
+	subjectID, _ := registry.Join(subject, newPendingServerFrames(), nil)
+	if subjectID == 0 {
+		t.Fatal("expected subject join to return a live shared-world entity ID")
+	}
+	actor, ok := registry.RegisterStaticActorWithCombatKind(0, "PracticeMob", bootstrapMapIndex, 1200, 2200, 20350, worldruntime.StaticActorCombatProfilePracticeMob)
+	if !ok {
+		t.Fatal("expected visible practice-mob registration to succeed")
+	}
+	targetAttempt := registry.AttemptStaticActorCombatTarget(subjectID, uint32(actor.EntityID))
+	if !targetAttempt.Accepted {
+		t.Fatalf("expected practice-mob combat-target selection to succeed, got %+v", targetAttempt)
+	}
+	if !registry.SetSessionCombatTarget(subjectID, targetAttempt.TargetVID) {
+		t.Fatal("expected accepted target selection to be recorded")
+	}
+
+	snapshot, ok := registry.CombatTargetSnapshot(subjectID)
+	if !ok {
+		t.Fatal("expected selected combat target snapshot to be reported")
+	}
+	if snapshot.SubjectEntityID != subjectID || snapshot.TargetVID != targetAttempt.TargetVID || snapshot.SnapshotVersion != targetAttempt.SnapshotVersion || snapshot.HPPercent != targetAttempt.HPPercent {
+		t.Fatalf("unexpected selected combat target snapshot: %+v target attempt=%+v", snapshot, targetAttempt)
+	}
+	if snapshot.Actor.EntityID != actor.EntityID || snapshot.Actor.Name != "PracticeMob" || snapshot.Actor.CombatProfile != worldruntime.StaticActorCombatProfilePracticeMob {
+		t.Fatalf("unexpected selected combat target actor snapshot: %+v", snapshot.Actor)
+	}
+}
+
 func TestSharedWorldRegistryRegisterSpawnGroupActorWithPracticeMobProfileIsCombatTargetable(t *testing.T) {
 	topology := worldruntime.NewBootstrapTopology(1).WithRadiusVisibilityPolicy(400, 200)
 	registry := newSharedWorldRegistryWithTopology(topology)

spec/protocol/combat-normal-attack-bootstrap.md

@@ -35,6 +35,7 @@ This contract currently applies only to:
 - one currently visible in-range non-player actor still marked as `training_dummy`
 - one immediate attack-intent request against that already selected target
 - one tiny target-refresh surface that can still describe `current target`, `updated hp percent`, or `no active target`
+- one read-only runtime snapshot of the session's current selected combat target for local/debug surfaces
 
 This contract does **not** yet claim:
 - the full gameplay meaning of every non-zero `attack_type` value beyond the first narrow bootstrap ownership boundary
@@ -121,6 +122,21 @@ So the first owned target-state surface is now intentionally tiny but expressive
 2. `TARGET(target_vid > 0, hp_percent = updated)` — same selected dummy after accepted bootstrap attack-driven HP changes
 3. `TARGET(0, 0)` — selected target cleared or no longer valid
 
+## Runtime combat-target snapshot
+
+The runtime now also owns one read-only selected-combat-target snapshot for local/debug callers.
+It is not a new client packet and does not replace the existing self-only `GC TARGET` wire surface.
+
+For a live shared-world session with an active selected static-actor combat target, the snapshot reports:
+- `subject_entity_id`
+- `target_vid`
+- the target `snapshot_version` captured from runtime combat ownership
+- current target `hp_percent`
+- the same compact static-actor snapshot shape used by local static-actor/visibility introspection
+
+The snapshot fails closed when the subject is missing, no target is selected, the selected target is no longer visible, or the selected actor no longer has owned bootstrap combat HP semantics.
+This gives later loopback/operator surfaces a stable read-only seam without granting stale sockets or global actor lookups a new authoritative combat path.
+
 ## Relationship to later HP / death work
 
 This document freezes the first deterministic bootstrap HP mutation and the preferred visible HP-refresh carrier.