Skip to content
Game Event Script

Game Event Script documentation

This directory is the canonical entry point for Game Event Script documentation. It separates normative, language-neutral contracts from non-normative learning material.

The project is distributed under the Apache License 2.0. The repository header, attribution, and file-exclusion rules are defined by the licensing policy; that policy is operational rather than part of the language specification.

Normative specification

Version notes such as Since: 0.1.0 and Since: Unreleased are informative availability hints, not additional language rules or a compatibility matrix. A note below a document title identifies its baseline; a more specific feature note takes precedence. A qualified note applies only to the feature it names. The version refers to the behavior currently described, not necessarily the first appearance of a similarly named feature. When behavior changes, update the note to the new release rather than retaining old behavior here. Unreleased requires a matching development build. Release history and migration details belong in the changelog.

Every contract area has exactly one owning document. Other documents link to that owner instead of restating its rules.

Contract area Owning document Responsibility Status
Language Language Lexical grammar, syntax, static semantics, and language constructs Normative
Syntax highlighting Highlighting Optional editor/terminal ranges, TextMate scopes and incremental states Normative
Public API Public API Language-neutral API responsibilities and per-language mappings Normative
Product JSON Message format Optional versioned message/value transport and external snapshots Normative
Host runtime Host runtime Host lifecycle, dispatch, execution, context, and outbound behavior Normative
Program model Program model Immutable transport data, ownership, validation, and linking boundary Normative
Bytecode Bytecode Instruction model, opcode semantics, operands, and control flow Normative
Binary format Binary format .gesb container, segments, encoding, retention, and decoding Normative
Assembler format Assembler format Human-readable .gesa dump syntax and presentation metadata Normative
Inline assembly Inline assembly Syntax, opcode inventory, and implementation gates Implemented
Diagnostics Diagnostics Stable phases, codes, locations, and propagation rules Normative
Text semantics Text Unicode, source text, names, ordering, scalar operations, data formatting, and literal recognition Normative
Number semantics Numbers Integer, Binary64, units, arithmetic, conversion, and equality Normative
Determinism Determinism Randomness, iteration, stable ordering, and deterministic dispatch Normative
Conformance Markdown Markdown format Portable suite authoring syntax and normalized test model Normative
Conformance runner Runner Capabilities, execution, results, reports, and received updates Normative
Independent runner protocol Python runner Standalone runner and internal implementation adapters Normative
Conformance environment Environment Fixed extensions, external types, sinks, observers, and resources Normative
Conformance coverage Coverage Stable mapping from portable behavior to executable case IDs Normative
Cross-language acceptance Cross-language acceptance Corpus identity and acceptance criteria for language ports Normative

All specification documents in the table are normative.

Compiler experiments

Generated API references

These describe the development checkout and show their source revision. They complement the portable specification with concrete language APIs.

Non-normative guides

The standalone CLI downloads describe C# and Swift archives, installation, checksums and the manual release workflow.

The Editor packages and syntax highlighting provide downloadable JSON and classic XML grammars for .ges and .gesa, with installation guidance.

Start with Learn Game Event Script, then choose the C# embedding guide or Swift embedding guide.

Guide contains tutorials, explanations, and examples intended for learning. A guide may simplify presentation but must link to the owning specification for exact behavior.

The C# implementation guide describes the library boundaries, solution and toolchain, build/test commands, CLI lifecycle and Compiler/Runtime embedding. The C# bridge guide covers attribute-based external types, extension functions and native callbacks. The C# CLI guide documents dotnet ges and the interactive event console; the C# distribution guide covers local packages, DLL sets and release verification. The package release guide describes the shared NuGet/SwiftPM release scope, Xcode consumption and publisher setup. Its version policy defines release numbering before and after 1.0. The platform support matrix lists toolchain requirements, actual CI coverage and the evidence required for release claims. The changelog collects user-visible changes and migration guidance for the next release. The 0.4.0 closing review records known limitations and remaining publication gates.

The Swift implementation guide describes the package boundaries, current port coverage, and local verification commands. It also documents the Xcode workspace for building and testing all Swift packages together. The Swift CLI guide describes ges, installation/update, the event console and native CLI verification. The SwiftBridge guide describes native closures, value conversions, typed external bindings and the optional synchronized Host runner. It depends only on Runtime. The Swift performance guide documents the measured profile, instrumentation scope and baseline review workflow. The generated performance baseline matrix (artifacts/conformance/PerformanceMatrix.md) lists every performance case with C# and Swift time/allocation references side by side. Create or refresh both tables with ruby --disable-gems scripts/write-performance-matrix.rb; the report stays under artifacts, and the shared Markdown remains the source of truth.

The numeric text roundtrip gate checks exact Number, Quantity and Percentage text exchange between C# and Swift. The product JSON roundtrip gate checks actual ordered message/value interchange against independent Markdown oracles.

Documentation rules

  • Normative documents describe only the current contract.
  • A rule is defined once. Cross-cutting documents use explicit links to the owning document.
  • C#, Swift, Kotlin, Go, Rust, C++, and Unity integrations may be idiomatic, but their observable behavior must satisfy the same language-neutral contracts.
  • Work plans, backlogs, test inventories, generated reports, and editor bundles remain outside the normative specification tree.
  • Public API names shown in a language mapping are not automatically language-neutral requirements unless the public API specification says so explicitly.