Cross-Server Shared Event Maps - Epic

[eduardosmaniotto]

Cross-Server Shared Event Maps

Depends on: existing map/gate system, existing GameServerHeartbeat pub/sub

Scope

Intra-group subserver switching via 0xC3:0xB1:0x00/0xC3:0xB1:0x01.

Glossary

• Sprint 1 — Data Model: MapHostingMode, GlobalMapHostAssignment, OriginServerId, OriginMapNumber, HostedSharedMaps
• Sprint 2 — LoginServer Contract + Auth State + Map Host Resolver: SharedMapLocation, ISharedMapLocator, BeginTransferAsync, TransferResult, TransferPayload, PendingMove
• Sprint 3 — Packet, View Plugin, and Handler: MapServerChange (0xC3:0xB1:0x00), IMapServerChangePlugIn, MapServerChangeGroupHandler, ServerChangeAuthenticationHandlerPlugIn
• Sprint 4 — Teleport Logic: TryCrossServerMoveAsync
• Sprint 5 — Login Redirect + Return Trip + Edge Cases: TryRedirectExistingSessionAsync, TryReturnToOriginAsync

Architecture

LoginServer mediates all server moves. Game servers call one BeginTransferAsync, LoginServer validates capacity (via existing heartbeat data), generates auth, updates _connectedAccounts, and returns target IP/port. Forward trip position stored in LoginServer memory (30s). Origin server/map persisted on Character DB for return-trip routing.

IP + port + capacity come from the existing GameServerHeartbeat pub/sub (published by GameServerStatePublisher, already consumed by ConnectServer). LoginServer.Host subscribes to the same topic — no new registration RPC needed.

sequenceDiagram
    participant C as Client
    participant GS as Source GameServer
    participant LS as LoginServer
    participant GS2 as Target GameServer

    Note over C,GS2: Forward Trip / Login Redirect / Return Trip
    C->>GS: Enter gate / Select character
    GS->>GS: Check SharedMapLocator

    alt Map is global, hosted elsewhere
        GS->>LS: BeginTransferAsync(account, from, to, map)
        LS->>LS: Check capacity via heartbeat<br/>Generate auth[4]<br/>Update _connectedAccounts
        LS-->>GS: TransferResult (auth, IP, port)
        GS->>GS: Save OriginServerId to DB
        GS-->>C: 0xB1:0x00 (auth, IP, port)
        GS->>GS: Disconnect client
    else Normal flow
        GS->>GS: Local warp / EnterWorld
    end

    Note over C,GS2: Auth Validation
    C->>GS2: Connect + 0xB1:0x01 (auth)
    GS2->>LS: ValidateAuth(auth)
    LS->>LS: Match auth, clear PendingMove<br/>Return DestMapNumber
    LS-->>GS2: DestMapNumber
    GS2->>GS2: Load account from DB<br/>Set Player.Account<br/>Find character, set CurrentMap
    GS2->>GS2: Set Player.SelectedCharacter
    Note over GS2: OnPlayerEnteredWorldAsync fires<br/>Party/guild/friends wired

Loading

Sprints

Sprint 1 — Data Model

Add config entities for global map assignment and origin columns on Character for return-trip routing.

// src/DataModel/Configuration/GameMapDefinition.cs
public MapHostingMode HostingMode { get; set; }

// src/DataModel/Configuration/MapHostingMode.cs — NEW
public enum MapHostingMode { PerSubServer, Global }

// src/DataModel/Configuration/GlobalMapHostAssignment.cs — NEW
[Cloneable]
public class GlobalMapHostAssignment
{
    public short MapNumber { get; set; }
    public virtual GameServerDefinition? HostSubServer { get; set; }
}

// src/DataModel/Configuration/GameConfiguration.cs — add owning collection
[MemberOfAggregate]
public virtual ICollection<GlobalMapHostAssignment> GlobalMapHostAssignments { get; protected set; } = null!;

// src/DataModel/Entities/Character.cs — add two nullable columns
public byte? OriginServerId { get; set; }
public short? OriginMapNumber { get; set; }

// src/DataModel/Configuration/GameServerConfiguration.cs — add
public virtual ICollection<GameMapDefinition> HostedSharedMaps { get; protected set; } = null!;

Files: 2 new, 4 modified + EF migration

---

Sprint 2 — LoginServer Contract + Auth State + Map Host Resolver

Extend ILoginServer with BeginTransferAsync. Add a named helper to resolve map→host server (used by gate, warp, and login redirect — single source of truth). LoginServer subscribes to existing GameServerHeartbeat topic for capacity + IP/port data.

