Lakona.Tool 0.15.4

Lakona.Tool

Lakona.Tool is the command-line project tool for Lakona. It generates a complete Lakona.Game workspace from one project specification: shared contracts, server app, hotfix project, selected client, operations files, and generated project docs.

Install

dotnet tool install -g Lakona.Tool

Create A Project

lakona-tool new

For scripts and CI, provide the required options explicitly (--output, --persistence, --nugetforunity-source, and --deploy-profile default to ., none, openupm, and none respectively):

lakona-tool new --name MyGame --client-engine unity --transport kcp --serializer memorypack

For a lightweight headless client for smoke and load checks:

lakona-tool new --name MyGame --client-engine console --transport kcp --serializer memorypack

After generation, build the server, then run the printed check command before starting it:

cd MyGame
dotnet build "Server/Server.slnx"
dotnet run --project "Server/App/Server.App.csproj" -- --readiness-check

Supported values:

• --client-engine: unity, unity-cn, tuanjie, godot, console
• --transport: websocket, tcp, kcp
• --serializer: json, memorypack
• --persistence: none, postgres, mysql
• --nugetforunity-source: embedded, openupm
• --deploy-profile: none, compose

Defaults

By default, the generated project includes:

• a server project
• a Unity, Tuanjie, Godot, or Console client project
• a shared contract project
• Lakona.Game server and client dependencies
• Cluster infrastructure
• Hotfix infrastructure
• Reliable Push infrastructure

Generated server projects reference Lakona.Game.Server.Hotfix.Generators as an analyzer so public [HotfixBehaviorOf] extension methods define actor APIs, and Hotfix-owned generated behavior-derived selectors/refs are available at build time.

For Unity and Tuanjie clients, the tool pins Lakona.Game.Client and Lakona.Game.Abstractions in Assets/packages.config and generates an editor import guard that prevents NuGet analyzer DLLs from being loaded as Unity runtime plugins.

The generated appsettings.json intentionally stays small. It contains only the local node identity, session cleanup retention, and endpoint-local serializer/RPC service exposure under Lakona; cluster discovery, hotfix defaults, reliable push defaults, and RPC check output are derived by generated server helper code.

Generated server apps use build-time hotfix service discovery. RPC contracts marked with [RpcService] in referenced user contract assemblies produce stable server proxies automatically; new projects no longer need hand-written service marker files.

For a local Docker Compose rehearsal:

lakona-tool new --name MyGame --deploy-profile compose

To include database dependencies:

lakona-tool new --name MyGame --persistence postgres
lakona-tool new --name MyGame --persistence mysql

Generated Configuration

The default development appsettings file has this shape:

{
  "Lakona": {
    "Node": {
      "Id": "dev-1"
    },
    "Sessions": {
      "Cleanup": {
        "DisconnectedRetentionSeconds": 30
      }
    },
    "Endpoints": [
      {
        "Transport": "kcp",
        "Serializer": "memorypack",
        "Host": "127.0.0.1",
        "Port": 20000,
        "RpcServices": [ "login", "chat" ]
      }
    ]
  }
}

For WebSocket projects, the endpoint entry also includes "Path": "/ws".

Validate the derived project state with:

dotnet run --project "Server/App/Server.App.csproj" -- --readiness-check

The check prints the generated Cluster, Hotfix, Reliable Push, and RPC state so the default appsettings.json does not need to expose every derived setting.

Use JSON output when CI or deployment scripts need machine-readable validation results:

dotnet run --project "Server/App/Server.App.csproj" -- --readiness-check --json

Server Package

Create the initial deployable server zip:

lakona-tool server pack --runtime linux-x64

The server package is self-contained, RID-specific, untrimmed, and includes an installed initial hotfix version under hotfix/versions/<version>/.

Use --configuration Debug for symbol-rich staging packages:

lakona-tool server pack --runtime linux-x64 --configuration Debug

Hotfix Operations

Package future hotfix zips after the initial server package has shipped:

lakona-tool hotfix pack

Install a package into the node-local hotfix root:

lakona-tool hotfix install artifacts/hotfix/Server.Hotfix-v20260612-153045Z.zip --root hotfix

Activate, inspect, or roll back the loopback-only admin endpoint:

lakona-tool hotfix activate v20260612-153045Z --server http://127.0.0.1:20090
lakona-tool hotfix status --server http://127.0.0.1:20090
lakona-tool hotfix rollback --server http://127.0.0.1:20090

Distributed Configuration

The generated server derives a node-local feature model. A node is one .NET server process; generated defaults include gateway, node-directory, and route-directory infrastructure inside that node.

The default appsettings.json does not expose that full derived topology and does not include Lakona:Feature for the single-node starter. Use --readiness-check to inspect it. When a generated project is intentionally split across processes, use the canonical feature selection, Lakona:Endpoints[], endpoint RpcServices, and minimal Lakona:Cluster shape described in ../../docs/cluster.md; include Lakona:Cluster:Directory only when a split project owns shared cluster directory infrastructure. Do not add Services, endpoint Name, or deployment-shaped sections to appsettings until the framework owns and validates those settings.