# 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 within the same zone works without a loading screen.** The client's replica code **adopts** an object it already has for a new server's construction, and it never deletes its own player. So a new server can take over if it skips `LOAD_STATIC_ZONE`. This is the opt-in seamless mode (see below). The player keeps its object, position and camera; the other objects still fade out and come back. * **A transfer to another zone cannot skip the loading screen.** The client loads a zone only on `LOAD_STATIC_ZONE` (or its own script command), and that handler always shows the loading screen and deletes every object first. No server message loads or unloads single scenes. ## 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. ### A second construction of the local player What the client does when a construction arrives for the player object it already has (the seamless mode's case): * `LWOGameObject::Unserialize` @ `00f99690` runs every component's construction read on the live object. * `LWOBasePhysComponent::Deserialize` @ `00bf5a10`: when the construction has a frame, it is applied at once (position, rotation, both velocities), local player or not. Without the frame bit nothing is set. * `LWOInventoryComponent_Client::Deserialize` @ `00d52860` compares the equipped items with the ones it has and only equips or unequips the difference. * `LWOCharacterComponent::Unserialize` @ `00ca3a40` reads the 2-bit world transition state (0 none, 1 arriving by rocket, 2 leaving) and ends in `LWOCharacterComponent::PostCharacterLoaded` @ `00c71660`. With state 0 that pushes the gameplay state again and posts a **full screen fade from white**. In every case it sends `PlayerLoaded` to the server. State 3 is read but nothing acts on it. * `LWOGhostComponent::OnGhostReceiveDestruction` @ `00c99410`: when the local player's last ghost is destroyed the object stays, but it leaves scope (`LWOBaseRenderComponent::OnLeaveScope` @ `00c49140` hides it). The next construction brings it back through `LWOBaseRenderComponent::OnEnterScope` @ `00be2150`, which fades it in with the `login` effect. A destruction for a ghost that a newer construction already replaced does nothing. * `PlayerReady` (`LWOCharacterComponent::iSendMessage` @ `00d34330`) puts the gameplay camera's pitch back to the default; the rest of it refreshes UI. * `ConnectToWorldServer` posts `UILoginFeedback` state 4, which only calls `_root.setLoginFeedback` on the current Flash scene (`NDUIScaleformScene::SendMessage` @ `00bc2d10`). Nothing shows in game. ### 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 **except their own player**, 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 and keeps its player (in scope, with its old ghost), terrain and UI. * **Target**: the carried state is marked seamless. When that character's session is validated within 30 s, 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. * The construction of the player that goes to **its own client** differs from the one everyone else gets (`WorldMigration::KeepClientPlayer`): * no position frame, so the client stays where it stands instead of snapping back to where it was saved; * world transition state 3, so there is no fade from white. * The client sends `PlayerLoaded` by itself after that construction. If it has not after 5 s the server runs it. `PlayerReady` is not sent (the client is ready, and it would reset the camera pitch). * **First test (2026-09-30), before these changes**: no loading screen, but a white flash and the character came back with the login effect. Cause: the source destroyed the player's own ghost too, and the construction said transition state 0. * **Still visible**: the other objects fade out when the source takes them away and come back when the target constructs them. Objects placed in the level have the same object ID on both instances and could be handed over without that (construct on the target first, destroy the source's ghosts after); that needs network ID ranges that don't overlap between instances and is not built. * **Untested with these changes**: everything. 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. ### Live updates A live update ([LiveUpdate.md](LiveUpdate.md)) replaces every instance with these migrations (`MigrationCoordinator::Options::liveUpdate`). It also moves what the commands refuse: character selection (its users are sent to the new one), private instances (the replacement gets the same password) and activity zones (after their players had time to finish). Properties are not moved: building in progress there isn't saved, so they keep running on the old build until everyone left (see [LiveUpdate.md](LiveUpdate.md), Properties). `MIGRATE_PREPARE` (save and freeze a property first) remains in the protocol but live updates and world reloads no longer send it. The player's position is carried in `CarriedPlayerState` and applied when the target creates them, so Moon Base keeps it too. ### 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. * The seamless mode only works within one zone: another zone's terrain and scenes only load through `LOAD_STATIC_ZONE`. 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.