From 6439809c7e1df07b230942972a2cc5e10d36c498 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Mon, 29 Jun 2026 04:37:22 +0100 Subject: [PATCH] Scope managed client document selectors --- Aetheria.State.Verify/Program.cs | 59 ++++++++++------ .../Tests/DaemonRuntimeDocumentTests.cs | 10 +-- Assets/Scripts/UI/Menu/InventoryMenu.cs | 2 +- Assets/Scripts/UI/Menu/InventoryPanel.cs | 2 +- Assets/Scripts/UI/Menu/SectorRenderer.cs | 2 +- .../Runtime/AetheriaClientState.cs | 68 ++++++++++++++++--- 6 files changed, 104 insertions(+), 39 deletions(-) diff --git a/Aetheria.State.Verify/Program.cs b/Aetheria.State.Verify/Program.cs index 6518c5783..209e65a49 100644 --- a/Aetheria.State.Verify/Program.cs +++ b/Aetheria.State.Verify/Program.cs @@ -4559,7 +4559,7 @@ static void RequireSectorMapZoneDetailsUseEveSurface(string root) "AetheriaUnityRuntimeClientProvider.ResolveClient(", ".State", ".Reactive()", - ".State.Reactive(zoneIndex)", + ".State.Reactive(AetheriaClientState.Zone(zoneIndex))", "_zoneDetails?.Current", "AetheriaClient", "AetheriaRuntimeZoneDetailsSurfaceCommands.TryRead(request, out var command)", @@ -4598,7 +4598,7 @@ static void RequireSectorMapZoneDetailsUseEveSurface(string root) "SectorRenderer", "AetheriaRuntimeZoneDetailsDocument", "_zoneDetails", - ".Reactive(zoneIndex)", + ".Reactive(AetheriaClientState.Zone(zoneIndex))", "AetheriaRuntimeZoneDetailsSession", ".ObserveZone(zoneIndex)"); RequireReactiveTypedDocumentAccess( @@ -7051,12 +7051,16 @@ static void RequireInventoryValidationUsesManagedTypedDocuments(string root) var clientState = File.ReadAllText(clientStatePath); if (!clientState.Contains("public CultMeshDocumentHandle Document()", StringComparison.Ordinal) || - !clientState.Contains("public CultMeshDocumentHandle Document(int entityOrZoneIndex)", StringComparison.Ordinal) || + !clientState.Contains("public static AetheriaClientZone Zone(int zoneIndex)", StringComparison.Ordinal) || + !clientState.Contains("public static AetheriaClientEntity Entity(int entityIndex)", StringComparison.Ordinal) || + !clientState.Contains("public CultMeshDocumentHandle Document(AetheriaClientZone zone)", StringComparison.Ordinal) || + !clientState.Contains("public CultMeshDocumentHandle Document(AetheriaClientEntity entity)", StringComparison.Ordinal) || !clientState.Contains("public CultMeshReactiveDocument Reactive(", StringComparison.Ordinal) || - !clientState.Contains("public CultMeshReactiveDocument Reactive(int entityOrZoneIndex)", StringComparison.Ordinal)) + !clientState.Contains("public CultMeshReactiveDocument Reactive(AetheriaClientZone zone)", StringComparison.Ordinal) || + !clientState.Contains("public CultMeshReactiveDocument Reactive(AetheriaClientEntity entity)", StringComparison.Ordinal)) { throw new InvalidOperationException( - "AetheriaClientState must expose native typed document handles and native reactive typed documents for current entity, station refit, and indexed inventory documents."); + "AetheriaClientState must expose native typed document handles and native reactive typed documents for current entity, station refit, and explicitly scoped inventory/zone documents."); } var sources = new Dictionary @@ -7081,7 +7085,7 @@ static void RequireInventoryValidationUsesManagedTypedDocuments(string root) { ".Reactive()", ".Reactive()", - ".Reactive(entityIndex)" + ".Reactive(AetheriaClientState.Entity(entityIndex))" }; missingSymbols = missingSymbols .Concat(requiredCompactedSymbols.Where(symbol => !compact.Contains(symbol, StringComparison.Ordinal))) @@ -7140,7 +7144,7 @@ static void RequireInventoryValidationUsesManagedTypedDocuments(string root) name, "AetheriaRuntimeInventoryDocument", "_inventory", - ".Reactive(entityIndex)", + ".Reactive(AetheriaClientState.Entity(entityIndex))", "AetheriaRuntimeInventorySession", ".ObserveInventory(entityIndex)"); } @@ -7338,7 +7342,8 @@ static void RequireUnitySharedDocumentAccessorErgonomics(string root) var requiredClientSymbols = new[] { "public CultMeshDocumentHandle Document()", - "public CultMeshDocumentHandle Document(int entityOrZoneIndex)" + "public CultMeshDocumentHandle Document(AetheriaClientZone zone)", + "public CultMeshDocumentHandle Document(AetheriaClientEntity entity)" }; var missingClientSymbols = requiredClientSymbols .Where(symbol => !clientState.Contains(symbol, StringComparison.Ordinal)) @@ -7353,10 +7358,12 @@ static void RequireUnitySharedDocumentAccessorErgonomics(string root) if (clientState.Contains("public Task LatestAsync", StringComparison.Ordinal) || clientState.Contains("public TDocument Latest", StringComparison.Ordinal) || clientState.Contains("public Task> ReactiveAsync", StringComparison.Ordinal) || - clientState.Contains("public Observable Watch", StringComparison.Ordinal)) + clientState.Contains("public Observable Watch", StringComparison.Ordinal) || + clientState.Contains("public CultMeshDocumentHandle Document(int ", StringComparison.Ordinal) || + clientState.Contains("public CultMeshReactiveDocument Reactive(int ", StringComparison.Ordinal)) { throw new InvalidOperationException( - "AetheriaClientState must not expose latest/watch/session wrappers; callers should hold native Document() handles or native Reactive() documents."); + "AetheriaClientState must not expose latest/watch/session wrappers or ambiguous raw-index document access; callers should hold native typed documents scoped by explicit selectors."); } var unityPaths = new[] @@ -7831,7 +7838,7 @@ static void RequireUnitySharedDocumentAccessorErgonomics(string root) { ".Reactive()", ".Reactive()", - ".Reactive(zoneIndex)" + ".Reactive(AetheriaClientState.Zone(zoneIndex))" }.Where(symbol => !compactSectorRenderer.Contains(symbol, StringComparison.Ordinal))) .ToArray(); if (missingSectorRendererSharedDocumentSymbols.Length > 0) @@ -7862,7 +7869,7 @@ static void RequireUnitySharedDocumentAccessorErgonomics(string root) "SectorRenderer", "AetheriaRuntimeZoneDetailsDocument", "_zoneDetails", - ".Reactive(zoneIndex)", + ".Reactive(AetheriaClientState.Zone(zoneIndex))", "AetheriaRuntimeZoneDetailsSession", ".ObserveZone(zoneIndex)"); RequireReactiveTypedDocumentAccess( @@ -7975,7 +7982,8 @@ static void RequireUnityViewportAndMapReadsUseManagedAccessors(string root) { "public CultMeshDocumentHandle Document()", "public CultMeshDocumentHandle Document(AetheriaRuntimeRtsViewportBounds viewport)", - "public CultMeshDocumentHandle Document(int entityOrZoneIndex)" + "public CultMeshDocumentHandle Document(AetheriaClientZone zone)", + "public CultMeshDocumentHandle Document(AetheriaClientEntity entity)" }; var missingClientSymbols = requiredClientSymbols .Where(symbol => !clientState.Contains(symbol, StringComparison.Ordinal)) @@ -8185,12 +8193,14 @@ static void RequireAetheriaManagedStateAccessorsCoverDomainDocuments(string root "public enum AetheriaClientEveSurface", "public CultMeshDocumentHandle Document(AetheriaClientEveSurface surface)", "public CultMeshDocumentHandle Document(AetheriaRuntimeRtsViewportBounds viewport)", - "public CultMeshDocumentHandle Document(int entityOrZoneIndex)", + "public CultMeshDocumentHandle Document(AetheriaClientZone zone)", + "public CultMeshDocumentHandle Document(AetheriaClientEntity entity)", "public CultMeshDocumentHandle Document(string seatId)", "public CultMeshReactiveDocument Reactive()", "public CultMeshReactiveDocument Reactive(AetheriaClientEveSurface surface)", "public CultMeshReactiveDocument Reactive(AetheriaRuntimeRtsViewportBounds viewport)", - "public CultMeshReactiveDocument Reactive(int entityOrZoneIndex)", + "public CultMeshReactiveDocument Reactive(AetheriaClientZone zone)", + "public CultMeshReactiveDocument Reactive(AetheriaClientEntity entity)", "public CultMeshReactiveDocument Reactive(string seatId)" }; var missingClientSymbols = requiredClientSymbols @@ -8206,10 +8216,12 @@ static void RequireAetheriaManagedStateAccessorsCoverDomainDocuments(string root if (clientState.Contains("public Task LatestAsync", StringComparison.Ordinal) || clientState.Contains("public TDocument Latest", StringComparison.Ordinal) || clientState.Contains("public Task> ReactiveAsync", StringComparison.Ordinal) || - clientState.Contains("public Observable Watch", StringComparison.Ordinal)) + clientState.Contains("public Observable Watch", StringComparison.Ordinal) || + clientState.Contains("public CultMeshDocumentHandle Document(int ", StringComparison.Ordinal) || + clientState.Contains("public CultMeshReactiveDocument Reactive(int ", StringComparison.Ordinal)) { throw new InvalidOperationException( - "AetheriaClientState must not reintroduce generic latest/watch shortcuts; callers should sample native typed document handles or native reactive typed documents."); + "AetheriaClientState must not reintroduce generic latest/watch shortcuts or ambiguous raw-index access; callers should sample native typed document handles scoped by explicit selectors."); } var forbiddenFixedReactiveWrappers = new[] @@ -8395,7 +8407,7 @@ static void RequireAetheriaManagedStateAccessorsCoverDomainDocuments(string root if (survivingDetailConvenienceWrappers.Length > 0) { throw new InvalidOperationException( - "AetheriaClientState must use generic indexed document access instead of named latest/reactive wrappers: " + + "AetheriaClientState must use generic scoped document access instead of named latest/reactive wrappers: " + string.Join(", ", survivingDetailConvenienceWrappers)); } @@ -14493,7 +14505,7 @@ static void RequireUnityObserverDoesNotTickLocalSimulation(string root) !compactMapRenderer.Contains(".State.Reactive()", StringComparison.Ordinal) || !sectorRenderer.Contains("AetheriaUnityRuntimeClientProvider.ResolveClient(", StringComparison.Ordinal) || !compactSectorRenderer.Contains(".State.Reactive()", StringComparison.Ordinal) || - !compactSectorRenderer.Contains(".State.Reactive(zoneIndex)", StringComparison.Ordinal) || + !compactSectorRenderer.Contains(".State.Reactive(AetheriaClientState.Zone(zoneIndex))", StringComparison.Ordinal) || !sectorRenderer.Contains(".Current", StringComparison.Ordinal) || !compactSectorRenderer.Contains("ResolveClient().State.Reactive()", StringComparison.Ordinal) || !compactSectorRenderer.Contains(".State.Reactive()", StringComparison.Ordinal) || @@ -16268,7 +16280,8 @@ static void RequireRuntimeStateReaderOwnsUnityStateAcquisition(string root) "public CultMeshDocumentHandle Document()", "public CultMeshDocumentHandle Document(AetheriaClientEveSurface surface)", "public CultMeshDocumentHandle Document(AetheriaRuntimeRtsViewportBounds viewport)", - "public CultMeshDocumentHandle Document(int entityOrZoneIndex)", + "public CultMeshDocumentHandle Document(AetheriaClientZone zone)", + "public CultMeshDocumentHandle Document(AetheriaClientEntity entity)", "public CultMeshDocumentHandle Document(string seatId)" }; var missingManagedStateAccessSymbols = requiredManagedStateAccessSymbols @@ -16285,11 +16298,13 @@ static void RequireRuntimeStateReaderOwnsUnityStateAcquisition(string root) aetheriaClientState.Contains("public TDocument Latest", StringComparison.Ordinal) || aetheriaClientState.Contains("public Observable Watch", StringComparison.Ordinal) || aetheriaClientState.Contains("public Task> ReactiveAsync", StringComparison.Ordinal) || + aetheriaClientState.Contains("public CultMeshDocumentHandle Document(int ", StringComparison.Ordinal) || + aetheriaClientState.Contains("public CultMeshReactiveDocument Reactive(int ", StringComparison.Ordinal) || aetheriaClientState.Contains("DocumentBySchema(", StringComparison.Ordinal) || aetheriaClientState.Contains("TryGetDocumentBySchema(", StringComparison.Ordinal)) { throw new InvalidOperationException( - "AetheriaClientState still exposes generic latest/watch or schema-string shortcuts instead of direct typed CultMesh document handles."); + "AetheriaClientState still exposes generic latest/watch, raw-index, or schema-string shortcuts instead of direct typed CultMesh document handles."); } if (aetheriaClientState.Contains("public AetheriaRuntimeDaemonRenderView? CurrentObservedDaemon(", StringComparison.Ordinal) || @@ -17446,7 +17461,7 @@ static void RequireInventoryDoubleClickTransferRequestAuthority(string root) "TryResolveTypedInventoryRows(", "TryValidateTypedCargoSlot(", "TryValidateTypedEquipmentSlot(", - ".State.Reactive(entityIndex)", + ".State.Reactive(AetheriaClientState.Entity(entityIndex))", "origin.Cargo.TryGetValue(item, out var originPosition)", "SourceIndex == cargoIndex", "SourceIndex == equipmentIndex", diff --git a/Assets/Scripts/Tests/DaemonRuntimeDocumentTests.cs b/Assets/Scripts/Tests/DaemonRuntimeDocumentTests.cs index e9bd80a88..4476bff8e 100644 --- a/Assets/Scripts/Tests/DaemonRuntimeDocumentTests.cs +++ b/Assets/Scripts/Tests/DaemonRuntimeDocumentTests.cs @@ -189,8 +189,8 @@ public class DaemonRuntimeDocumentTests MaxY = 100 }; var objectsViewport = ReadLatest(client.State.Document(viewport)); - var zoneDetails = ReadLatest(client.State.Document(0)); - var inventory = ReadLatest(client.State.Document(0)); + var zoneDetails = ReadLatest(client.State.Document(AetheriaClientState.Zone(0))); + var inventory = ReadLatest(client.State.Document(AetheriaClientState.Entity(0))); var currentEntityFromClientType = client.State .Document() .LatestAsync() @@ -220,9 +220,9 @@ public class DaemonRuntimeDocumentTests using var currentEntityDocumentReactive = client.State.Reactive(); using var currentDockingReactive = client.State.Reactive(); using var stationRefitReactive = client.State.Reactive(); - using var zoneDetailsReactive = client.State.Reactive(0); - using var selectedObjectReactive = client.State.Reactive(0); - using var inventoryReactive = client.State.Reactive(0); + using var zoneDetailsReactive = client.State.Reactive(AetheriaClientState.Zone(0)); + using var selectedObjectReactive = client.State.Reactive(AetheriaClientState.Entity(0)); + using var inventoryReactive = client.State.Reactive(AetheriaClientState.Entity(0)); using var mapViewportReactive = client.State.Reactive(viewport); using var objectsViewportReactive = client.State.Reactive(viewport); using var gravityViewportReactive = client.State.Reactive(viewport); diff --git a/Assets/Scripts/UI/Menu/InventoryMenu.cs b/Assets/Scripts/UI/Menu/InventoryMenu.cs index b8518f58b..48bc08de8 100644 --- a/Assets/Scripts/UI/Menu/InventoryMenu.cs +++ b/Assets/Scripts/UI/Menu/InventoryMenu.cs @@ -1001,7 +1001,7 @@ public class InventoryMenu : MonoBehaviour try { var nextInventory = ResolveClient() - .State.Reactive(entityIndex); + .State.Reactive(AetheriaClientState.Entity(entityIndex)); _inventory?.Dispose(); _inventoryEntityIndex = entityIndex; _inventory = nextInventory; diff --git a/Assets/Scripts/UI/Menu/InventoryPanel.cs b/Assets/Scripts/UI/Menu/InventoryPanel.cs index f9e1b28e4..8e27656cc 100644 --- a/Assets/Scripts/UI/Menu/InventoryPanel.cs +++ b/Assets/Scripts/UI/Menu/InventoryPanel.cs @@ -1565,7 +1565,7 @@ private void Update() try { var nextInventory = ResolveClient() - .State.Reactive(entityIndex); + .State.Reactive(AetheriaClientState.Entity(entityIndex)); _inventory?.Dispose(); _inventoryEntityIndex = entityIndex; _inventory = nextInventory; diff --git a/Assets/Scripts/UI/Menu/SectorRenderer.cs b/Assets/Scripts/UI/Menu/SectorRenderer.cs index 3deb7336b..6ccb336d4 100644 --- a/Assets/Scripts/UI/Menu/SectorRenderer.cs +++ b/Assets/Scripts/UI/Menu/SectorRenderer.cs @@ -203,7 +203,7 @@ public class SectorRenderer : MonoBehaviour, IBeginDragHandler, IDragHandler, IS try { var nextZoneDetails = ResolveClient() - .State.Reactive(zoneIndex); + .State.Reactive(AetheriaClientState.Zone(zoneIndex)); _zoneDetails?.Dispose(); _zoneDetailsIndex = zoneIndex; _zoneDetails = nextZoneDetails; diff --git a/Packages/org.gamecult.aetheria.state/Runtime/AetheriaClientState.cs b/Packages/org.gamecult.aetheria.state/Runtime/AetheriaClientState.cs index 14358a69a..1f4a54676 100644 --- a/Packages/org.gamecult.aetheria.state/Runtime/AetheriaClientState.cs +++ b/Packages/org.gamecult.aetheria.state/Runtime/AetheriaClientState.cs @@ -13,6 +13,32 @@ namespace GameCult.Aetheria.State.Verse EditorTui } + public readonly struct AetheriaClientZone + { + public AetheriaClientZone(int zoneIndex) + { + if (zoneIndex < 0) + throw new ArgumentOutOfRangeException(nameof(zoneIndex), zoneIndex, "Zone index must be non-negative."); + + ZoneIndex = zoneIndex; + } + + public int ZoneIndex { get; } + } + + public readonly struct AetheriaClientEntity + { + public AetheriaClientEntity(int entityIndex) + { + if (entityIndex < 0) + throw new ArgumentOutOfRangeException(nameof(entityIndex), entityIndex, "Entity index must be non-negative."); + + EntityIndex = entityIndex; + } + + public int EntityIndex { get; } + } + public sealed class AetheriaClientState : IDisposable { private readonly CultMeshDocumentCatalog _documents; @@ -241,24 +267,48 @@ namespace GameCult.Aetheria.State.Verse return Document(viewport).Reactive(); } - public CultMeshDocumentHandle Document(int entityOrZoneIndex) + public static AetheriaClientZone Zone(int zoneIndex) + { + return new AetheriaClientZone(zoneIndex); + } + + public static AetheriaClientEntity Entity(int entityIndex) + { + return new AetheriaClientEntity(entityIndex); + } + + public CultMeshDocumentHandle Document(AetheriaClientZone zone) where TDocument : class { if (typeof(TDocument) == typeof(AetheriaRuntimeZoneDetailsDocument)) - return (CultMeshDocumentHandle)(object)_zoneDetails(entityOrZoneIndex); - if (typeof(TDocument) == typeof(AetheriaRuntimeSelectedObjectDocument)) - return (CultMeshDocumentHandle)(object)_selectedObject(entityOrZoneIndex); - if (typeof(TDocument) == typeof(AetheriaRuntimeInventoryDocument)) - return (CultMeshDocumentHandle)(object)_inventory(entityOrZoneIndex); + return (CultMeshDocumentHandle)(object)_zoneDetails(zone.ZoneIndex); throw new NotSupportedException( - $"Aetheria typed state does not expose an indexed document for {typeof(TDocument).FullName}."); + $"Aetheria typed state does not expose a zone-scoped document for {typeof(TDocument).FullName}."); } - public CultMeshReactiveDocument Reactive(int entityOrZoneIndex) + public CultMeshReactiveDocument Reactive(AetheriaClientZone zone) where TDocument : class { - return Document(entityOrZoneIndex).Reactive(); + return Document(zone).Reactive(); + } + + public CultMeshDocumentHandle Document(AetheriaClientEntity entity) + where TDocument : class + { + if (typeof(TDocument) == typeof(AetheriaRuntimeSelectedObjectDocument)) + return (CultMeshDocumentHandle)(object)_selectedObject(entity.EntityIndex); + if (typeof(TDocument) == typeof(AetheriaRuntimeInventoryDocument)) + return (CultMeshDocumentHandle)(object)_inventory(entity.EntityIndex); + + throw new NotSupportedException( + $"Aetheria typed state does not expose an entity-scoped document for {typeof(TDocument).FullName}."); + } + + public CultMeshReactiveDocument Reactive(AetheriaClientEntity entity) + where TDocument : class + { + return Document(entity).Reactive(); } public CultMeshDocumentHandle Document(string seatId)