diff --git a/AGENTS.md b/AGENTS.md index a0c26b6..cf486de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,6 +36,7 @@ - Overlay UI state must converge from actual game state on periodic updates, not depend only on one-shot event or patch callbacks. Cloned controls must reset runtime state while retaining source styles; use `UXAssist.UI.Util.GetPreferredWidth` for dynamic text and `ResetButton` for cloned buttons. - LiveStreamAssist browser overlays must use single-flight polling and discard stale work after connection changes. Compound queries must reject mixed session IDs; cache only positive production indices so newly tracked items remain discoverable. - LiveStreamAssist production reads must schedule the native extra-info calculator for queried factories independently of the statistics UI. Deduplicate and throttle refreshes, let active native batches finish, and clear pending factory indices and deadlines at session boundaries. +- LiveStreamAssist `ReflectionReader` caches bounded per-type member metadata and clears it during API uninitialization; do not cache mutable game values or arbitrary request results. ## Automation Architecture diff --git a/LiveStreamAssist/Api/ReflectionReader.cs b/LiveStreamAssist/Api/ReflectionReader.cs index 5c975a5..11b4eae 100644 --- a/LiveStreamAssist/Api/ReflectionReader.cs +++ b/LiveStreamAssist/Api/ReflectionReader.cs @@ -527,8 +527,13 @@ internal sealed class ReflectionReader static bool IsAllowedProperty(PropertyInfo prop) { - return prop.DeclaringType == typeof(GameHistoryData) && - string.Equals(prop.Name, "currentTech", StringComparison.Ordinal); + if (prop.DeclaringType == typeof(GameHistoryData)) + return string.Equals(prop.Name, "currentTech", StringComparison.Ordinal); + + if (prop.DeclaringType == typeof(GameDesc)) + return string.Equals(prop.Name, "clusterString", StringComparison.Ordinal); + + return false; } bool IsAllowedType(Type type) diff --git a/LiveStreamAssist/docs/WebSocketApi.md b/LiveStreamAssist/docs/WebSocketApi.md index 3c89003..36d8236 100644 --- a/LiveStreamAssist/docs/WebSocketApi.md +++ b/LiveStreamAssist/docs/WebSocketApi.md @@ -285,7 +285,7 @@ Strings are literal member names, not expressions: `"history.currentTech"` is no V1 supports one-dimensional zero-based arrays, concrete BCL `List`, and concrete BCL `Dictionary` with `Int32` or string keys. String keys are not converted to integers. Other collection implementations and arbitrary `IEnumerable` enumeration are unsupported. -Fields can be public or non-public instance fields on permitted game-data types. Static fields, compiler-generated backing fields, methods, setters, and indexer properties are not exposed. Property reads require an explicit server allowlist. The initial property allowlist contains `GameHistoryData.currentTech`; other getters are not automatically allowed merely because they are public or have no setter. +Fields can be public or non-public instance fields on permitted game-data types. Static fields, compiler-generated backing fields, methods, setters, and indexer properties are not exposed. Property reads require an explicit server allowlist. The property allowlist contains `GameHistoryData.currentTech` and `GameDesc.clusterString`; other getters are not automatically allowed merely because they are public or have no setter. Use `data.describe` to discover the permitted surface. If inheritance hides a name, the most-derived declaration wins. Field/property traversal through runtime infrastructure such as Unity native objects, delegates, reflection objects, streams, or synchronization objects is unsupported. diff --git a/LiveStreamAssist/docs/WebSocketDesign.md b/LiveStreamAssist/docs/WebSocketDesign.md index 120e38a..e84c332 100644 --- a/LiveStreamAssist/docs/WebSocketDesign.md +++ b/LiveStreamAssist/docs/WebSocketDesign.md @@ -251,6 +251,7 @@ Use one resolver/member-policy path for `data.read`, `data.describe`, and projec | Declaring type | Property | Verified behavior | | --- | --- | --- | | `GameHistoryData` | `currentTech` | Public auto-property getter returning its backing value; private setter is not exposed. | + | `GameDesc` | `clusterString` | Formats the current cluster seed/address from `galaxySeed`, `starCount`, resource mode, and combat difficulty fields without mutating game state. | Additional properties require a concrete query need and inspection of the original getter and any called methods. Record the exact declaration and reason here and update the API reference before adding it. Do not allow every public getter, call a setter, or bypass a rejected getter through its compiler-generated backing field. @@ -258,7 +259,7 @@ Use one resolver/member-policy path for `data.read`, `data.describe`, and projec 6. Keep projections shallow as specified by the API. Explicit paths may follow cyclic references within the path limit, but summaries terminate output traversal. No graph serializer, persistent object handles, reference registry, or general cycle-resolution framework is needed. 7. Encode 64-bit values and other scalars before passing snapshots to JSON serialization. Use Newtonsoft.Json without automatic CLR type construction (`TypeNameHandling.None`); parse request DTO/token data only. Never use `SerializeObject` or `JToken.FromObject` on an arbitrary game object. 8. Bound serialized output while producing it, not after creating an unlimited JSON string. Bound snapshot construction too: enforce projection/page limits and reject obviously oversized strings before copying/encoding them. Metadata discovery is shallow and must not execute listed getters. -9. Cache successful type/member metadata, not requests or failed arbitrary path strings. Use a bounded cache (for example, at most 1024 entries, then stop adding entries) rather than a new eviction framework. Clear it on server uninitialization. +9. Cache successful type/member metadata, not requests or failed arbitrary path strings. Use a bounded cache (for example, at most 1024 entries, then stop adding entries) rather than a new eviction framework. Clear it on server uninitialization. `ReflectionReader` stores the resolved `FieldInfo`/`PropertyInfo` objects in this per-type cache; it must still read live member values for every request instead of caching mutable game state. Catch reflection/getter failures at the request boundary and map them to the API errors. Retain diagnostic exceptions in local logs, not response bodies. System methods and generic game-data methods must share envelope/error handling; do not introduce parallel protocol implementations. diff --git a/LiveStreamAssist/js/README.md b/LiveStreamAssist/js/README.md index 63fdd4c..be44e15 100644 --- a/LiveStreamAssist/js/README.md +++ b/LiveStreamAssist/js/README.md @@ -105,6 +105,11 @@ Pass an array of positive integer item ids to share the factory scan; duplicates - `getTechState(techId)` reads `history.techStates[techId]`. - `getCurrentResearch()` reads `history.currentTech`, then that tech's state. `techId === 0` means no active research. `progressPercent` uses integer hash math, same as the sample overlay. +### Current cluster + +- `getClusterString()` reads `game.gameDesc.clusterString`, the current Dyson Sphere Program star-cluster seed/address string. +- The result is `{ clusterString, sessionId, gameTick }`; the string is sampled on the game thread and is not cached across sessions. + ### Dyson power `getDysonPower()` sums `game.dysonSpheres[i].energyGenCurrentTick` across non-null spheres, projecting energy fields in collection pages. `getDysonPower({ starIndex })` reads only that sphere. Watts are `joulesPerTick * 60` (DSP ticks per second). `originalWatts` is the pre-Dark-Fog-debuff figure. Star display names use `overrideName` or `name` because `displayName` is a getter and is not readable through the API. Empty results retain their session metadata. diff --git a/LiveStreamAssist/js/livestream-assist.js b/LiveStreamAssist/js/livestream-assist.js index de82017..d83658b 100644 --- a/LiveStreamAssist/js/livestream-assist.js +++ b/LiveStreamAssist/js/livestream-assist.js @@ -516,6 +516,19 @@ }); }; + GameQuery.prototype.getClusterString = function () { + var self = this; + var context = {}; + return this._read({ root: "game", path: ["gameDesc", "clusterString"] }, context).then(function (result) { + self._assertSession(context); + return { + clusterString: result.value == null ? "" : String(result.value), + sessionId: result.sessionId, + gameTick: result.gameTick + }; + }); + }; + GameQuery.prototype._factoryIds = function (scope, context) { if (scope === "localPlanet") { return this._read({ root: "localPlanet", path: ["factoryIndex"] }, context).then(function (result) { diff --git a/LiveStreamAssist/js/scripts/test_query.js b/LiveStreamAssist/js/scripts/test_query.js index b908a4d..6cf2ac0 100644 --- a/LiveStreamAssist/js/scripts/test_query.js +++ b/LiveStreamAssist/js/scripts/test_query.js @@ -76,6 +76,15 @@ test("research from different saves is not combined", async () => { await assert.rejects(query.getCurrentResearch(), { kind: "SESSION_CHANGED" }); }); +test("cluster string reads the active game description", async () => { + const { query, calls } = createQuery(() => result("12345678-64-A10")); + const cluster = await query.getClusterString(); + assert.equal(cluster.clusterString, "12345678-64-A10"); + assert.equal(cluster.sessionId, "save-a"); + assert.equal(calls[0].root, "game"); + assert.equal(calls[0].path.join("."), "gameDesc.clusterString"); +}); + test("research progress keeps integer precision", async () => { const { query } = createQuery(() => result({ hashUploaded: "9007199254740993", hashNeeded: "18014398509481986", curLevel: 1 diff --git a/LiveStreamAssist/js/src/query.js b/LiveStreamAssist/js/src/query.js index 1c73487..681e15a 100644 --- a/LiveStreamAssist/js/src/query.js +++ b/LiveStreamAssist/js/src/query.js @@ -126,6 +126,19 @@ }); }; + GameQuery.prototype.getClusterString = function () { + var self = this; + var context = {}; + return this._read({ root: "game", path: ["gameDesc", "clusterString"] }, context).then(function (result) { + self._assertSession(context); + return { + clusterString: result.value == null ? "" : String(result.value), + sessionId: result.sessionId, + gameTick: result.gameTick + }; + }); + }; + GameQuery.prototype._factoryIds = function (scope, context) { if (scope === "localPlanet") { return this._read({ root: "localPlanet", path: ["factoryIndex"] }, context).then(function (result) { diff --git a/LiveStreamAssist/tools/ReflectionReaderCheck/Program.cs b/LiveStreamAssist/tools/ReflectionReaderCheck/Program.cs index 78e351a..f9c826e 100644 --- a/LiveStreamAssist/tools/ReflectionReaderCheck/Program.cs +++ b/LiveStreamAssist/tools/ReflectionReaderCheck/Program.cs @@ -20,6 +20,7 @@ static class Program { InheritedPrivateFields(reader); BlockedGetter(reader); + ClusterStringProperty(reader); NullIntermediateAndTerminal(reader); DictionaryKeys(reader); Indexes(reader); @@ -71,6 +72,13 @@ static class Program Check(!HasMember(desc, "Boom"), "blocked getter omitted from describe"); } + static void ClusterStringProperty(ReflectionReader reader) + { + var described = reader.Describe(null, typeof(GameDesc), Array.Empty()); + Check(described.Error == null && HasMember(described, "clusterString"), + "cluster string property is allowlisted"); + } + static void NullIntermediateAndTerminal(ReflectionReader reader) { var obj = new DerivedFixture();