Files
systemrevivalserver/pending-clientChanges.md
T

167 lines
5.8 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, 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
- 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 (Still Needed)
- Browser world editor APIs are in place, but in-game overworld runtime streaming is still pending.
- Client still needs final runtime contract and handlers for:
- loading world region/zone/chunk state at player spawn
- receiving nearby chunk deltas from server during movement
- enforcing `isWalkable` and VIP paywall collision in live world movement
## 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.