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.