env-breakoutatari2600-turbo-native 0.5.8

🕹️ Blazing-fast, deterministic Breakout for Reinforcement Learning 🕹️

env-BreakoutAtari2600-turbo-native is a Python library for reinforcement-learning researchers and engineers who need many reproducible Breakout games behind one Gymnasium vector-environment API. Add it to a uv project from PyPI, create BreakoutVecEnv, and step every lane with one NumPy action batch.

Fixed-point Rust physics owns game state and parallel stepping. Python exposes manual reset, policy-ready observations, rendered frames, exact snapshots, and side-effect-free action branching.

Install

Requires Python 3.11+ on Apple-silicon macOS 11+ or x86-64 Linux with glibc 2.28+.

Install uv, then add the library to your project:

uv add env-breakoutatari2600-turbo-native

Choose the corresponding requirement instead when you need an optional tool:

uv add "env-breakoutatari2600-turbo-native[play]"  # interactive Pygame player

To work from source, also install a Rust toolchain, then run:

git clone https://github.com/tsilva/env-BreakoutAtari2600-turbo-native.git
cd env-BreakoutAtari2600-turbo-native
uv sync --frozen --extra dev --extra play
make develop-release

Use

import gymnasium as gym
import numpy as np

env = gym.make_vec(
    "env_breakoutatari2600_turbo_native:EnvBreakoutAtari2600TurboNative-v0",
    game="Breakout-Atari2600-v0",
    num_envs=4096,
    num_threads=8,
)
obs, infos = env.reset()
obs, rewards, terminated, truncated, infos = env.step(
    np.zeros(env.num_envs, dtype=np.uint8)
)

done = terminated | truncated
if done.any():
    obs, reset_infos = env.reset(options={"reset_mask": done})

The module-qualified ID imports the package and registers the factory. This ID is vector-only and requires an explicit game; BreakoutVecEnv remains available for direct use.

Train with GradLab

Training recipes and implementations live in GradLab, keeping this repository focused on the environment. Run a published recipe from any directory without installing GradLab or cloning either repository.

For the default high-throughput PPO recipe:

uvx gradlab@0.1.1 train Breakout-Atari2600-v0/ppo

For PPO with learning-rate decay and KL-based update stopping:

uvx gradlab@0.1.1 train Breakout-Atari2600-v0/ppo-stable-updates

env-BreakoutAtari2600-turbo-native is ROM-free, so neither command needs a ROM path or registration. GradLab shows live progress, writes a playable final_model.zip below ./runs, and prints the matching version-pinned uvx ... play command when training finishes or is stopped safely. Local runs disable W&B and checkpoint evaluation by default, so they cannot establish acceptance or promotion. These are full-cap research recipes rather than short timed demos.

Turbo Vector API v2

BreakoutVecEnv implements the strict Turbo Vector API v2:

• metadata["turbo_api_version"] is 2, metadata["transition_transport"] is "numpy", and metadata["render_modes"] advertises rgb_array.
• Immutable capabilities and signal_schema declarations describe supported features and the dtype, shape, and reset/step availability of every signal.
• capabilities["supported_filtered_actions"] discloses the exact noop, FIRE, right, and left eight-button rows accepted by the filtered action transport.
• buttons, action_mode, action_preset, action_table, action_meanings, and action_table_hash expose the resolved action semantics without provider-specific probing.
• state_catalog is an immutable ordered tuple. Callers select reset states with an int32 state_indices array and inspect the read-only active indices with active_state_indices(); state sampling and lane routing remain caller-owned.
• observation_ownership and observation_buffer_depth declare the exact lifetime of returned observations. Rendering is opt-in: with render_mode="rgb_array", render_lane(index) renders one lane, get_images() renders all lanes, and render() renders lane zero. With the default render_mode=None, the first two methods return None and get_images() returns one None entry per lane.

Interesting live positions can be archived without advancing the game and restored into any lane of the same environment:

capture_mask = np.zeros(env.num_envs, dtype=np.bool_)
capture_mask[0] = True
captured = env.capture_snapshots(capture_mask)

