10 KiB
10 KiB
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
npcsarray added to top-level dungeon state.- NPC payload fields:
id,definitionId,namex,y,rotationlevel,health,maxHealth,isAliveisKillable,canShop,hasDialogbehavior,onAttackBehaviorcurrentAnimation,spriteConfig,tintColor,scale
Interaction payloads
DUNGEON_INPUT_NPC_INTERACTrequest:{ npcId }
DUNGEON_INPUT_NPC_DIALOG_SELECTrequest:{ npcId, optionId }
DUNGEON_INPUT_NPC_SHOP_ACTIONrequest:{ npcId, action: "buy", slotIndex, quantity }
Dialog payloads
NPC_DIALOG_STATE:successnpcIdnode:{ 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
errorwhen blocked/invalid.
Shop payloads
NPC_SHOP_STATE:successshop:{ id, name, items[] }- each item:
{ slotIndex, itemDefinitionId, itemName, quantity, priceGold, restocks, restockIntervalSeconds }
NPC_SHOP_RESULT:success,npcId,action,itemDefinitionId,quantity,totalPrice,remainingGold,remainingStock- or
errorfor 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,versiontiles[]with{ x, y, sheetId, frameIndex, isWalkable, isInvisiblePaywall }objects[]with placement + definition idnpcs[]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,chunkYfromVersion,toVersionop: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=ClearChunkPOST /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.
- Keep
- Add coordinate helpers:
- Tile size is
32pixels. worldTileX = zoneX * chunksPerZoneX * chunkWidthTiles + chunkX * chunkWidthTiles + tileXworldTileY = zoneY * chunksPerZoneY * chunkHeightTiles + chunkY * chunkHeightTiles + tileY
- Tile size is
- 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 == trueand player is not VIP.
- Block movement if target tile has
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:successplayer:{ 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 ofchunkUpdatesentries wheretype = "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):tickackSeqself:{ 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 includesinteractionTypestring.chunk_unload:{ type, regionId, zoneX, zoneY, chunkX, chunkY }
portalEventoptional:- 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? }
- world teleport:
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+chunkYusingchunk.version.
- replace/refresh cache entry for
chunk_unload:- remove cache entry and unload chunk visuals/colliders.
- server emits
chunk_fullwhen 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.
- server saves
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 from
- 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 == falsetiles. - server blocks movement against
isInvisiblePaywall == truewhenplayer.isVip == false.
- server blocks movement against
World portal metadata contract (object metadataJson)
- Portal objects are world chunk objects whose definition has
interactionType = Teleport(or metadata includesportalType). 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:triggeredByWalkinteractionTypemetadataJson
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
Portalinto runtime collision portals when destination metadata is present.