# 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®ionId={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.