Summary And Gameplay Impact
Add a clean-room, engine-owned WorldGraph metadata layer that enriches Atlas, travel, wander, and living-world pressure with route kind, travel time/cost, terrain/biome, danger, discovery/fog, and strategic context. This turns the open-world layer from a list of connected locations into a tactical exploration graph while preserving existing travel authority.
Current ClawDnD State
ClawDnD already has Campaign.locations, Location.connections, travel_to, /atlas-surface, strategic clocks, and partial Atlas display work. Existing issues #60 and #117 cover the strategic living world and Atlas surface; closed issues #74 and #75 covered StrategicState seed ingestion and typed clocks/projects. What is missing is a durable graph metadata schema that connects travel mechanics, region pressure, biome-aware events, and Atlas visualization without becoming a second travel authority.
External Source Value And Recommendation
Use Azgaar/Fantasy-Map-Generator as reference-only. Its conceptual value is world graph thinking: nodes/settlements, route classes, terrain/biome cost, cells/regions, and map-derived metadata. Do not vendor Azgaar UI, renderer code, .map save format, global pack/grid state, or generated/fan map geometry.
Architecture Plan
- Keep
Campaign.locations and Location.connections as canonical travel authorization.
- Add additive graph metadata, either as
Campaign.world_graph or scoped Location/edge metadata.
WorldGraph.edges may enrich existing connections but must not authorize travel to unconnected destinations by itself.- Seed optional graph metadata from world JSON with deterministic validation and safe skips for malformed references.
- Read graph metadata from
travel_to, look_around, wander.py, and worldsim.py through pure helpers.
- Project only player-known graph fields through
/atlas-surface.
- Show route kind, travel cost/time, danger, biome/terrain, discovery/fog, and region pressure in OpenWorlds Atlas.
Files And Modules Likely Touched
servers/engine/models.pyservers/engine/content.pyservers/engine/travel.pyservers/engine/server.pyservers/engine/wander.pyservers/engine/worldsim.pyviewer/server.pyviewer/openworlds/screen-map.jsxviewer/tests/test_atlas_surface.pycontent/worlds/README.md
State-Authority Boundary
The graph is engine-owned metadata. Viewer/OpenWorlds may render it and may post player travel intent through /move, but may not write graph nodes, edges, discovery, route status, or world clocks directly.
Acceptance Criteria
- Old snapshots without
world_graph metadata load unchanged.
- Valid graph metadata seeds deterministically from content.
- Malformed graph references produce diagnostics/skips without corrupting campaign state.
travel_to still rejects destinations that are not reachable through canonical Location.connections.- Atlas read model includes route kind, travel cost/time, biome/terrain, danger, discovery/fog, and region pressure without leaking hidden nodes.
- Wander/worldsim can use biome/danger metadata with existing fallback behavior.
- At least one original-world fixture demonstrates the schema.
- No Azgaar UI,
.map save/load, renderer runtime, or third-party map geometry is imported.
Focused Validation Commands
uv run --directory servers/engine --group dev pytest -q tests/test_travel.py tests/test_worldsim.py tests/test_content.py
python3 -m unittest viewer.tests.test_atlas_surface -q
git diff --check
Adversarial Risks
- Accidentally duplicating travel authority between
Location.connections and graph edges.
- Hidden/future locations leaking through Atlas metadata.
- Copying Azgaar data shapes too literally instead of clean-room modeling.
- Fan/unlicensed geometry becoming committed content.
Original-Agent Handoff
Start with:
servers/engine/models.pyservers/engine/content.pyservers/engine/travel.pyviewer/server.pyviewer/openworlds/screen-map.jsxviewer/tests/test_atlas_surface.py
Refs #60, #117. Related to #74 and #75.
Summary And Gameplay Impact
Add a clean-room, engine-owned
WorldGraphmetadata layer that enriches Atlas, travel, wander, and living-world pressure with route kind, travel time/cost, terrain/biome, danger, discovery/fog, and strategic context. This turns the open-world layer from a list of connected locations into a tactical exploration graph while preserving existing travel authority.Current ClawDnD State
ClawDnD already has
Campaign.locations,Location.connections,travel_to,/atlas-surface, strategic clocks, and partial Atlas display work. Existing issues #60 and #117 cover the strategic living world and Atlas surface; closed issues #74 and #75 covered StrategicState seed ingestion and typed clocks/projects. What is missing is a durable graph metadata schema that connects travel mechanics, region pressure, biome-aware events, and Atlas visualization without becoming a second travel authority.External Source Value And Recommendation
Use
Azgaar/Fantasy-Map-Generatoras reference-only. Its conceptual value is world graph thinking: nodes/settlements, route classes, terrain/biome cost, cells/regions, and map-derived metadata. Do not vendor Azgaar UI, renderer code,.mapsave format, globalpack/gridstate, or generated/fan map geometry.Architecture Plan
Campaign.locationsandLocation.connectionsas canonical travel authorization.Campaign.world_graphor scopedLocation/edge metadata.WorldGraph.edgesmay enrich existing connections but must not authorize travel to unconnected destinations by itself.travel_to,look_around,wander.py, andworldsim.pythrough pure helpers./atlas-surface.Files And Modules Likely Touched
servers/engine/models.pyservers/engine/content.pyservers/engine/travel.pyservers/engine/server.pyservers/engine/wander.pyservers/engine/worldsim.pyviewer/server.pyviewer/openworlds/screen-map.jsxviewer/tests/test_atlas_surface.pycontent/worlds/README.mdState-Authority Boundary
The graph is engine-owned metadata. Viewer/OpenWorlds may render it and may post player travel intent through
/move, but may not write graph nodes, edges, discovery, route status, or world clocks directly.Acceptance Criteria
world_graphmetadata load unchanged.travel_tostill rejects destinations that are not reachable through canonicalLocation.connections..mapsave/load, renderer runtime, or third-party map geometry is imported.Focused Validation Commands
Adversarial Risks
Location.connectionsand graph edges.Original-Agent Handoff
Start with:
servers/engine/models.pyservers/engine/content.pyservers/engine/travel.pyviewer/server.pyviewer/openworlds/screen-map.jsxviewer/tests/test_atlas_surface.pyRefs #60, #117. Related to #74 and #75.