Files
systemrevivalserver/Game/World/client_fixes.md
T
2026-02-16 16:41:23 -05:00

7.6 KiB

Client Changes Required After WorldHandler Refactor

Existing Protocol: UNCHANGED

All existing OpCodes (700-711) and payload shapes are identical. No changes needed for spawn, input, or state.

NEW: OpCode 712 - WORLD_CHUNK_DELTA (Server -> Client)

The server now pushes live chunk deltas to clients whenever the world is edited (admin panel, etc). Any player who has the affected chunk in their visible set receives the delta immediately, without waiting for a full chunk reload.

When it fires

  • Admin places/removes a tile via the world editor
  • Admin places/removes an object, NPC, or mob spawn
  • Admin clears or deletes a chunk

Payload shape

{
  "kind": "chunk_delta",
  "regionId": 1,
  "zoneX": 0,
  "zoneY": 0,
  "chunkX": 3,
  "chunkY": 2,
  "fromVersion": 5,
  "toVersion": 6,
  "op": { ... }
}

op types the client must handle

tile_upsert - A tile was added or changed

{
  "type": "tile_upsert",
  "x": 12,
  "y": 8,
  "sheetId": 3,
  "frameIndex": 42,
  "isWalkable": true,
  "isInvisiblePaywall": false
}

Client action: Find the chunk in chunk_cache by regionId/zoneX/zoneY/chunkX/chunkY. Update or insert the tile in the chunk's tiles array. Then call _rebuild_world_visuals(). Also update local walkability data if you cache it.

tile_remove - A tile was removed

{
  "type": "tile_remove",
  "x": 12,
  "y": 8
}

Client action: Remove the tile at (x, y) from the chunk's tiles array. Call _rebuild_world_visuals(). Mark that tile as walkable in local collision data.

object_upsert - An object was added or changed

{
  "type": "object_upsert",
  "id": 456,
  "x": 5,
  "y": 3,
  "objectDefinitionId": 12,
  "objectName": "Portal Stone",
  "interactionType": "Teleport",
  "rotation": 0,
  "metadataJson": "{\"portalType\":\"world\",...}"
}

Client action: Upsert by id in the chunk's objects array. Call _rebuild_world_entities().

object_remove - An object was removed

{
  "type": "object_remove",
  "id": 456
}

Client action: Remove the object with matching id from objects. Call _rebuild_world_entities().

npc_upsert - An NPC spawn was added or changed

{
  "type": "npc_upsert",
  "id": 789,
  "x": 10,
  "y": 15,
  "npcDefinitionId": 5,
  "npcName": "Merchant",
  "rotation": 0,
  "metadataJson": null
}

Client action: Upsert by id in the chunk's npcs array. Call _rebuild_world_entities().

npc_remove

{ "type": "npc_remove", "id": 789 }

Client action: Remove NPC with matching id. Call _rebuild_world_entities().

mob_upsert - A mob spawn was added or changed

{
  "type": "mob_upsert",
  "id": 101,
  "x": 20,
  "y": 25,
  "mobDefinitionId": 3,
  "mobName": "Slime",
  "rotation": 0,
  "spawnCount": 2,
  "respawnSeconds": 30.0,
  "metadataJson": null
}

Client action: Upsert by id in the chunk's mobs array. Call _rebuild_world_entities().

mob_remove

{ "type": "mob_remove", "id": 101 }

Client action: Remove mob with matching id. Call _rebuild_world_entities().

chunk_clear - All tiles/objects/npcs/mobs removed from chunk

{ "type": "chunk_clear" }

Client action: Empty the chunk's tiles, objects, npcs, mobs arrays. Call _rebuild_world_visuals() and _rebuild_world_entities().

chunk_deleted - Entire chunk deleted from DB

{ "type": "chunk_deleted" }

Client action: Remove the chunk from chunk_cache entirely. Call _rebuild_world_visuals() and _rebuild_world_entities().

Implementation guide for the client

In your GameState (or wherever you route opcodes), add a handler for opcode 712:

# In GameState or network handler:
712:  # WORLD_CHUNK_DELTA
    emit_signal("world_chunk_delta_received", data)

