DarkflameServer/docs/SeamlessTransfer.md

Moving players between world instances

How the LEGO Universe client (1.10.64, legouniverse.exe) switches world servers, what that allows, and how DarkflameServer uses it to replace an instance (live updates) or merge two quiet instances of a zone.

Addresses are from legouniverse.exe 1.10.64 in Ghidra; the functions below are named and commented there, with bookmarks in the SeamlessTransfer category. Message layouts were checked against the client first, then lu_packets.

Short answer

• A normal transfer always shows a loading screen. TRANSFER_TO_WORLD makes the client connect to another world server, and the LOAD_STATIC_ZONE that server sends tears the scene down and loads the zone again. There is no "same zone already loaded" shortcut in the client.
• The Mythran shift flag is not an animation. It is LU's own maintenance feature: after connecting it shows "Mythran Dimensional Shift Succeeded! You have been moved to a new dimension to continue playing." The matching warning ("Mythran Maintenance Alert! The Mythrans have detected some problems in this dimension...") is sent by the server as a localized announcement. Live used this to evacuate instances.
• Moving within the same zone keeps the player where they stood. Merging instances therefore works, but the player sees the warning, a short loading screen, and the "shift succeeded" notice.
• A transfer without a loading screen looks possible. The client's replica code can adopt an object it already has for a new server's construction, and it keeps its own player object when the old server takes its ghost away. So a new server can take over if it skips LOAD_STATIC_ZONE. This is built as an opt-in experiment (see below) and has not been tried with the real client yet.

What the client does (1.10.64)

TRANSFER_TO_WORLD (client message 0x0e)

PacketHandler_MSG_CLIENT_TRANSFER_TO_WORLD @ 00b32c60, packet ClientTransferToWorldPacket: char[33] ip, u16 port, bool mythranShift (lu_packets calls the flag is_maintenance_transfer).

• ip[0] == 0 means the transfer failed, and port is the reason: 0 "No empty servers available", 1 "Map couldn't load", 2 "Target specific instance was full", anything else "Non-specific failure". It is only shown in chat.
• Otherwise the client closes its world connection (LwoNetClient::CloseConnection @ 00a32080, with a disconnection notification), clears worldNetID (LwoNetClient::ResetNetID @ 00b213c0) and calls LwoNetClient::ConnectToWorldServer(ip, port, requestCharacterList = false) @ 00b325e0.
• If the connection attempt starts and mythranShift is set: it hides the announcement UI_INSTANCE_LOCKED_ANNOUNCE_TITLE and shows ToggleAnnounce with the title UI_INSTANCE_LOCKED_TRANSFERRED_TITLE and message UI_INSTANCE_LOCKED_TRANSFERRED_BODY.

Nothing else happens yet. The old scene stays on screen and nothing is deleted. ConnectToWorldServer only posts a UI network state message.

Connecting to the new world

• LwoNetClient::HandleServerConnectionType @ 00b2df70: once the version handshake with a world (service type 4) succeeds, it calls WorldValidation @ 00b2dc00.
• WorldValidation sends MSG_WORLD_CLIENT_VALIDATION (username, session key, cdclient.fdb checksum). It sends MSG_WORLD_CLIENT_CHARACTER_LIST_REQUEST only when requestCharacterList (LwoNetClient+0x79) is set. The character select screen sets it; a transfer does not. After a transfer the client waits for the server to act.
• PacketHandler_MSG_CLIENT_LOAD_STATIC_ZONE @ 00b2f170 resets everything without any checks: ResMgr2EnableLoadScreen, stop game rendering, DeleteAllGameObjects, RenderDumpAll, audio flush, LevelResetEnvironment, ResMgr2LoadZone, and the zone's mixer program. LoadThread_Run @ 0105ccf0 loads the zone from scratch every time (a second request while one is loading gets queued). Afterwards the client sends MSG_WORLD_CLIENT_LEVEL_LOAD_COMPLETE.
• PacketHandler_MSG_CLIENT_CREATE_CHARACTER @ 00b2eb40 creates the local player (LoadObject with isLocalPlayer) from the LDF (objid, template, position, rotation, xmlData), then sends ResMgr2NotifyLevelLoadComplete and UIReadyInGameUI. If an object with that ID already exists or is waiting to load, the packet is ignored.
• ServerDoneLoadingAllObjects (in LWOCharacterComponent::SendMessage @ 00d34330) moves the loading screen to its last phase. The client then sends PlayerLoaded, and the server answers with PlayerReady.

Replicas: taking over existing objects

