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

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

  • 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.