In the world scene script, connect to the signal and apply:

func _setup_runtime():
    # ... existing connections ...
    if GameState:
        GameState.world_chunk_delta_received.connect(_on_world_chunk_delta_received)

func _on_world_chunk_delta_received(data: Dictionary):
    if runtime == null:
        return
    runtime.apply_chunk_delta(data)
    _rebuild_world_visuals()
    _rebuild_world_entities()

In the world runtime client, add the delta application logic:

func apply_chunk_delta(data: Dictionary):
    var key = _chunk_key(
        int(data.get("regionId", 0)),
        int(data.get("zoneX", 0)),
        int(data.get("zoneY", 0)),
        int(data.get("chunkX", 0)),
        int(data.get("chunkY", 0))
    )
    var op = data.get("op", {})
    var op_type = str(op.get("type", ""))

    if not chunk_cache.has(key):
        return  # We don't have this chunk loaded, ignore

    var chunk = chunk_cache[key]

    match op_type:
        "tile_upsert":
            _delta_upsert_tile(chunk, op)
        "tile_remove":
            _delta_remove_tile(chunk, op)
        "object_upsert":
            _delta_upsert_by_id(chunk, "objects", op)
        "object_remove":
            _delta_remove_by_id(chunk, "objects", int(op.get("id", -1)))
        "npc_upsert":
            _delta_upsert_by_id(chunk, "npcs", op)
        "npc_remove":
            _delta_remove_by_id(chunk, "npcs", int(op.get("id", -1)))
        "mob_upsert":
            _delta_upsert_by_id(chunk, "mobs", op)
        "mob_remove":
            _delta_remove_by_id(chunk, "mobs", int(op.get("id", -1)))
        "chunk_clear":
            chunk["tiles"] = []
            chunk["objects"] = []
            chunk["npcs"] = []
            chunk["mobs"] = []
        "chunk_deleted":
            chunk_cache.erase(key)

    # Update version tracking
    var new_version = int(data.get("toVersion", 0))
    if chunk_cache.has(key):
        chunk_cache[key]["version"] = new_version

func _delta_upsert_tile(chunk: Dictionary, op: Dictionary):
    var tx = int(op.get("x", -1))
    var ty = int(op.get("y", -1))
    var tiles = chunk.get("tiles", [])
    for i in range(tiles.size()):
        var t = tiles[i]
        if int(t.get("x", t.get("tileX", -1))) == tx and int(t.get("y", t.get("tileY", -1))) == ty:
            tiles[i] = op
            return
    tiles.append(op)

func _delta_remove_tile(chunk: Dictionary, op: Dictionary):
    var tx = int(op.get("x", -1))
    var ty = int(op.get("y", -1))
    var tiles = chunk.get("tiles", [])
    for i in range(tiles.size() - 1, -1, -1):
        var t = tiles[i]
        if int(t.get("x", t.get("tileX", -1))) == tx and int(t.get("y", t.get("tileY", -1))) == ty:
            tiles.remove_at(i)
            return

func _delta_upsert_by_id(chunk: Dictionary, array_name: String, op: Dictionary):
    var id = int(op.get("id", -1))
    var arr = chunk.get(array_name, [])
    for i in range(arr.size()):
        if int(arr[i].get("id", -1)) == id:
            arr[i] = op
            return
    arr.append(op)

func _delta_remove_by_id(chunk: Dictionary, array_name: String, id: int):
    var arr = chunk.get(array_name, [])
    for i in range(arr.size() - 1, -1, -1):
        if int(arr[i].get("id", -1)) == id:
            arr.remove_at(i)
            return

Performance Notes

Server movement fix

The server tick loop no longer hits the database. Movement/collision is now pure in-memory. The "1 tile per 3 seconds" latency was caused by 30+ DB round-trips per player per tick on the server side.

LOCAL_MOVE_SPEED mismatch

The client uses LOCAL_MOVE_SPEED = 160.0 for local prediction, but the server walk speed is 120 px/s and run speed is 180 px/s. This causes minor rubber-banding. Consider changing LOCAL_MOVE_SPEED to 120.0 or reading the server's speed from WORLD_SPAWN.