restore_mask = np.zeros(env.num_envs, dtype=np.bool_)
restore_mask[3] = True
starts = [None] * env.num_envs
starts[3] = captured[0]
obs, infos = env.reset(
    options={"reset_mask": restore_mask, "snapshots": starts},
)
env.close()

Importing the package also preserves the Stable Retro Turbo-compatible Breakout-Atari2600-v0 vector ID. The complete lifecycle, configuration, snapshot, and branching contract is in the environment documentation.

Stable-Baselines3 users can wrap the already-vectorized environment with the optional, explicitly auto-resetting adapter described in the environment documentation. SB3 remains a separate install and is not part of the core dependency set.

Commands

uv run --frozen --extra play env-breakoutatari2600-turbo-native play       # open the player
uv run --frozen --extra play env-breakoutatari2600-turbo-native play --uncapped
uv run --frozen ruff check .                               # lint Python
uv run --frozen pytest -m "not stable_retro"               # run regular Python tests
cargo test --locked --lib                                  # run Rust tests
RETRO_DATA_PATH=/lawful/stable_retro/data make test-semantic-oracle ORACLE_RECEIPT=/external/oracle.json  # certify pinned Turbo parity

Append --help to the player command for its options. Matched performance comparisons are provided by TurboBench, not by this repository.

Notes

• Native actions are 0 noop, 1 FIRE, 2 right, and 3 left. The default policy observation is grayscale uint8, CHW, and shaped (num_envs, 4, 84, 84).
• Filtered actions use int8 batches shaped (num_envs, 8). Only the exact binary noop, FIRE, right, and left rows disclosed by capabilities["supported_filtered_actions"] are accepted; unsupported buttons, combinations, dtypes, shapes, and values reject the whole batch before any lane advances.
• Rewards are score deltas using Atari row scoring. There is no life-loss or board-clear shaping. The cartridge presents two walls: the first refills after the next paddle return, the second ends at score 864 without another refill, and only losing all five lives terminates the episode.
• Autoreset is disabled. Reset terminated lanes explicitly with a Boolean reset_mask; unselected lanes remain byte-exact.
• With noop_reset_max=N, each static reset samples a seeded inclusive count from 1..N and advances that many native console frames with noop, matching the conventional Atari reset distribution. FIRE is not issued automatically: use_fire_reset remains unavailable and the policy must start each serve.
• The canonical Start state targets Stable Retro Turbo's 160×210 native indexed frame, lifecycle, physics, raster, rewards, collision behavior, and public trajectory values. In particular, ball_y uses the Atari RAM convention where zero means the serve is waiting for FIRE. Opt into rendered frames with render_mode="rgb_array"; render() then returns lane zero's canonical Stella RGB rendered frame while render_lane(index) selects any lane, separately from policy observations. Stable Retro Turbo's inherited BGR-labeled RGB565 transport is normalized only at this human-facing boundary.
• Live validation requires a separately obtained lawful ROM. The sole semantic oracle is the Stable Retro Turbo vector provider selected by validation/stable-retro-turbo.json. make test-semantic-oracle ORACLE_RECEIPT=/external/oracle.json is the sole certifying command; its fixed workload receipt binds the exact clean checkout or published candidate, configuration, provider pin, and comparison result. Configurable pytest runs are diagnostic only and cannot create a receipt. Releases accept only receipts generated and provenance-attested by the protected manual Stable Retro Turbo oracle evidence workflow; arbitrary uploaded or caller-authored JSON has no release authority. No provider package, ROM, save state, or recorded reference frame is distributed by this project.
• Only Apple-silicon macOS and x86-64 Linux are supported. See support and release validation for exact boundaries.
• The specification compliance matrix maps every project requirement to its maintained executable or non-code evidence.
• The project is a 0.x community preview. Public changes are recorded in the changelog. Serialized get_state() snapshots are portable only within the same package version and compatible configuration; live snapshot handles are session-local and intentionally not pickleable.

Architecture

License

MIT. See third-party notices for Atari, Stable Retro, ROM, and trademark boundaries.