Game Learning Runtime

Game Learning Runtime (GLR) is a framework-neutral contract between game runtimes and learning systems. A game adapter describes observations, actions, action masks, rewards, events, and episode boundaries once; TorchRL, custom PPO or IMPALA learners, behavior cloning, offline datasets, evaluators, and QA tools can then consume the same interface.

A universal runtime for connecting games to learning systems and AI agents.

GLR is intended 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 this boundary

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 never needs to know whether the game is Unity, Unreal, Source, native, or a test simulator. The standardized boundary is the data and lifecycle contract, not a single implementation language or transport.

Current capabilities

• Recursive tensor-tree specs for continuous, discrete, multi-discrete, binary, hybrid, parameterized, and hierarchical data.
• A GameEnvironment port with reset, step, close, action masks, semantic events, terminated/truncated signals, episode IDs, and monotonic step IDs.
• A fail-closed ContractEnvironment wrapper that validates every boundary.
• Capability-gated live attachment for continuing games that cannot claim a physical or deterministic reset.
• Transport-neutral BridgeDriver, BridgeEnvironment, and EnvironmentBridgeDriver ports for authenticated local HTTP, socket, named-pipe, gRPC, or native transports.
• Strict glr.training.v1 JSON configuration for bounded authoritative or advisory knowledge sources, reset/attach collection policy, required bridge capabilities, and auditable weighted reward terms.
• A data-only RewardComposer that rejects missing, unknown, wrong-source, or non-finite signals and never evaluates configuration as code.
• Fixed-length or terminal-bounded actor Unroll collection suitable for custom PPO and IMPALA.
• Versioned glr.transition.v1 JSONL records for BC, replay, and offline data.
• A packaged glr.v1 Protobuf service with unary and bidirectional streaming interaction contracts.
• An optional TorchRL EnvBase adapter tested against TorchRL 0.13.
• Optional, model-neutral PyTorch objectives for masked BC, PPO/GAE, and IMPALA/V-trace custom learners.
• A privacy-safe adapter conformance runner plus synthetic turn-based, real-time combat, FPS, and ARPG contract profiles.
• A project-owned glr-adapter-builder Agent Skill that scaffolds a runnable synthetic adapter lane, gameplay-research provenance, reward configuration, and reset/attach conformance tests.

Game-specific runtime adapters, concrete transport packages, generated C#/C++/Rust protocol SDKs, distributed actor transport, complete trainers, and reference model architectures remain roadmap items.

Install

Install the core package from PyPI:

uv add game-learning-runtime

Add the TorchRL integration only where training requires it:

uv add "game-learning-runtime[torchrl]"

Use the reusable objectives in a custom PyTorch learner without TorchRL:

uv add "game-learning-runtime[torch]"

Reuse an existing Gymnasium environment without writing another TorchRL adapter:

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

Pin a PyPI version or immutable GitHub release tag when reproducibility requires an exact build.

Minimal environment

import numpy as np

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 adapter bound to an already-running game, advertise live-attach and select the lifecycle explicitly:

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

Attach creates a fresh logical GLR episode at step zero. It never implies that the game world was reset or seeded. stop_on_done=True keeps a long-running live-game unroll from silently continuing into a second physical episode; the default remains fixed-length collection across resets.

Define knowledge and reward policy without executable expressions:

from game_learning_runtime import RewardComposer, RewardSignal, load_training_config

config = load_training_config("training.json")
reward = RewardComposer(config).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. The project Skill at .agents/skills/glr-adapter-builder shows new agents how to research current gameplay, preserve provenance, scaffold a trainable seam, and validate the bridge without publishing local or proprietary information.

Run the complete example from a clone:

uv sync --frozen
uv run python -c "from game_learning_runtime import *; from game_learning_runtime.examples import *; print(SyncCollector(ContractEnvironment(make_environment())).collect(always_increment, steps=4).total_reward)"

For TorchRL:

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

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

For a custom masked PPO update:

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()

Reuse the CI workflow

Any uv-managed Python repository can call the public reusable workflow:

jobs:
  quality:
    uses: loonghao/GameLearningRuntime/.github/workflows/reusable-python-ci.yml@v0.2.0
    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 repositories. The workflow never receives deployment secrets and only checks out/tests the calling repository.

Documentation

• Getting started
• Adapt an existing Gymnasium environment
• Compose custom Torch objectives
• Validate an adapter with the conformance runner
• Build a reusable runtime bridge
• Configure knowledge sources and rewards
• Architecture
• Protocol and data flow
• Local development
• Data-plane benchmark baseline
• Release runbook
• Roadmap
• Architecture decisions

Contributing and security

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