Game environments

An environment turns emulator frames into the observation, action and reward interface expected by Gymnasium. Each step applies an action and returns the next observation, reward and episode status.

Configuration files

Each environment needs three kinds of configuration:

• Game: the machine state, controls, game data and rules that define the task.
• Model: screenshot processing and the number of emulator frames between observations.
• Training: reward and episode rules for learning. This configuration is optional when the selected task does not need training rules.

Examples live alongside each game under experiments/games. Paths inside these files must refer to game data available on your machine.

Run a random agent

This example uses Batty's checked-in configuration. Run it from the repository root after providing the game files referenced by its YAML:

from pathlib import Path

import gymnasium as gym

from mrkwatkins.oakemu_rl.gymnasium import GameConfiguration, ensure_registered

configuration = Path("experiments/games/batty")
ensure_registered(
    configuration / "Game.yaml",
    configuration / "Model.yaml",
    configuration / "Training.yaml",
)

# The environment ID is the Name in Game.yaml.
name = GameConfiguration(configuration / "Game.yaml").name
environment = gym.make(name)
observation, info = environment.reset(seed=123)

for _ in range(100):
    observation, reward, terminated, truncated, info = environment.step(environment.action_space.sample())
    if terminated or truncated:
        observation, info = environment.reset()

environment.close()

You can also load GameConfiguration, ModelConfiguration and TrainingConfiguration directly and construct OakEmuEnv without registration.

Observations and actions

Observations are NumPy arrays. Their shape follows the model configuration and the selected dimension order: hwf means height, width and stacked frames; fhw places frames first.

Actions are integer indexes into the configured action list. The info dictionary contains game data reported for that step. A terminated episode reached a task boundary; a truncated episode stopped because of a limit.

OakEmuMultiEnv runs several environments together. Use the API reference for its batched interface.