diff --git a/pending-clientChanges.md b/pending-clientChanges.md index c7f9b92..11a75dc 100644 --- a/pending-clientChanges.md +++ b/pending-clientChanges.md @@ -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.