Skip to content
Game Event Script

C# distribution

The C# reference implementation publishes four independently consumable packages under the GameEventScript product name:

  • GameEventScript.Runtime contains the portable Runtime, Program codec and validator, Host, shared values, and runtime literal parser.

  • GameEventScript.Compiler contains the source builder, compiler, and compilation options/errors and depends only on Runtime.

  • GameEventScript.CSharpBridge contains optional C# delegate, reflection, dictionary, and automatic-runner adapters and depends only on Runtime.

  • GameEventScript.SyntaxHighlighter contains optional GES/GESA editor ranges, TextMate scopes, incremental states and ANSI rendering, with no GES dependency.

Conformance remains an internal project for repository verification. CLI NuGet tools (since 0.3.0) are separate from these library packages; see CLI installation.

For precompiled .gesb execution, reference Runtime and optionally CSharpBridge. Source compilation additionally requires Compiler. The direct entry points are GameEventScriptBuilder.Create() for compilation and GameEventScriptHost.CreateBuilder() for host construction. File reading belongs to the CLI or embedding, which supplies text through AddScript(text, sourceName); the previous Bridge AddFile helper is removed.

All four public libraries target netstandard2.1. Their NuGet packages contain the Apache-2.0 license, repository README, XML API documentation, deterministic assemblies, and separate portable-PDB symbol packages.

Package and assembly names identify the module; the shared namespace root is GameEventScript. Public APIs use GameEventScript.Api, values use GameEventScript.Runtime.Values, and the optional libraries use GameEventScript.CSharpBridge. The public type names retain their existing GameEventScript or Ges prefixes.

Local release dry run

The repository pins the build SDK in global.json. The complete local dry run uses the same entry point as CI:

Terminal window
./scripts/release-csharp-dry-run.sh 0.1.0-rc.1

It builds canonical unsigned NuGet and symbol packages, validates their metadata and dependency graph, stages DLL sets, and runs external consumers through local NuGet restore and direct DLL references. Each route compiles a fixture and then loads and executes it in a separate application referencing only Runtime and CSharpBridge. That application also rejects Compiler or Conformance DLLs, dependency-manifest entries, and loaded assemblies. Each smoke test creates a fresh build tree below artifacts/csharp/distribution-consumers; the NuGet route also uses an empty package cache. This prevents stale CopyLocal DLLs with reproducible timestamps and sizes from contaminating release checks. Successful workspaces are removed; failed workspaces are retained at the printed path. No command in the dry run publishes an artifact.

NuGet assigns random internal Core Properties names during ordinary packing. The repository package tool rewrites this packaging-only metadata, ZIP entry order, and timestamps into a canonical form. Package normalization is permitted only before signing. A signed archive is rejected.

Two independent package runs can be compared byte for byte with:

Terminal window
./scripts/verify-csharp-reproducibility.sh 0.1.0-rc.1

Generated files exist only under the ignored artifacts/ tree:

artifacts/csharp/
  packages/<version>/
    GameEventScript.Runtime.<version>.nupkg
    GameEventScript.Runtime.<version>.snupkg
    GameEventScript.Compiler.<version>.nupkg
    GameEventScript.Compiler.<version>.snupkg
    GameEventScript.CSharpBridge.<version>.nupkg
    GameEventScript.CSharpBridge.<version>.snupkg
    GameEventScript.SyntaxHighlighter.<version>.nupkg
    GameEventScript.SyntaxHighlighter.<version>.snupkg
  dll/<version>/
    syntaxhighlighter/ # Standalone highlighter DLL, PDB and XML
    runtime/
    compiler/
    unity/

The runtime set contains Runtime alone; compiler contains Runtime and Compiler; unity contains Runtime and CSharpBridge. All sets include matching XML and PDB files.

Unity DLL use

The initial Unity integration is the dll/<version>/unity set. It contains GameEventScript.Runtime and GameEventScript.CSharpBridge; their DLLs are the runtime inputs, while matching XML and portable PDB files improve editor and debugger behavior. A consuming Unity project must support netstandard2.1 and must import both assemblies together when using the Bridge. Precompiled execution needs no Compiler DLL; source compilation additionally uses the Compiler DLL from the compiler set.

The repository verifies the exact staged pair through an external project with ordinary assembly references. This proves that the staged dependency set loads and executes without project references or Unity dependencies. A real Unity project remains the final engine compatibility gate because only Unity can validate its selected scripting backend, API compatibility level, and asset importer. Unity follow-up work is tracked in BACKLOG.md.

CI and publishing boundary

C# CI runs formatting, non-performance Conformance/native tests, the zero-allocation hot-path gate, the release dry run, and an independent reproducibility comparison. Performance references are measured separately by the manually triggered C# Performance Gate on a self-hosted macOS/ARM64 runner matching the checked-in performance profile.

C# Release Candidate prepares and uploads workflow artifacts (with visibility inherited from the repository). NuGet publishing is additionally gated by all of the following:

  • the manual publish input and matching Git version tag;
  • the independent SwiftPM distribution consumer check;
  • repository variable NUGET_PUBLISH_ENABLED=true;
  • the protected nuget GitHub environment;
  • a NuGet trusted-publishing policy for this repository/workflow/environment;
  • secret NUGET_USER, used by the official NuGet login action to request a short-lived API key through GitHub OIDC.

The repository variable is absent or false by default, so the publishing job cannot run. Availability of the chosen package IDs and publisher identity must be confirmed before that gate is enabled. Language-port and publication follow-up work is tracked in BACKLOG.md.

The package release guide describes owner configuration, Trusted Publishing and the shared Git-tag/version workflow. The upload script explicitly selects Runtime, Compiler, CSharpBridge and SyntaxHighlighter at the requested version, including their symbol packages. It never uploads every package found in a directory.