From d0c6e3030408d821d5d34835bfbdfe81d8735f37 Mon Sep 17 00:00:00 2001 From: Jonathan Bourdon Date: Tue, 7 Apr 2026 01:43:13 -0400 Subject: [PATCH] Clarify anchor-based mining model --- docs/UNIVERSE-MODEL-MIGRATION-WORKSHEET.md | 51 ++++++++++++++++++++-- docs/UNIVERSE-MODEL.md | 26 +++++++++++ 2 files changed, 74 insertions(+), 3 deletions(-) diff --git a/docs/UNIVERSE-MODEL-MIGRATION-WORKSHEET.md b/docs/UNIVERSE-MODEL-MIGRATION-WORKSHEET.md index 94be8c5..aace761 100644 --- a/docs/UNIVERSE-MODEL-MIGRATION-WORKSHEET.md +++ b/docs/UNIVERSE-MODEL-MIGRATION-WORKSHEET.md @@ -198,9 +198,10 @@ Each entry should be removed from this list when the compatibility bridge is rem | Status | Area | Compatibility Item | Reason | Removal Condition | | --- | --- | --- | --- | --- | -| Planned | Backend contracts | Legacy `CelestialId` placement fields alongside `anchorId` | Preserve contract compatibility while moving structures and ships to anchor-based placement truth | Remove once backend and viewer both consume anchor placement directly | -| Planned | Backend ship state | Legacy `DestinationNodeId` / node-based transit naming during anchor migration | Preserve existing travel wiring while renaming and rebinding spatial state | Remove once runtime and contracts use anchor terminology end-to-end | -| Planned | Viewer ingestion | Compatibility mapping from legacy world snapshot fields into anchor-based view models | Allow incremental frontend migration without blocking backend progress | Remove once viewer contracts expose anchors as primary data | +| Active | Backend contracts | Legacy `CelestialId` placement fields alongside `anchorId` | Preserve contract compatibility while moving structures and ships to anchor-based placement truth | Remove once backend and viewer both consume anchor placement directly | +| Active | Backend ship state | Legacy `DestinationNodeId` / node-based transit naming during anchor migration | Preserve existing travel wiring while renaming and rebinding spatial state | Remove once runtime and contracts use anchor terminology end-to-end | +| Active | Viewer ingestion | Compatibility mapping from legacy world snapshot fields into anchor-based view models | Allow incremental frontend migration without blocking backend progress | Remove once viewer contracts expose anchors as primary data | +| Active | Mining orders and directives | Overloaded generic `NodeId` usage for both mining travel and extraction targeting | The current name hides the required split between anchor travel and localspace extraction choice | Remove once mining travel uses `AnchorId` and extraction uses an explicit localspace target concept | ## Phase 1. Stabilize Vocabulary @@ -296,6 +297,50 @@ Make intra-system travel obey the universe model. - ships no longer “just move across the whole system” as the primary truth - warp is anchor-to-anchor by model, not just by UI +### Status + +Implemented. + +Notes: + +- ship runtime travel truth is now anchor-first +- warp transit stores origin/destination anchors plus timing/progress +- FTL transit uses anchor-based entry/destination semantics +- viewer ship state and travel presentation now prefer anchor-based transit fields +- legacy node/celestial travel fields remain only as explicit compatibility bridges + +Mining-specific clarification: + +- travel to a mining site should target an `anchorId` +- selecting a concrete rock or gas pocket should happen only after arrival inside that anchor's localspace +- generic `NodeId` usage is still overloaded in some mining/order/directive paths and should be split in a later migration slice + +## Phase 4A. Split Mining Travel From Local Extraction + +### Objective + +Make mining obey the same anchor/localspace boundary as the rest of the universe model. + +### Required + +- Mining travel targets an `anchorId`. +- Resource nodes remain anchors and strategic mining destinations. +- Concrete extractable targets are chosen only inside the destination localspace. +- Do not use one generic field to mean both: + - strategic mining destination + - tactical extraction target + +### Recommended + +- Rename overloaded mining `NodeId` fields to explicit meanings during this slice. +- Keep any remaining compatibility fields loud and temporary. + +### Success Criteria + +- mining travel is anchor-first +- tactical extraction targeting is localspace-only +- generic mining `NodeId` naming is no longer the primary truth + ## Phase 5. Update Viewer Contracts ### Objective diff --git a/docs/UNIVERSE-MODEL.md b/docs/UNIVERSE-MODEL.md index 977c00c..edcc093 100644 --- a/docs/UNIVERSE-MODEL.md +++ b/docs/UNIVERSE-MODEL.md @@ -197,6 +197,22 @@ Resource nodes are not construction sites. That is intentional so they can be spawned, depleted, despawned, and regenerated more freely than permanent infrastructure anchors. +Resource nodes are strategic mining destinations. + +That means: + +- outside localspace, a miner travels to a resource-node anchor +- inside that localspace, the miner chooses a concrete extractable target + +The concrete extractable target is a tactical mining concern, not a strategic travel identity. + +So: + +- travel uses `anchorId` +- local extraction uses a localspace-level target such as a rock, cluster, or gas pocket + +Do not use a generic `NodeId` to mean both. + ## Localspace `localspace` is the tactical simulation term and should be the only term used for this concept. @@ -232,6 +248,16 @@ Localspace is where close simulation happens: - local logistics - tactical defense +For mining specifically: + +- the destination localspace is chosen by anchor +- the final extractable target is chosen only after the ship is inside that localspace + +This preserves the distinction between: + +- strategic travel to a mining site +- tactical mining behavior inside that site + Ships and constructions do not exist directly in system space. They exist in one localspace at a time unless they are explicitly traveling between anchors. ## Ship Placement