// src/GameLogic/SharedMapLocation.cs — NEW
public record SharedMapLocation(bool IsGlobal, byte? HostServerId, GameMapDefinition? Definition);

// src/GameLogic/ISharedMapLocator.cs — NEW
public interface ISharedMapLocator
{
    SharedMapLocation LocateGlobalMap(short mapNumber);
}

Implementation: filters GameConfiguration.GlobalMapHostAssignments, resolves host from HostSubServer.ServerID.

ISharedMapLocator added as a property on IGameServerContext (same pattern as LoginServer, GuildServer, FriendServer). All call sites access it via ((IGameServerContext)player.GameContext).SharedMapLocator.

// src/Interfaces/ILoginServer.cs — add

/// <summary>
/// Initiates a server-to-server transfer. Called by source game server for
/// live teleport, or by any game server for login redirect.
///
/// LoginServer:
///   - checks target capacity via heartbeat data
///   - generates 4 auth codes, stores (auth[4], destMapNumber) for 30s
///   - removes old server from _connectedAccounts, inserts new server
///   - returns auth codes + target address on success, error code on failure
/// </summary>
ValueTask<TransferResult> BeginTransferAsync(
    string accountName, byte fromServerId, byte toServerId, short destMapNumber);

// Discriminated result — success has payload, failure has only code
public readonly record struct TransferPayload(
    uint Auth1, uint Auth2, uint Auth3, uint Auth4,
    string TargetIp, ushort TargetPort);

public readonly record struct TransferResult(
    TransferResultCode Code, TransferPayload? Payload = null);

public enum TransferResultCode { Success, TargetOffline, TargetFull, InternalError }

LoginServer internal additions:

• _pendingMoves: Dictionary<string, PendingMove> — keyed by account name
• record PendingMove(byte ServerId, short DestMapNumber, uint[] Auth, uint Tick) — Tick for 30s expiry
• BeginTransferAsync: lookup target server from heartbeat data → check CurrentConnections < MaxConnections → store PendingMove → update _connectedAccounts[account] = toServerId → return auth + address from heartbeat
• Auth validation handler: match auth → clear PendingMove → return DestMapNumber
• LoginServer.Host subscribes to GameServerHeartbeat topic (same as ConnectServer already does) — populates ConcurrentDictionary<byte, ServerHeartbeatData> with current connections, max connections, public endpoint
• No new IGameServer additions needed

Files: 2 new (SharedMapLocation.cs, ISharedMapLocator.cs), 1 modified

---

Sprint 3 — Packet, View Plugin, and Handler

Server → Client 0xC3:0xB1:0x00 — MapServerChange (38 bytes)

Offset	Type	Field
0-3	C3HeaderWithSubCode	{ Type=0xC3, Code=0xB1, SubCode=0x00, Length=38 }
4-19	char[16]	ServerIpAddress
20-21	ushort	ServerPort
22-23	ushort	ServerCode
24-27	uint	AuthCode1
28-31	uint	AuthCode2
32-35	uint	AuthCode3
36-37	uint	AuthCode4

Client → Server (0xC3:0xB1:0x01, 69 bytes) already exists in codebase.

New group handler for 0xB1:

• MapServerChangeGroupHandler — extends GroupPacketHandlerPlugIn, GroupKey = 0xB1
• ServerChangeAuthenticationHandlerPlugIn — [BelongsToGroup(0xB1)], Key = 0x01

// src/GameLogic/Views/World/IMapServerChangePlugIn.cs — NEW
public interface IMapServerChangePlugIn : IViewPlugIn
{
    ValueTask MapServerChangeAsync(string ip, ushort port, ushort serverCode,
        uint auth1, uint auth2, uint auth3, uint auth4);
}

// src/GameServer/RemoteView/World/MapServerChangePlugIn.cs — NEW

// src/GameServer/MessageHandler/MapServerChangeGroupHandler.cs — NEW

// src/GameServer/MessageHandler/ServerChangeAuthenticationHandlerPlugIn.cs — NEW

ServerChangeAuthenticationHandlerPlugIn flow:

1. Deserialize 69-byte packet, Xor3-decode account/character name
2. Validate auth codes with LoginServer → get DestMapNumber
3. Load account from DB: player.PersistenceContext.GetAccountByLoginNameAsync(accountName)
4. Set player.Account = loadedAccount
5. Find target character in loadedAccount.Characters by decoded character name
6. Set character's CurrentMap to dest map, position to map spawn gate
7. Set Player.SelectedCharacter = character — this triggers OnPlayerEnteredWorldAsync (requires player.Account to be set), which fires PlayerEnteredWorld event that wires up party rejoin, guild registration, friend online state. Do NOT manually place character on map.

Files: 4 new

---

