Document overworld runtime client navigation contract and remaining client requirements

This commit is contained in:
dingo
2026-02-14 17:42:26 -05:00
parent 43c4ce7478
commit 0ba4d02767
+74 -10
View File
@@ -108,14 +108,14 @@
- `regionId`, `zoneX`, `zoneY`, `chunkX`, `chunkY`
- `fromVersion`, `toVersion`
- `op`:
- `tile_upsert`: `{ x, y, sheetId, frameIndex, isWalkable, isInvisiblePaywall }`
- `tile_remove`: `{ x, y }`
- `object_upsert`: `{ id, x, y, objectDefinitionId, objectName, rotation, metadataJson }`
- `object_remove`: `{ id }`
- `npc_upsert`: `{ id, x, y, npcDefinitionId, npcName, rotation, metadataJson }`
- `npc_remove`: `{ id }`
- `chunk_clear`: `{}`
- `chunk_deleted`: `{}`
- `tile_upsert`: `{ x, y, sheetId, frameIndex, isWalkable, isInvisiblePaywall }`
- `tile_remove`: `{ x, y }`
- `object_upsert`: `{ id, x, y, objectDefinitionId, objectName, rotation, metadataJson }`
- `object_remove`: `{ id }`
- `npc_upsert`: `{ id, x, y, npcDefinitionId, npcName, rotation, metadataJson }`
- `npc_remove`: `{ id }`
- `chunk_clear`: `{}`
- `chunk_deleted`: `{}`
### Browser world editor additions
@@ -136,6 +136,70 @@
- receiving nearby chunk deltas from server during movement
- enforcing `isWalkable` and VIP paywall collision in live world movement
### Runtime status and wiring note
- `WORLD_*` opcodes already reserved in `Networking/Messages/OpCodes.cs`:
- `WORLD_SPAWN_REQUEST` (`300`)
- `WORLD_SPAWN` (`301`)
- `WORLD_DESPAWN` (`302`)
- `WORLD_INPUT` (`310`)
- `WORLD_STATE` (`311`)
- Current server handler routing is still dungeon-only, so client should keep this behind a feature flag until runtime handlers are enabled.
### Client world navigation requirements
- Add world scene mode/state machine:
- `connecting -> awaiting_spawn -> active_world -> recovering`.
- Add runtime map cache keyed by `regionId:zoneX:zoneY:chunkX:chunkY`:
- Keep `version`, `tiles`, `objects`, `npcs`.
- Add coordinate helpers:
- Tile size is `32` pixels.
- `worldTileX = zoneX * chunksPerZoneX * chunkWidthTiles + chunkX * chunkWidthTiles + tileX`
- `worldTileY = zoneY * chunksPerZoneY * chunkHeightTiles + chunkY * chunkHeightTiles + tileY`
- Add collision gates before local prediction and on server reconciliation:
- Block movement if target tile has `isWalkable == false`.
- Block movement if target tile has `isInvisiblePaywall == true` and player is not VIP.
### Draft runtime packet contract for client implementation
- `WORLD_SPAWN_REQUEST` (`300`) request:
- `{ characterId? }` (or empty object if selected character is already server session state).
- `WORLD_SPAWN` (`301`) response:
- `success`
- `player`: `{ id, x, y, regionId, zoneX, zoneY, chunkX, chunkY }`
- `region`: `{ id, name, zonesX, zonesY, chunksPerZoneX, chunksPerZoneY, chunkWidthTiles, chunkHeightTiles }`
- `initialChunks[]`: same shape as world-editor `OnGetChunk` payload (`chunk`, `tiles[]`, `objects[]`, `npcs[]`)
- `nearbyPlayers[]` minimal shape: `{ id, name, x, y, direction, speed }`
- `WORLD_INPUT` (`310`) request (20hz max):
- `{ seq, moveX, moveY, isRunning, facing, x?, y? }`
- `WORLD_STATE` (`311`) response (10-20hz):
- `ackSeq`
- `self`: `{ x, y, velocityX, velocityY }`
- `players[]`: `{ id, x, y, facing, speed, isMoving }`
- `chunkDeltas[]`: list of delta payloads matching `kind: "chunk_delta"` operations used by world editor stream.
- `errors[]` optional: e.g. `["blocked_non_walkable"]`, `["blocked_paywall"]`.
- `WORLD_DESPAWN` (`302`) response:
- `{ playerId, reason }`.
### Chunk delta handling rules in client
- Apply delta only if `fromVersion == cachedVersion`.
- If mismatch or cache missing:
- Mark chunk `dirty`.
- Request full chunk refresh from runtime endpoint (or reconnect world session if no runtime chunk endpoint exists yet).
- `chunk_clear`:
- Remove all cached tiles/objects/npcs for that chunk.
- `chunk_deleted`:
- Remove chunk cache entry entirely and unload visuals/colliders.
### Rendering and assets
- Reuse tile-sheet loader logic from dungeon/world editor:
- Render from `sheetId + frameIndex`.
- Keep non-smoothed nearest-neighbor rendering for pixel art.
- Render paywall tile overlay only in editor/debug mode; keep invisible in normal gameplay while still colliding.
- Render object and NPC world instances from their definition IDs, reusing existing sprite/animation systems.
## Dungeon Portals and Ledge-Safe Movement
- Movement collision now uses entity radius checks against tile walkability.
@@ -160,7 +224,7 @@
- Room template object placements can define portal destination via `OverridesJson`:
- Pixel destination:
- `{ "targetX": 1024, "targetY": 640 }`
- `{ "targetX": 1024, "targetY": 640 }`
- Tile destination:
- `{ "targetTileX": 32, "targetTileY": 20, "useTileCoords": true }`
- `{ "targetTileX": 32, "targetTileY": 20, "useTileCoords": true }`
- VNext maps object templates of type `Portal` into runtime collision portals when destination metadata is present.