• LwoClientGhostManager::OnReceiveConstruction @ 00b31c30: a construction for an object ID that already exists, or is waiting to load, does not create a second object. A new ghost is registered, and the existing object gets UpdateFromGhost followed by OnUnserialize(construction). This is also how the local player made by CREATE_CHARACTER receives its replica.
• LWOGhostComponent::OnGhostReceiveDestruction @ 00c99410: an object can hold several ghosts. When the last one is destroyed, other objects are deleted but the local player is kept (the code only clears pGhost).
• When the world connection closes, nothing is deleted. ReplicaManager::RemoveParticipant @ 00a478d0 leaves the objects alone.

Connection loss vs. a transfer

LwoNetClient::OnConnectionDropped_World @ 00b22fb0 shows NET_CONNDROP_WORLD_LOST, ..._TIMEOUT or ..._REFUSED, clears the character ID, and without a new connection shuts the network down and returns to the login screen. MSG_SERVER_DISCONNECT_NOTIFY @ 00b30590 gives each disconnect reason its own message. A transfer avoids all of this because the client clears worldNetID before the old connection closes.

The warning announcement

LocalizedAnnouncementServerToSingleClient (game message 1580). The client reads it in GameMessage::LocalizedAnnouncementServerToSingleClient::Deserialize @ 00f23c50:

1. body LDF (u32 length, then UTF-16 with a terminator)
2. bit forceOpenChatbox, bit showAnnouncementUI, bit showTextInChatbox
3. body (u32 length, then UTF-16)
4. title (u32 length, then UTF-16)
5. title LDF

LWOTranslator::LocalizeWithLdf @ 010e0430 looks the body and title up as locale phrase IDs and falls back to the text itself. That makes UI_INSTANCE_LOCKED_ANNOUNCE_TITLE / ..._BODY the game's own maintenance alert.

Other client-side state

The Flash UI keeps its state across a transfer: chat history, the open chat and friends windows, and the minimap. Friends, the team and guild live on the chat server, which the world forwards to. The client does not reset them itself; the new world sends them again. Anything tied to objects is rebuilt: the pet, missions shown in the UI, buffs, and possession.

What live servers sent (packet captures)

These are live captures of 242 world connections from several players (the lcdr capture archive). They were read locally, and none of it is in this repository. They agree with the client:

• TRANSFER_TO_WORLD: 168 captured. Every one is 44 bytes (8-byte header, char[33] ip, u16 port, u8 flag). All 168 have the Mythran shift flag at 0, and none were failures (empty ip). Ports were 2001-2009, one world server each. No maintenance transfer (flag 1) and no LocalizedAnnouncementServerToSingleClient (1580) is in the captures.
• What followed a transfer on the old connection: nothing in 89 of them. The rest show replica destructions (0x25, about 2,500) and disconnection notifications (0x13). Live took its objects away from the leaving client, but only after the transfer, when the client had already left. The experimental seamless mode sends them before it.
• Every new world connection started the same way: handshake, MSG_WORLD_CLIENT_VALIDATION, then at once LOAD_STATIC_ZONE. After that came the client's LEVEL_LOAD_COMPLETE, CREATE_CHARACTER, SERVER_STATES and the replica constructions. Some clients sent a few game messages in between.
  • A character list request appears in only 6 connections, the ones at character select. So after a transfer the client did not ask for its characters, as WorldValidation predicts.
• Transfers within the same map: 4 transfers went to another instance of the same map, all property → property (map 1150, different clones). Live still sent LOAD_STATIC_ZONE, a full reload. No live transfer kept the scene.

lu_packets' test packet src/world/client/tests/TransferToWorld.bin shows the same shape (ip "171.20.35.42" with the rest of the 33 bytes uninitialised, port 2005, flag 0). lcdr-utils' found.zip has only replica constructions.

What DarkflameServer does

Normal mode (loading screen)

1. A GM (level DEVELOPER) in the instance types /replaceinstance [warn seconds] [seamless] or /mergeinstance [target instance, 0 = best fit] [warn seconds] [seamless]. The world sends INSTANCE_MIGRATE to master. Anything else connected to master (a web dashboard later) can send the same message.

2. Master (dMasterServer/MigrationCoordinator) checks the source. Character selection, private instances, properties/clones and activity zones (any Activities.instanceMapID) are refused, as is an instance already taking part in a migration.

   • Replace: starts a new instance of the zone. It runs the world binary on disk now, so an updated server takes effect.
   • Merge: uses the chosen target or picks one (PickMergeTarget). The target has to fit everyone under its hard cap; one that stays under the soft cap is preferred, and then the fullest.

   The source is marked draining (FindInstance skips it, so nobody new is sent there). Seats for its players are reserved on the target (IsFull counts them). Once the target is ready, master sends MIGRATE_PLAYERS to the source.

