256 lines
10 KiB
Markdown
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®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.
|