中文版: 06.tools-codegen.md

GoPlay's "call remote routes like local functions" experience is built on three layers of code generation:

1. goplay CLI - scans server-side processors and emits client extension methods / protocol constants; also exports Excel tables and Proto enums.
2. Roslyn source generator - emits ProcessorRef<T> extensions for [ProcessorApi] methods at compile time.
3. Roslyn analyzers - reject illegal cross-processor access and [MaxConcurrency] configuration at compile time.

Plus project templates (dotnet new goplay-tcp / goplay-ws) that scaffold a full-featured project in one command.

dotnet tool install -g GoPlay.Tools
goplay info

The command name is fixed as goplay (see ToolCommandName in Tools/Main/Main.csproj).

goplay info            show process information (debug)
goplay extension       scan Processors and emit client/server extensions
goplay config          Excel -> cs/yaml/json data tables
goplay excel2proto     Excel -> .proto enum

Example (from the template gen_ext.sh):

goplay extension \
  -i  $DIR \
  -ob $DIR/Client.Extension/ClientExtensions.be.cs \
  -of $DIR/Client.Extension/ClientExtensions.fe.cs \
  -b  ProcessorBase,GoPlayProjProcessor \
  -tb $DIR/scripts/liquids/server.liquid \
  -tf $DIR/scripts/liquids/server.liquid \
  -nb GoPlay.Core.Protocols \
  -nf GoPlay.Core.Protocols

Key options:

• -i input solution folder (parses .sln)
• -of / -ob output file for FrontEnd / BackEnd extensions
• -tf / -tb custom Liquid templates (can emit TypeScript, Unity C#, etc.)
• -b filter base classes; only processors extending them are scanned
• -nf / -nb extra using namespaces added to the generated code
• -igt / -igm class / method ignore lists

Generated sample (default C# template):

public static class ClientExtensions
{
    public static Task<(Status, PbString)> Echo_Request(this Client client, PbString data)
        => client.Request<PbString, PbString>("echo.request", data);

    public static void Echo_Notify(this Client client, PbString data)
        => client.Notify("echo.notify", data);
}

public static class ProtocolConsts
{
    public const string Push_EchoPush = "echo.push";
}

For non-C# clients (TypeScript, Unity-specific), just write a .liquid template; the scanner stays identical (see Tools/Generator.Extension/Processors2Extension.cs).

goplay config \
  -i Excels/ \
  -oc GoPlayProj/Common/Configs/ \
  -od data/ \
  -p s \
  -t yaml

• Input an Excel folder; output .cs (types + Manager) and .yaml / .json.
• Array splitters (-s), platform split (-p s|c for server/client), force re-export (-f), clean old (-c).
• Custom Liquid templates (-tc / -tm / -te).
• Reads Excel via EPPlus, writes YAML via YamlDotNet; see Tools/Generator.Config/.

Good for syncing ops table enums into the protocol:

goplay excel2proto -i Excels/ -oc proto/

Tools/Generator.ProcessorRef ships with GoPlay.Server as a Roslyn source generator. At compile time it scans every method tagged with [ProcessorApi] and emits a same-named extension on ProcessorRef<T> - so business code just writes Server.GetProcessor<Xxx>().TheMethod(...).

References:

• Attribute: Frameworks/Core/Attributes/ProcessorApiAttribute.cs
• Generator: Tools/Generator.ProcessorRef/ProcessorRefGenerator.cs
• Usage details: 04.processor-model.md

• Must be a public instance method on a Processor (no static / private / internal).
• Parameters cannot be ref / out / in (references across mailboxes are meaningless).
• Return Task / Task<T> preferred; if Fire = true, void is also OK.

• Forbids business code from holding another processor's raw instance / touching its private fields (bypassing the mailbox breaks serial semantics).
• Warns on direct Server.GetProcessorUnsafe<T>() usage (that API is itself [Obsolete]).

• Checks [MaxConcurrency(N)] has N >= 1.
• Checks method-level N <= class-level N.
• Illegal config fails the build, not the server.

Both analyzers come as NuGet dependencies of GoPlay.Server; no manual install.

dotnet new install GoPlay.Templates

dotnet new goplay-tcp -n MyGame         # NcServer-based
dotnet new goplay-ws  -n MyGame         # WsServer-based

dotnet new uninstall GoPlay.Templates   # cleanup

MyGame/
  GoPlayProj.sln
  Main/                   # entry point (System.CommandLine + HostBuilder)
  ProcessorsBase/         # shared processor base class GoPlayProjProcessor
  Processors.Logic/       # business processors (EchoProcessor / TimeProcessor to start)
  Processors.Admin/       # admin processors
  Processors.DbSaver/     # persistence processor (uses [ProcessorApi])
  Client.Extension/       # output of goplay extension
  Common/                 # RunArgs / AppConfig / SessionManager extensions
  UnitTests/              # NUnit end-to-end tests
  scripts/
    gen_ext.sh            # run goplay extension
    gen_proto.sh          # compile .proto
    gen_config.sh         # run goplay config
    gen_db.sh             # DB schema gen (if enabled)
    liquids/              # custom templates
  app.json / app.test.json

• gen_ext.sh: run after adding/changing any processor to refresh Client.Extension/*.cs.
• gen_proto.sh: run after editing .proto to invoke protoc and regenerate C# classes.
• gen_config.sh: run after updating ops Excel files to re-emit .cs + .yaml.

All scripts are bash; on Windows use Git Bash or WSL. Each is a thin wrapper over one goplay invocation.

When contributing to the framework itself:

# Build and pack all framework NuGets into ./packages
bash Frameworks/Scripts/build_nupkg.sh

# Publish to nuget.org (requires NUGET_KEY env)
bash Frameworks/Scripts/publish_nupkg.sh

# Publish the goplay CLI package
bash Tools/publish_nuget.sh

# Install goplay CLI locally (development)
bash Tools/publish_local.sh

Script locations: Frameworks/Scripts/, Tools/publish_nuget.sh, Tools/publish_local.sh.