Lakona.Game.Server.Hotfix 0.2.3

Lakona.Game.Server.Hotfix

Runtime loader and dispatch infrastructure for server-side Lakona.Game hotfix assemblies.

This package keeps reload mechanics separate from actor runtime, sessions, transports, and gameplay code.

Design model

Lakona.Game hotfix separates stable state from replaceable logic:

stable actor or state object + reloadable static behavior methods

Actors, room loops, timers, persistence, RPC contracts, transports, and long-lived mutable state stay in stable assemblies. Hotfix assemblies contain stateless business rules that operate on stable state objects. A reload replaces the runtime dispatch table; it does not replace existing actor or state instances.

Hotfix behaviors should return stable DTOs that describe what happened. Stable runtime code should perform side effects such as persistence writes, leaderboard updates, session cleanup, logging, and network pushes.

Reload uses next-entry semantics: a method already executing keeps the version it resolved, while the next dispatch call sees the new table after a successful reload. If reload fails, the previous dispatch table remains active.

Server hotfix flow

Stable code owns state:

[HotfixState]
public partial class PlayerActor : Actor
{
 private int level;
 private int exp;
}

Hotfix code owns behavior:

[FriendOf(typeof(PlayerActor))]
[HotfixBehaviorOf(typeof(PlayerActor))]
public static class PlayerActorBehavior
{
 public static void AddExp(this PlayerActor self, int amount)
 {
 var exp = self.__hotfix_exp();
 }
}

Reload with IHotfixManager.ReloadAsync(). Reload failure keeps the previous dispatch table active.

Use AddLakonaGameHotfix(...) to register a source such as CurrentDirectoryHotfixAssemblySource, and pass stable assembly names as shared assemblies so Hotfix behaviors operate on the same state types as the running server. AddLakonaGameHotfixFileWatcher(...) can be added when a host should reload after hotfix DLL changes.

Loader safety contract

HotfixManager must be the only component that loads hotfix assemblies. Hosts must not call Assembly.LoadFrom on files in the hotfix directory. Reload reads the main hotfix DLL, adjacent PDB, and managed dependency DLLs into memory via stream loading before loading them into a collectible AssemblyLoadContext, validates shared type identity, and publishes the dispatch table only after validation succeeds. Native dependencies continue to use path-based loading.

Use version-pointer deployment for production:

hotfix/current.txt
hotfix/versions/<version>/Server.Hotfix.dll
hotfix/versions/<version>/Server.Hotfix.pdb

The pointer should change only after the version directory is fully written.

First-version boundaries

The first implementation uses one process-global dispatch table. Treat it as one hotfix domain per server process; do not register unrelated hotfix managers that should carry independent behavior in the same process.

Generated friend accessors are public members on [HotfixState] partial types because the hotfix assembly must be able to call them across an assembly boundary. [FriendOf] is metadata and convention for Hotfix behaviors, not a CLR security boundary. Only mark stable state types where exposing generated __hotfix_ accessors is acceptable, and keep sensitive runtime internals outside those state types.

Generated server apps discover [RpcService] contracts at build time and emit stable service proxies that call hotfix methods through HotfixServiceCall<TRequest> or HotfixServiceCall<TRequest, TCallback>. Hotfix assemblies implement those contracts with exactly one [HotfixService(typeof(IMyService))] static class per generated service contract. Reload validation rejects missing or duplicate required service implementations before publishing a new dispatch table.

State shape changes, protocol changes, serializer changes, persistent schema changes, and actor runtime changes are not hotfixes. Deploy or migrate stable assemblies for those changes.