feat: add combat target runtime snapshots

Author: MikelCalvo

internal/minimal/factory.go

@@ -307,6 +307,13 @@ func (r *gameRuntime) CharacterVisibility() []CharacterVisibilitySnapshot {
 	return r.sharedWorld.CharacterVisibility()
 }
 
+func (r *gameRuntime) CombatTargetSnapshots() []CombatTargetSnapshot {
+	if r == nil || r.sharedWorld == nil {
+		return nil
+	}
+	return r.sharedWorld.CombatTargetSnapshots()
+}
+
 func (r *gameRuntime) InteractionVisibility() []CharacterInteractionVisibilitySnapshot {
 	if r == nil || r.sharedWorld == nil {
 		return nil

internal/minimal/shared_world.go

@@ -697,6 +697,38 @@ func (r *sharedWorldRegistry) CombatTargetSnapshot(entityID uint64) (CombatTarge
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
+	return r.combatTargetSnapshotLocked(entityID)
+}
+
+func (r *sharedWorldRegistry) CombatTargetSnapshots() []CombatTargetSnapshot {
+	if r == nil {
+		return nil
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if len(r.sessionCombatTargets) == 0 {
+		return nil
+	}
+	entityIDs := make([]uint64, 0, len(r.sessionCombatTargets))
+	for entityID := range r.sessionCombatTargets {
+		entityIDs = append(entityIDs, entityID)
+	}
+	sort.Slice(entityIDs, func(i, j int) bool { return entityIDs[i] < entityIDs[j] })
+
+	snapshots := make([]CombatTargetSnapshot, 0, len(entityIDs))
+	for _, entityID := range entityIDs {
+		snapshot, ok := r.combatTargetSnapshotLocked(entityID)
+		if !ok {
+			continue
+		}
+		snapshots = append(snapshots, snapshot)
+	}
+	return snapshots
+}
+
+func (r *sharedWorldRegistry) combatTargetSnapshotLocked(entityID uint64) (CombatTargetSnapshot, bool) {
 	targetVID, ok := r.sessionCombatTargets[entityID]
 	if !ok || targetVID == 0 {
 		return CombatTargetSnapshot{}, false

internal/minimal/shared_world_test.go

@@ -15629,6 +15629,76 @@ func TestSharedWorldRegistryCombatTargetSnapshotReportsSelectedPracticeMob(t *te
 	}
 }
 
+func TestSharedWorldRegistryCombatTargetSnapshotsReportsDeterministicActiveSelections(t *testing.T) {
+	topology := worldruntime.NewBootstrapTopology(1).WithRadiusVisibilityPolicy(400, 200)
+	registry := newSharedWorldRegistryWithTopology(topology)
+	firstSubject := peerVisibilityCharacter("FirstSubject", 0x01030101, 0x02040101, 1100, 2100, 0, 101, 201)
+	secondSubject := peerVisibilityCharacter("SecondSubject", 0x01030102, 0x02040102, 1110, 2110, 1, 101, 201)
+	firstSubjectID, _ := registry.Join(firstSubject, newPendingServerFrames(), nil)
+	secondSubjectID, _ := registry.Join(secondSubject, newPendingServerFrames(), nil)
+	if firstSubjectID == 0 || secondSubjectID == 0 {
+		t.Fatalf("expected both subjects to join, got first=%d second=%d", firstSubjectID, secondSubjectID)
+	}
+	firstActor, ok := registry.RegisterStaticActorWithCombatKind(0, "FirstPracticeMob", bootstrapMapIndex, 1200, 2200, 20350, worldruntime.StaticActorCombatProfilePracticeMob)
+	if !ok {
+		t.Fatal("expected first practice-mob registration to succeed")
+	}
+	secondActor, ok := registry.RegisterStaticActorWithCombatKind(0, "SecondPracticeMob", bootstrapMapIndex, 1210, 2210, 20351, worldruntime.StaticActorCombatProfilePracticeMob)
+	if !ok {
+		t.Fatal("expected second practice-mob registration to succeed")
+	}
+	secondAttempt := registry.AttemptStaticActorCombatTarget(secondSubjectID, uint32(secondActor.EntityID))
+	if !secondAttempt.Accepted || !registry.SetSessionCombatTarget(secondSubjectID, secondAttempt.TargetVID) {
+		t.Fatalf("expected second subject target selection to be recorded, got %+v", secondAttempt)
+	}
+	firstAttempt := registry.AttemptStaticActorCombatTarget(firstSubjectID, uint32(firstActor.EntityID))
+	if !firstAttempt.Accepted || !registry.SetSessionCombatTarget(firstSubjectID, firstAttempt.TargetVID) {
+		t.Fatalf("expected first subject target selection to be recorded, got %+v", firstAttempt)
+	}
+
+	snapshots := registry.CombatTargetSnapshots()
+	if len(snapshots) != 2 {
+		t.Fatalf("expected two active combat target snapshots, got %d: %+v", len(snapshots), snapshots)
+	}
+	if snapshots[0].SubjectEntityID != firstSubjectID || snapshots[0].TargetVID != uint32(firstActor.EntityID) {
+		t.Fatalf("expected first deterministic snapshot to describe first subject/actor, got %+v", snapshots[0])
+	}
+	if snapshots[1].SubjectEntityID != secondSubjectID || snapshots[1].TargetVID != uint32(secondActor.EntityID) {
+		t.Fatalf("expected second deterministic snapshot to describe second subject/actor, got %+v", snapshots[1])
+	}
+	if snapshots[0].Actor.Name != "FirstPracticeMob" || snapshots[1].Actor.Name != "SecondPracticeMob" {
+		t.Fatalf("unexpected active combat target actors: %+v", snapshots)
+	}
+}
+
+func TestGameRuntimeCombatTargetSnapshotsReportsActiveSelections(t *testing.T) {
+	store := loginticket.NewFileStore(t.TempDir())
+	attacker := peerVisibilityCharacter("SnapshotAttacker", 0x01030103, 0x02040103, 1100, 2100, 0, 101, 201)
+	issuePeerTicket(t, store, "snapshot-attacker", 0x33333333, attacker)
+	runtime, err := newGameRuntimeWithAccountStore(config.Service{LegacyAddr: ":13000", PublicAddr: "127.0.0.1"}, store, nil)
+	if err != nil {
+		t.Fatalf("unexpected game runtime error: %v", err)
+	}
+	actor, ok := runtime.sharedWorld.RegisterStaticActorWithCombatKind(0, "SnapshotPracticeMob", bootstrapMapIndex, 1200, 2200, 20350, worldruntime.StaticActorCombatProfilePracticeMob)
+	if !ok {
+		t.Fatal("expected practice-mob registration to succeed")
+	}
+	flow, _ := enterGameWithLoginTicket(t, runtime.SessionFactory(), "snapshot-attacker", 0x33333333)
+	defer closeSessionFlow(t, flow)
+	targetVID := uint32(actor.EntityID)
+	if selectOut, err := flow.HandleClientFrame(decodeSingleFrame(t, combatproto.EncodeClientTarget(combatproto.ClientTargetPacket{TargetVID: targetVID}))); err != nil || len(selectOut) != 1 {
+		t.Fatalf("expected target selection before runtime snapshot to succeed with one frame, got frames=%d err=%v", len(selectOut), err)
+	}
+
+	snapshots := runtime.CombatTargetSnapshots()
+	if len(snapshots) != 1 {
+		t.Fatalf("expected one runtime combat target snapshot, got %d: %+v", len(snapshots), snapshots)
+	}
+	if snapshots[0].TargetVID != targetVID || snapshots[0].HPPercent != 100 || snapshots[0].Actor.Name != "SnapshotPracticeMob" {
+		t.Fatalf("unexpected runtime combat target snapshot: %+v", snapshots[0])
+	}
+}
+
 func TestSharedWorldRegistryRegisterSpawnGroupActorWithPracticeMobProfileIsCombatTargetable(t *testing.T) {
 	topology := worldruntime.NewBootstrapTopology(1).WithRadiusVisibilityPolicy(400, 200)
 	registry := newSharedWorldRegistryWithTopology(topology)

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

@@ -124,17 +124,18 @@ So the first owned target-state surface is now intentionally tiny but expressive
 
 ## 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.
+The runtime now also owns read-only selected-combat-target snapshots for local/debug callers.
+They are not new client packets and do 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:
+For a live shared-world session with an active selected static-actor combat target, each 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.
+The per-subject 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.
+The aggregate runtime snapshot skips those invalid/stale entries and returns active selections in deterministic `subject_entity_id` order.
 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