Game Learning Runtime

English | 简体中文

Game Learning Runtime (GLR) is an agent-first, learner-neutral control plane for game learning. It gives an agent one stable JSON CLI and strict contracts to start an authorized game bridge, train while recording review video, query prior runs and world knowledge, research guides, revise bounded training and reward plans, and reproduce a verified model bundle in a new game instance.

Define observations, actions, masks, rewards, events, and episode boundaries once. The same adapter remains reusable with TorchRL, custom PPO or IMPALA, behavior cloning, offline datasets, evaluation, and automated QA.

A game-learning runtime designed to be operated by agents.

GLR is for games and test environments you own or are authorized to instrument. It does not include anti-cheat bypasses, stealth injection, or game-specific reverse-engineering code.

Why interface-first training

GLR lets an agent learn through a structured environment interface: observations, actions, rewards, events, and episode boundaries are exchanged as compact data. Compared with pixel-only control, this usually means fewer vision frames and less context per decision, so training can converge faster while using fewer tokens and lower inference cost. Pixel capture remains useful for review and human-facing evidence; it is not required for every control step.

See GLR running

This GIF is generated from a real local ContractEnvironment + SyncCollector run against GLR's explicitly synthetic counter adapter. It demonstrates the public contract without exposing a game account, machine path, process/window identity, or proprietary runtime data. See the showcase provenance and capture policy before contributing footage from a live adapter.

Training workflows we use in practice

We use GLR-style interface control in authorized local workflows for Black Myth: Wukong and Vampire Survivors. This section separates the visual demo from the engineering claim: the media shows what a run looks like, while the runtime contracts and run records remain the source of truth for observations, actions, rewards, and terminal outcomes.

Black Myth: Wukong	Vampire Survivors
Play the short Wukong clip	Play the short Vampire Survivors clip

Full Black Myth: Wukong recording

Click the image to open the seven-minute, muted recording in GitHub's media viewer. The repository copy is resized and compressed for web playback; use the short clip above for a quick preview.

The 12×12 contact sheet is a compact review of a longer Vampire Survivors run. These visuals are demonstrations, not claims of a completed benchmark, terminal win, or general model quality.

One boundary, many consumers

Game / simulator
      │
      ▼
