Files
systemrevivalserver/pending-clientChanges.md
2026-02-15 10:11:35 -05:00

256 lines
10 KiB
Markdown

# Pending Client Changes
## NPC Interactions
- New input opcodes:
- `DUNGEON_INPUT_NPC_INTERACT` (`406`)
- `DUNGEON_INPUT_NPC_DIALOG_SELECT` (`407`)
- `DUNGEON_INPUT_NPC_SHOP_ACTION` (`408`)
- New response opcodes:
- `NPC_INTERACT_STATE` (`620`)
- `NPC_DIALOG_STATE` (`621`)
- `NPC_DIALOG_RESULT` (`622`)
- `NPC_SHOP_STATE` (`623`)
- `NPC_SHOP_RESULT` (`624`)
### DUNGEON_STATE additions
- `npcs` array added to top-level dungeon state.
- NPC payload fields:
- `id`, `definitionId`, `name`
- `x`, `y`, `rotation`
- `level`, `health`, `maxHealth`, `isAlive`
- `isKillable`, `canShop`, `hasDialog`
- `behavior`, `onAttackBehavior`
- `currentAnimation`, `spriteConfig`, `tintColor`, `scale`
### Interaction payloads
- `DUNGEON_INPUT_NPC_INTERACT` request:
- `{ npcId }`
- `DUNGEON_INPUT_NPC_DIALOG_SELECT` request:
- `{ npcId, optionId }`
- `DUNGEON_INPUT_NPC_SHOP_ACTION` request:
- `{ npcId, action: "buy", slotIndex, quantity }`
### Dialog payloads
- `NPC_DIALOG_STATE`:
- `success`
- `npcId`
- `node`: `{ id, text, isTerminal, rewardGold, rewardXp, rewardItemDefinitionId, rewardItemQuantity, rewardQuestKey }`
- `options`: list of `{ id, text, nextNodeId }` that pass server-side conditions.
- `NPC_DIALOG_RESULT`:
- `success`, `npcId`, `nextNodeId`, `isTerminal`
- or `error` when blocked/invalid.
### Shop payloads
- `NPC_SHOP_STATE`:
- `success`
- `shop`: `{ id, name, items[] }`
- each item: `{ slotIndex, itemDefinitionId, itemName, quantity, priceGold, restocks, restockIntervalSeconds }`
- `NPC_SHOP_RESULT`:
- `success`, `npcId`, `action`, `itemDefinitionId`, `quantity`, `totalPrice`, `remainingGold`, `remainingStock`
- or `error` for failure states.
## Stash Access
- Stash is no longer VIP-gated on server.
- Existing stash opcodes are unchanged:
- `STASH_REQUEST` (`610`)
- `STASH_STATE` (`611`)
- `STASH_DEPOSIT` (`612`)
- `STASH_WITHDRAW` (`613`)
- `STASH_RESULT` (`614`)
## Overworld Live Editing (Planned)
- Browser editor needs world hierarchy selection:
- region -> zone -> chunk
- optional full-zone load mode
- Region minimap support:
- zone outlines for the full region
- selected zone/chunk highlight
### Tile editing requirements
- Tile picker flow:
- select sprite sheet
- select frame index
- set `isWalkable` (bool)
- set `isInvisiblePaywall` (bool)
- Live placement and erase should apply immediately via proximity-safe delta updates.
### Object/NPC editing requirements
- Place/move/remove object instances from filterable definition lists.
- Place/move/remove NPC spawns from filterable NPC definition lists.
- Changes should be chunk-scoped and include version numbers to prevent stale overwrites.
### Proposed payload additions
- Chunk state payload:
- `regionId`, `zoneId`, `chunkX`, `chunkY`, `version`
- `tiles[]` with `{ x, y, sheetId, frameIndex, isWalkable, isInvisiblePaywall }`
- `objects[]` with placement + definition id
- `npcs[]` with spawn placement + npc definition id
- Delta update payload:
- `regionId`, `zoneId`, `chunkX`, `chunkY`, `fromVersion`, `toVersion`
- operations list (tile upsert/remove, object upsert/remove, npc upsert/remove)
### Implemented live stream contract (browser world editor)
- SSE endpoint:
- `GET /admin/worldeditor?handler=Stream&regionId={id}&zoneX={x}&zoneY={y}&chunkX={x}&chunkY={y}`
- Message payload:
- `kind: "chunk_delta"`
- `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, interactionType, rotation, metadataJson }`
- `object_remove`: `{ id }`
- `npc_upsert`: `{ id, x, y, npcDefinitionId, npcName, rotation, metadataJson }`
- `npc_remove`: `{ id }`
- `mob_upsert`: `{ id, x, y, mobDefinitionId, mobName, rotation, spawnCount, respawnSeconds, metadataJson }`
- `mob_remove`: `{ id }`
- `chunk_clear`: `{}`
- `chunk_deleted`: `{}`
### Browser world editor additions
- Region creation endpoint:
- `POST /admin/worldeditor?handler=CreateRegion`
- Request: `{ name, zonesPerRegionX, zonesPerRegionY, chunksPerZoneX, chunksPerZoneY, chunkWidthTiles, chunkHeightTiles }`
- Response: `{ success, region }`
- Chunk maintenance endpoints:
- `POST /admin/worldeditor?handler=ClearChunk`
- `POST /admin/worldeditor?handler=DeleteChunk`
- Tile paint now respects tile definition walkability when a definition exists for selected `sheetId + frameIndex`.
## Overworld Runtime Client Support
- Runtime world opcodes are now server-wired through `WorldHandler`.
- Browser world editor APIs still exist separately for admin live-editing.
### Runtime opcodes
- `WORLD_SPAWN_REQUEST` (`700`)
- `WORLD_SPAWN` (`701`)
- `WORLD_DESPAWN` (`702`)
- `WORLD_INPUT` (`710`)
- `WORLD_STATE` (`711`)
### 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.
### Implemented runtime packet contract
- `WORLD_SPAWN_REQUEST` (`700`) request:
- `{ regionId?, zoneX?, zoneY?, chunkX?, chunkY? }`
- all fields optional.
- if not provided, server prefers persisted character world location.
- if character has no saved world location, server defaults to first enabled region at `zone/chunk = 0,0`.
- `WORLD_SPAWN` (`701`) response:
- `success`
- `player`: `{ id, name, x, y, regionId, zoneX, zoneY, chunkX, chunkY, isVip }`
- `region`: `{ id, name, zonesX, zonesY, chunksPerZoneX, chunksPerZoneY, chunkWidthTiles, chunkHeightTiles }`
- `tileSheets[]`: `{ id, name, path, tileW, tileH, cols, sheetW, sheetH }`
- `initialChunks[]`: subset of `chunkUpdates` entries where `type = "chunk_full"`:
- `{ type: "chunk_full", chunk, tiles[], objects[], npcs[], mobs[] }`
- `nearbyPlayers[]`: `{ id, name, x, y, facing, speed, isMoving }`
- `WORLD_INPUT` (`710`) request (20hz max):
- `{ seq, moveX, moveY, isRunning, facing }`
- `WORLD_STATE` (`711`) response (10-20hz):
- `tick`
- `ackSeq`
- `self`: `{ x, y, velocityX, velocityY }`
- `players[]`: `{ id, name, x, y, facing, speed, isMoving, regionId, zoneX, zoneY, chunkX, chunkY }`
- `chunkUpdates[]`:
- `chunk_full`: `{ type, chunk, tiles[], objects[], npcs[], mobs[] }`
- `objects[]` now includes `interactionType` string.
- `chunk_unload`: `{ type, regionId, zoneX, zoneY, chunkX, chunkY }`
- `portalEvent` optional:
- world teleport: `{ type: "world_teleport", sourceObjectId, regionId, zoneX, zoneY, chunkX, chunkY, x, y }`
- dungeon transfer request: `{ type: "dungeon_request", sourceObjectId, portalType, dungeonTemplateId?, randomTier?, levelBracketMin?, levelBracketMax? }`
- `errors[]` optional: e.g. `["blocked_non_walkable"]`, `["blocked_paywall"]`.
- `WORLD_DESPAWN` (`702`) response:
- `{ playerId, reason }`.
### Chunk update handling rules in client
- `chunk_full`:
- replace/refresh cache entry for `regionId+zoneX+zoneY+chunkX+chunkY` using `chunk.version`.
- `chunk_unload`:
- remove cache entry and unload chunk visuals/colliders.
- server emits `chunk_full` when entering visibility range or when chunk version changes.
- player world location persistence:
- server saves `{ regionId, zoneX, zoneY, chunkX, chunkY, x, y }` on disconnect.
- next world spawn (without explicit location override) returns player to that saved position.
### 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.
- Movement authority:
- server blocks movement against `isWalkable == false` tiles.
- server blocks movement against `isInvisiblePaywall == true` when `player.isVip == false`.
### World portal metadata contract (object `metadataJson`)
- Portal objects are world chunk objects whose definition has `interactionType = Teleport` (or metadata includes `portalType`).
- `portalType: "world"`:
- `{ "portalType":"world","targetRegionId":1,"targetZoneX":0,"targetZoneY":0,"targetChunkX":0,"targetChunkY":0,"targetTileX":5,"targetTileY":5 }`
- server teleports immediately on collision.
- `portalType: "dungeon_random"`:
- `{ "portalType":"dungeon_random","randomTier":3,"levelBracketMin":11,"levelBracketMax":20 }`
- server emits `portalEvent.type = "dungeon_request"` for client-driven dungeon entry flow.
- `portalType: "dungeon_specific"`:
- `{ "portalType":"dungeon_specific","dungeonTemplateId":42 }`
- server emits `portalEvent.type = "dungeon_request"` for client-driven dungeon entry flow.
## Dungeon Portals and Ledge-Safe Movement
- Movement collision now uses entity radius checks against tile walkability.
- Prevents edge-clipping / hanging off non-walkable ledges while moving.
- Dungeon supports collision-triggered teleport portals with server-authoritative destination.
### DUNGEON_STATE portal payload additions
- `portals[]` now also includes:
- `triggerOnCollision` (bool)
- `triggerRadius` (pixels)
- `destinationX`, `destinationY` (world-space pixels, nullable)
### DUNGEON_STATE placed object payload additions
- `placedObjects[]` now also includes:
- `triggeredByWalk`
- `interactionType`
- `metadataJson`
### Template portal metadata convention
- Room template object placements can define portal destination via `OverridesJson`:
- Pixel destination:
- `{ "targetX": 1024, "targetY": 640 }`
- Tile destination:
- `{ "targetTileX": 32, "targetTileY": 20, "useTileCoords": true }`
- VNext maps object templates of type `Portal` into runtime collision portals when destination metadata is present.