Sprint 4 — Teleport Logic

Wire BeginTransferAsync + ISharedMapLocator into gate/warp flows.

// In a shared helper:
async ValueTask<bool> TryCrossServerMoveAsync(Player player, ExitGate targetGate)
{
    var gsc = (IGameServerContext)player.GameContext;
    var location = gsc.SharedMapLocator.LocateGlobalMap(targetGate.Map.Number);

    if (!location.IsGlobal || location.HostServerId == gsc.Id)
        return false;

    var result = await gsc.LoginServer.BeginTransferAsync(
        player.Account!.LoginName, gsc.Id, location.HostServerId!.Value,
        targetGate.Map.Number);

    if (result.Code != TransferResultCode.Success)
    {
        // error feedback to player
        return true;
    }

    var payload = result.Payload!;
    // Save origin for return trip
    player.SelectedCharacter!.OriginServerId = gsc.Id;
    player.SelectedCharacter!.OriginMapNumber = player.SelectedCharacter!.CurrentMap!.Number;
    // persist to DB

    await player.InvokeViewPlugInAsync<IMapServerChangePlugIn>(
        p => p.MapServerChangeAsync(payload.TargetIp, payload.TargetPort,
            location.HostServerId.Value, payload.Auth1, payload.Auth2, payload.Auth3, payload.Auth4));
    player.Client.Disconnect();
    return true;
}

Called from WarpGateAction.EnterGateAsync and WarpAction.WarpToAsync.

GameServerMapInitializer creates global map instances for HostedSharedMaps.

Files: 1 new, 3 modified

---

Sprint 5 — Login Redirect + Return Trip + Edge Cases

Login redirect — SetSelectedCharacterAsync:

var gsc = (IGameServerContext)player.GameContext;
var location = gsc.SharedMapLocator.LocateGlobalMap(player.SelectedCharacter!.CurrentMap!.Number);
if (location.IsGlobal && location.HostServerId != gsc.Id)
{
    var result = await gsc.LoginServer.BeginTransferAsync(
        player.Account!.LoginName, gsc.Id, location.HostServerId!.Value,
        player.SelectedCharacter!.CurrentMap!.Number);
    // send 0xB1:0x00 via IMapServerChangePlugIn, disconnect
}

Return trip — WarpGateAction:

var character = player.SelectedCharacter!;
if (character.OriginServerId != null)
{
    var result = await gsc.LoginServer.BeginTransferAsync(
        player.Account!.LoginName, gsc.Id, character.OriginServerId.Value,
        character.OriginMapNumber!.Value);

    character.OriginServerId = null;
    character.OriginMapNumber = null;
    // persist to DB
    // send 0xB1:0x00 via IMapServerChangePlugIn, disconnect
}

Edge cases

Scenario	Handling
Target offline	No heartbeat data → TargetOffline
Target full	Heartbeat CurrentConnections >= MaxConnections → TargetFull
Target full (reconnect)	Login redirect → if host full → redirect to OriginServerId/OriginMapNumber; fallback to host safe zone
Player quits on shared map, rejoins	Login redirect on SetSelectedCharacterAsync
Mid-transfer disconnect	Auth codes expire after 30s. Character on global map in DB → login redirect.
Server crash	Origin persisted on Character. Reconnect → login redirect. If host still down → TargetOffline → player cannot log in until host recovers.
Auth code replay	30s expiry + _connectedAccounts already updated prevents it.
Party / Trade	SelectedCharacter setter triggers party rejoin on arrival. Trade cancelled (can't persist across servers).

---

Notes

• IP/port/capacity from existing GameServerHeartbeat pub/sub. LoginServer subscribes — no new RPC.
• _connectedAccounts[account] atomically updated inside BeginTransferAsync.
• GlobalMapHostAssignments owned by GameConfiguration with [MemberOfAggregate].
• Auth handler sets Player.SelectedCharacter → OnPlayerEnteredWorldAsync wires party/guild/friend.

[eduardosmaniotto]

I tried using AI to come up with a plan for shared maps. I'm not sure if it's good enough. @sven-n let me know what you think.

[sven-n]

It makes totally sense when the server is deployed 'distributed'. However, when we use the all-in-one deployment we can cut some corners: The client doesn't have to reconnect. Since we can access all game server instances within the same process, we can simply let it respawn in a map of another 'server'/GameServerContext. We could also move the RemotePlayer instances within from one GameServerContext to another.
The game server connection endpoint in this case is just an entry point to the server the client initially wanted to join. To fix the server name display in the character info panel, we could introduce a new packet.

I'd like to keep it as simple as possible, since even the original server had its problems with reconnection (lags when changing the map, dupe bug etc.)