Runtime adapter (C#, C++, Rust, Python, official API, ...)
      │
      ▼
GLR protocol + environment contract
      │
      ├── TorchRL
      ├── custom PPO / IMPALA
      ├── BC / DAgger / offline learning
      ├── recorder / replay
      └── evaluation / automated QA

Game adapters never import PPO, IMPALA, BC, or TorchRL. Learning code does not need to know whether the runtime is Unity, Unreal, Source, native, or a test simulator. GLR standardizes the data and lifecycle boundary, not one language, engine, transport, or algorithm.

What GLR standardizes

Game-specific adapters, authenticated target-bound local provider transport, distributed actor transport, production trainers, and reference policies remain roadmap work.

Quick start

Install the matching standalone archive from the latest GitHub Release. Verify glr-{version}-{rust-target}.zip against SHA256SUMS, then put glr and glr-hostd on PATH. The archive also carries the glr-cli and glr-adapter-builder Skills.

The CLI is the primary deployment, integration, training, query, and playback entrypoint. It does not require Python:

glr --version
glr --project . --json doctor
glr --json update --check

Install the Python SDK only when a trainer, adapter, or learner imports it:

uv add game-learning-runtime

Choose optional integrations only where they are needed:

uv add "game-learning-runtime[torchrl]"
uv add "game-learning-runtime[torch]"
uv add "game-learning-runtime[gymnasium,torchrl]"

Agent-operated project

Once an authorized project provides glr-project.json and its fixed bridge roles, an agent can use the same machine-readable interface for the complete workflow:

glr --project . --json doctor
glr --project . --json runtime start
glr --project . --context config/contexts/ranked.toml --json train
glr --project . --json task list
glr --project . --json task run season --set profile=example/default
glr --project . --json goal run --goal goals/reach-destination.json
glr --project . --json query entities --world forest --kind shrine
glr --project . --json query routes --world forest --to-entity shrine.forest-1
glr --project . --json query research --tag navigation
glr --project . --json report build run-0123456789abcdef
glr --project . --json play --bundle .glr/exports/model-bundles/model-bundle

The project manifest owns exact executable paths, environment identity, data locations, and runtime/trainer/player/researcher/planner/evaluator/recorder roles. GLR validates and orchestrates those roles; it does not embed a game-specific launcher, scraper, or learning algorithm.

Projects can add strict, fixed-argv workflows in glr.toml. Use runner = "vx" for Python training tasks so VX owns runtime and virtual environment resolution while GLR owns validation, dependency ordering, timeout, logs, and execution receipts. See Extend GLR with declarative VX tasks.

Default goal binding

A goal is structured metadata: it is copied into the run directory as an auditable receipt and never shapes rewards or judges completion. Bind one goal per project so goal run works without repeating --goal, and bind the run context that makes it executable so train works without repeating --context:

glr --project . --context config/contexts/ranked.toml --json goal set --goal goals/reach-destination.json
glr --project . --json goal show
glr --project . --json goal list
glr --project . --json goal use goal.reach-destination
glr --project . --json train
glr --project . --json goal run

Bindings live in <data_dir>/goal-binding.json (glr.goal-binding.v1) and store project-relative paths plus a SHA-256 of the goal file, so goal show reports source_status (unchanged / changed / missing) and context_status (unbound / bound / unresolved). An explicit --goal or --context always wins over the saved default, so existing scripts keep their behaviour. doctor reports the active goal under goal_binding, and every run receipt records goal_binding.source (default or explicit), goal_binding.context_source (explicit / default / none), and the source_status of a default goal. Bind with goal set plus the global --context flag; the stored paths are re-checked when the store is loaded, so a hand-edited path outside the project is refused instead of opened.

DSH-like plugin bundles

Projects can compose reviewed learner, recorder, evaluator, or harness bundles through a declarative profile, inspired by DeepSeek Harness (DSH). The control plane accepts local directories, validates glr.plugin.v1 and glr.profile.v1, and never imports entrypoints, runs hooks, starts processes, or accesses the network during inspection or installation:

glr --project . --json plugin inspect --source plugins/torchrl-learner
glr --project . --json plugin install --source plugins/torchrl-learner --sha256 <digest>
glr --project . --json plugin profile enable training torchrl-learner --grant read:environment
glr --project . --json plugin profile resolve training
glr --project . --json plugin health --profile training

Use the plugin system guide for the bundle schema, permission model, and Python API. TorchRL is the recommended first learner slot because its optional 0.13 integration is already CI-tested; Sample Factory remains an independent high-throughput backend choice. The repository ships the contracts and lifecycle, not either framework's payload.

Select invocation-specific configuration with a strict project-relative glr.run-context.v1 TOML file. GLR freezes the context and its declared inputs, passes the receipt to every configured role, and persists it with the run. Domain concepts such as a season or ruleset remain labels or VX task policy; they do not become core CLI commands. See Bind an invocation run context.

glr update --check only inspects the latest stable release. After an explicit update request, glr update verifies the exact target archive and SHA256SUMS, then updates glr, its sibling glr-hostd, and the project-owned Skills. It never changes game code, trainer dependencies, models, datasets, or project configuration. The check uses GitHub's public latest-release asset link without consuming anonymous REST API quota. Use --no-skills for binary-only maintenance or --skills-dir for an explicitly selected Skills directory. The former --yes form remains accepted for compatibility. When binaries are already current, glr update still synchronizes configured project Skills from the verified release archive.

Library integration

Collect a learner-neutral unroll:

from game_learning_runtime import ContractEnvironment, SyncCollector
from game_learning_runtime.examples import CounterEnvironment, always_increment

environment = ContractEnvironment(CounterEnvironment(target=3))
collector = SyncCollector(environment, actor_id="local-actor")
unroll = collector.collect(always_increment, steps=16, policy_version=0)

print(len(unroll.transitions), unroll.total_reward)

For an authorized already-running game, advertise live-attach and select that lifecycle explicitly:

environment = ContractEnvironment(authorized_live_adapter)
collector = SyncCollector(environment, start_mode="attach")
unroll = collector.collect(policy, steps=128, stop_on_done=True)

Attach starts a fresh logical GLR episode at step zero. It never claims that the physical game world was reset or seeded.

From a user goal to verified replay

user goal + hard budgets
          │
          ▼
allowed rules / text / video + prior runs / spatial knowledge
          │
          ▼
research ──► plan ──► train + indexed video ──► authoritative evaluation
                ▲                                      │
                └──────── bounded revision ────────────┘
                                                       │
                                                       ▼
                                   queryable evidence + model bundle
                                                       │
                                                       ▼
                                      verified replay in a new instance

Training can run a project-owned small-window recorder concurrently and bind its H.264 output to episode/step IDs for human review and later supervised-data selection. Goal runs gather allowed official rules, text guides, video tutorials, and runtime traces through the configured researcher; adjust declarative reward plans between bounded trials; and stop only on matching authoritative runtime metrics. Guides and transferred knowledge remain advisory until fresh runtime evidence verifies them. See Operate GLR as an agent-first control plane.

Unity and Unreal integration lanes

GLR keeps one learner-facing contract while making the runtime boundary explicit:

• Source or official extension SDK: run an engine plugin with semantic state, native actions, main-thread dispatch, controllable time, and a truthful physical reset.
• Authorized binary-only runtime: attach externally through an official API, telemetry, replay, or bounded rendered observation/input seam. It defaults to real-time attach, exact target binding, input lease cleanup, and verified post-state.
• Authorized mod-loader runtime: host a reviewed bounded-command adapter in BepInEx or UE4SS. It keeps truthful real-time attach, semantic observations, game-thread dispatch, exact loader/version provenance, and an empty-deny action vocabulary until game-specific handlers are reviewed.

from game_learning_runtime import EngineFamily, RuntimeIntegrationProfile

profile = RuntimeIntegrationProfile.for_source(EngineFamily.UNITY)
environment = profile.connect(authorized_driver)

Generate a Unity or Unreal adapter lane with the repository-owned Skill, then replace its synthetic semantics while keeping the contract tests green. See the engine runtime integration guide.

For no-source games that explicitly permit mods, GLR can generate a BepInEx 5 LTS Unity Mono host or a UE4SS 3.x Lua host:

vx python .agents/skills/glr-adapter-builder/scripts/scaffold_adapter.py `
  --output adapters/example_loader `
  --package example_loader `
  --environment-id example.loader-v1 `
  --engine unity `
  --access loader `
  --loader bepinex `
  --loader-version v5.4.23.5

The generated deployment command stages a checksummed payload; it never scans for or modifies a game installation. See the loader-plugin integration guide.

Runtime Host and engine providers

The implemented Runtime Host centralizes strict framing and lifecycle fencing without trying to replace engine bootstraps:

TorchRL / PPO / IMPALA / BC
  -> BridgeEnvironment -> HostBridgeDriver
  -> glr-hostd (Rust)
  -> C# Unity provider / C++ Unreal provider
  -> official plugin, BepInEx, UE4SS, or official mod SDK

Run the real cross-process conformance path and compile both provider contracts:

vx just host-smoke
vx just provider-sdk-check

glr-hostd currently ships only synthetic-counter over serialized stdio. It has a 1 MiB hard frame bound and never retries a mutating action, but it does not yet claim authenticated or target-bound IPC and cannot yet connect a live external C#/C++ provider. See the Runtime Host and provider SDK guide for the exact current boundary and Unity/Unreal implementation path.

Optional DeepSeek Harness

DeepSeekHarnessProvider is a separate, disabled-by-default control-plane provider for structured analysis, completion, or planning tasks. It does not alter learner-facing environment contracts, discover credentials, or grant runtime action authority. Explicit handlers receive bounded JSON tasks with permissions, deadlines, and idempotency keys; failures and timeouts are cached, and ordered events/state snapshots can be recovered through the optional LocalHarnessOrchestrator. See the DeepSeek Harness guide and configuration sample.

Reproducible local development

GLR pins Python, Node.js, uv, just, rustup, Rust, and .NET SDK inputs. Local development and GLR's GitHub Actions execute the same recipes:

vx setup
vx just dashboard-build dashboard-check
vx just check
vx just ci

Any agent or new contributor can bootstrap, run, test, and verify upstream alignment with one chain — see the agent onboarding guide:

vx setup && vx just layout-check && vx just core-check && vx just glr-doctor && vx just glr-fork-gate

Repository governance and unattended runs

Automation is owned by capability domain under tools/<domain>/ and registered in tools/registry.toml; vx just layout-check fails when a tool is unregistered or orphaned. Unattended training uses explicit scheduler-facing exit codes:

# Supervision pass: 0 healthy, 3 recovered, 4 escalated.
vx just glr-watchdog --source trainer --heartbeats .glr/heartbeats.jsonl --restart-attempt-limit 3

# Anti-fork gate: 0 aligned, 5 drifted from canonical upstream.
vx just glr-fork-gate

# Aggregate doctor: 0 every check passed, 4 at least one failed.
glr --project . doctor

A project can also pin the one entry point that is allowed to launch it, so an unattended agent cannot drift onto a stale launcher. glr doctor reports the attestation and fails on it only for a strict project — which is the one whose drifting runs are refused with exit code 79 before any budget is spent — see pin one entry point per project.

See repository layout, supervision and watchdog, the anti-fork gate, and the entry point guide.

Knowledge and rewards as data

from game_learning_runtime import (
    EpisodeRewardGuard,
    RewardSignal,
    load_reward_safety_config,
    load_training_config,
)

config = load_training_config("training.json")
guard = EpisodeRewardGuard(config, load_reward_safety_config("reward-safety.json"))
reward = guard.compose([RewardSignal(name="progress", source="runtime", value=0.25)])
print(reward.total, reward.contributions)

Runtime telemetry should be authoritative; web guides and strategy priors should be advisory. Reward terms require authoritative sources by default. Adapters may also use the learner-neutral runtime evidence contracts to record settled route edges, stall/oscillation telemetry, modal navigation boundaries, and trajectory/recording lineage. These records never control the adapter, widen action masks, or replace authoritative reward and terminal evidence. Configuration is data only: GLR does not evaluate reward expressions as code. KnowledgeInjector additionally validates bounded glr.knowledge-snapshot.v1 payloads and selects stage/tag-relevant acquire, engage, upgrade, and avoid advice into an immutable learner context. The learner owns encoding; the context never gains action or reward authority. The episode guard caps positive shaping per step and episode, requires an authoritative terminal outcome, and prevents a failed episode from retaining a positive return. DemonstrationGate separately rejects policy self-imitation, failed episodes, and unknown provenance from BC by default. See training safety.

Build an adapter with the Agent Skill

The repository-owned glr-adapter-builder Skill gives a new agent a bounded workflow for:

1. researching current game mechanics with source provenance;
2. separating physical reset from truthful live attach;
3. scaffolding a synthetic trainable seam;
4. defining knowledge, reward budgets, and BC provenance policy;
5. implementing fenced observations/actions through a runtime bridge; and
6. validating conformance before a bounded authorized runtime trace.

The Skill never turns web strategy into runtime authority and never treats a synthetic test as live-game acceptance.

Give the Skill to your agent

The fastest path is to clone this repository and start Codex from its root. Codex discovers repository skills under .agents/skills automatically. Invoke the workflow explicitly in your prompt:

$glr-adapter-builder Create an authorized Unity adapter with source access. Scaffold a trainable environment, research manifest, reward configuration, and contract tests.

For an authorized binary-only runtime, say external access. For an authorized mod-enabled runtime, name BepInEx or UE4SS and the exact compatible upstream tag. The Skill chooses truthful attach, denies unknown actions, and refuses source-only capability claims.

To use the Skill from another repository, ask Codex's built-in installer to install it from GitHub:

$skill-installer install https://github.com/loonghao/GameLearningRuntime/tree/main/.agents/skills/glr-adapter-builder

Start a new agent turn after installation, then invoke $glr-adapter-builder. Pin the GitHub URL to a release tag or commit SHA when you need a reproducible team setup. Agents that implement the open Agent Skills standard can instead place the same glr-adapter-builder directory under the target repository's .agents/skills/ directory. See the official Codex Skills documentation.

The generated lane includes the environment skeleton, training.json, reward-safety.json, demonstration-policy.json, runtime-integration.json, a provenance-aware research manifest, tests, Agent instructions, a model-bundle smoke trainer, vx.toml, and a justfile.

Distribute the skills as an Agent Plugin

For plugin-capable agents, this repository also ships the self-contained game-learning-runtime-skills plugin. Its .codex-plugin/plugin.json follows the Agent Plugin manifest contract and its skills/ payload contains the same glr-adapter-builder skill as the repository source. Copy or archive the plugin directory without changing its internal layout; a compatible host should resolve each skill relative to the plugin's skills/ directory. Pin the repository to a release tag or commit SHA when sharing it with a team.

The repo-local .agents/plugins/marketplace.json exposes the plugin as game-learning-runtime-skills for hosts that support Agent Plugin marketplaces. Point that host at the repository marketplace, then install the plugin by that name; other Agent Skills-compatible hosts can consume the same plugin directory directly.

For Codex CLI, the equivalent commands are:

codex plugin marketplace add loonghao/GameLearningRuntime
codex plugin add game-learning-runtime-skills@game-learning-runtime

Before publishing a change, verify that the distributable payload has not drifted from the repository-owned skills:

vx uv run python tools/packaging/package_agent_plugin.py --check

Maintainers can intentionally refresh the payload after editing a source skill with --sync, then rerun the check and the normal vx run check gates. The skill's bundled scripts and references are resolved from the installed skill root, so user-level plugin installs do not depend on a .agents/skills path in the consuming project.

Loader lanes also include bounded host source and a deployment manifest. From that generated directory, run:

vx setup
vx run check
vx run train
vx run reproduce

train emits a synthetic BC smoke model plus a self-contained checksummed reproduction environment. Replace the learner while preserving the glr.model-bundle.v1 gate; see reproducible model bundles.

For projects whose bridge already exists, use the separate glr-cli Skill. It teaches agents to configure and operate runtime, training capture, goal loops, history queries, knowledge transfer, verified playback, and explicitly authorized managed updates without changing adapter internals. Both Skills ship in every standalone GLR archive.

Distribute the skills as an Agent Plugin

For plugin-capable agents, this repository also ships the self-contained game-learning-runtime-skills plugin. Its .codex-plugin/plugin.json follows the Agent Plugin manifest contract and its skills/ payload contains the repository's glr-adapter-builder and glr-cli Skills. Copy or archive the plugin directory without changing its internal layout; a compatible host should resolve each Skill relative to the plugin's skills/ directory. Pin the repository to a release tag or commit SHA when sharing it with a team.

The repo-local .agents/plugins/marketplace.json exposes the plugin as game-learning-runtime-skills for hosts that support Agent Plugin marketplaces. Point that host at the repository marketplace, then install the plugin by that name; other Agent Skills-compatible hosts can consume the same plugin directory directly.

For Codex CLI, the equivalent commands are:

codex plugin marketplace add loonghao/GameLearningRuntime
codex plugin add game-learning-runtime-skills@game-learning-runtime

Before publishing a change, verify that the distributable payload has not drifted from the repository-owned Skills:

vx uv run python tools/packaging/package_agent_plugin.py --check

Maintainers can intentionally refresh the payload after editing a source Skill with --sync, then rerun the check and the normal vx run check gates. The Skills' bundled scripts and references are resolved from each installed Skill root, so user-level plugin installs do not depend on a .agents/skills path in the consuming project.

TorchRL and custom learners

Use the optional TorchRL adapter:

from game_learning_runtime.examples import CounterEnvironment
from game_learning_runtime.integrations.torchrl import TorchRLEnvironment

env = TorchRLEnvironment(CounterEnvironment())
rollout = env.rollout(max_steps=32)

Or reuse the masked PPO objective in a custom PyTorch learner:

from game_learning_runtime.integrations.torch_objectives import ppo_loss

terms = ppo_loss(
    policy_logits=logits,
    actions=actions,
    old_log_prob=old_log_prob,
    advantages=advantages,
    values=values,
    value_targets=value_targets,
    action_mask=action_mask,
)
terms.loss.backward()

Hybrid and multi-head learners can instead call ppo_loss_from_log_prob with their summed per-head log-probability and entropy tensors. GLR shares the PPO mathematics without owning the project's distributions, policy network, action encoding, or optimizer.

Reuse the CI workflow

Any uv-managed Python repository can call GLR's public reusable workflow:

jobs:
  quality:
    uses: loonghao/GameLearningRuntime/.github/workflows/reusable-python-ci.yml@v0.26.0 # x-release-please-version
    with:
      python-versions: '["3.10", "3.12"]'
      sync-args: "--frozen --all-groups"
      lint-command: "uv run ruff check . && uv run mypy"
      test-command: "uv run pytest"

Pin a release tag or commit SHA in production. Release Please keeps the example tag synchronized with package releases. The reusable workflow receives no deployment secrets and only checks out and tests the calling repository.

Releases

Conventional Commits on main create or update a Release Please pull request. Merging that reviewed PR creates the tag and GitHub Release, verifies and builds the tagged source, attaches provenance, publishes the Python distributions to PyPI through Trusted Publishing, and attaches checksummed unified GLR archives for Linux, Windows, Intel macOS, and Apple Silicon. Each archive contains the standalone Rust CLI, matching Runtime Host, install manifest, and both GLR Skills; the release also includes the C# provider package. See the release runbook.

Documentation

• Getting started
• Downstream Python quality and framework migrations
• Distribute a trained stage as a user installer
• Operate GLR as an agent-first control plane
• Build a reusable runtime bridge
• Connect Unity and Unreal runtimes
• Use the Runtime Host and C#/C++ provider SDKs
• Connect authorized BepInEx and UE4SS loaders
• Compose DSH-like declarative plugin bundles
• Start configured game instances before training
• Extend GLR with declarative VX tasks
• Standard agent-first CLI and query tables
• Reproduce trained models
• Build offline interactive run reports
• Normalize project output layout
• Record the training window on Windows
• Configure knowledge sources and rewards
• Enforce reward budgets and BC provenance
• Declare and audit adapter metrics
• Record why every episode ended
• Size the state-action space against the step budget
• Validate an adapter
• Adapt an existing Gymnasium environment
• Compose custom Torch objectives
• Architecture and data flow
• Local development
• Agent onboarding
• Repository layout and tool ownership
• Supervision and watchdog
• Anti-fork gate
• Pin one entry point per project
• Declare the environment a role receives
• Benchmark baseline
• Roadmap and architecture decisions

See CONTRIBUTING.md for the development contract and SECURITY.md for private vulnerability reporting. GLR is licensed under the MIT License.

Goal-driven QA

Run bounded checks against a human-readable objective and get a self-contained report grouped by local date:

# Install the package in the selected environment first: python -m pip install -e .
python -m game_learning_runtime.qa "inspect the whole game for bugs" `
  --project . `
  --check smoke python -c "print('adapter smoke ok')"

Each run is written to .glr-qa/YYYY-MM-DD/<UTC-time>/ with result.json and index.html. Checks are intentionally command based so an adapter can attach its own deterministic training, replay, or live-host probe while GLR keeps the goal, evidence, timeout, and report contract stable.

Goal-driven QA

Run bounded checks against a human-readable objective and get a self-contained report grouped by local date:

# Install the package in the selected environment first: python -m pip install -e .
python -m game_learning_runtime.qa "inspect the whole game for bugs" --project . --check smoke python -c "print('adapter smoke ok')"

Each run is written to .glr-qa/YYYY-MM-DD/<UTC-time>/ with result.json and index.html. Checks are command based so an adapter can attach deterministic training, replay, or live-host probes while GLR keeps the goal, evidence, timeout, and report contract stable.

Training dashboard and durable history

glr --project . dashboard

Training dashboard and durable history