3. Source world (dGame/dUtilities/WorldMigration):

   • Sends everyone the Mythran Maintenance Alert, then waits warnSeconds.
   • Moves up to 10 players a second. Each player's open trade is cancelled (nothing changes hands) and their character is saved, including position. The zone stays the same and the target scene is cleared, so they land where they stood.
   • The player is then locked: packets from them are ignored, and the disconnect does not save them again. Nothing they do after the save can be lost or duplicated, and a late save cannot overwrite what the target saves.
   • The pet that was out is sent on through MIGRATE_PLAYER_STATE, and the player gets TRANSFER_TO_WORLD with mythranShift.
   • Dead players and players in build mode wait up to 15 s.
   • A client still connected 20 s after its transfer is disconnected; it is already saved.
   • Progress goes to master every second (MIGRATE_STATUS). The migration is done once nobody is left and everyone sent away has disconnected.
   • Master passes each status on to every world. The world where the GM who asked is now tells them in chat each time the state changes.

4. Target world: a normal login (validation, LOAD_STATIC_ZONE, level load, CREATE_CHARACTER, construction). On PlayerLoaded it summons the carried pet.

5. Master releases the reservation and shuts the source down, unless keepSource was set. If anything fails, the source stops draining and a fresh target nobody reached is shut down again. If the target stops, the source is told to stop moving players.

6. Chat: the old world reports the disconnect, and the chat server waits 20 s before removing the player (which would also take them out of their team). The new world's login notice cancels that. Friends and the team carry over as long as loading takes less than 20 s.

Experimental seamless mode ("Without loading screen")

Built from the replica behaviour above:

• Source: after saving and locking the player, it sends a destruction for every object it sent them (DestructAllEntities) and then TRANSFER_TO_WORLD without mythranShift. Both go out on the same ordered channel, so the destructions arrive first. The client deletes those objects but keeps its player, terrain and UI.

• Target: the carried state is marked seamless. When that character's session is validated, the target skips LOAD_STATIC_ZONE and runs the level-load step at once (LoadPlayer): it creates the player entity, sends CREATE_CHARACTER (which the client ignores because the object exists), and constructs the player and everything else. The client adopts its existing player object for the new ghost. One second later the server does what the client's PlayerLoaded would have triggered, because the client never sends it again.

• Untested:

  • how the client reacts to ServerDoneLoadingAllObjects / PlayerReady without a load in progress
  • the UI state ConnectToWorldServer posts
  • the camera reset in PlayerReady
  • whether objects visibly pop out and back in

  If it goes wrong the worst case should be a stuck client that has to log in again. The character is already saved.

What carries over

Carried by	State
Character XML, saved before the transfer	position/rotation (same zone), health/armor/imagination, buffs (not cancelOnZone ones), inventory, missions, flags, currency, stats
MIGRATE_PLAYER_STATE	the active pet (summoned again)
Chat server	team, friends, guild (within the 20 s grace)
Client UI	chat history, open windows
Lost	an open trade (cancelled first), build mode in progress, possession/mounts, an activity lobby, dropped loot on the ground, things NPCs or enemies were doing (the target's world simulation is separate)

Messages (appended to MessageType::Master; nothing renumbered)

Message	Direction	Payload
INSTANCE_MIGRATE	world (GM command) or a future dashboard → master	InstanceMigrationRequest
MIGRATE_PLAYERS	master → source world	MigratePlayersOrder (target port 0 = cancel)
MIGRATE_STATUS	source world → master → every world	MigrationStatus (carries the requester's character ID)
MIGRATE_PLAYER_STATE	source world → master → target world	CarriedPlayerState

All structs are in dNet/InstanceMigration.h, together with the pure planning functions (CheckSource, CheckMergeTarget, PickMergeTarget, SuggestMerges, DecidePlayer). They are unit tested in tests/dCommonTests/InstanceMigrationTests.cpp. The values are appended after NEW_SESSION_ALERT; a branch that also appends there has to put one set after the other when merged.

Controls

• /replaceinstance [warn seconds, 0-300, default 10] [seamless]
• /mergeinstance [target instance, 0 = best fit] [warn seconds] [seamless]

Both need DEVELOPER, act on the instance the GM is in, and report progress to the GM in chat. SuggestMerges is there for a dashboard to offer merges; nothing uses it yet. A dashboard only has to send INSTANCE_MIGRATE and listen for MIGRATE_STATUS.

Limits

• Normal mode always shows a loading screen, because the client has no way around it once LOAD_STATIC_ZONE is sent. Staying in the same zone keeps it short: the zone files are warm in the OS cache and the target is already running.
• Only public, non-clone, non-activity instances can be moved.
• The target world starts its own simulation. Enemies, smashables, quickbuilds and dropped loot are the target's, not the source's.
• The team survives only when loading takes less than the chat server's 20 s grace.
• Players still loading into the source when it starts draining are moved once they have loaded.