Document overworld runtime client navigation contract and remaining client requirements
This commit is contained in:
+74
-10
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user