Skip to main content
The Arcade class is the main entry point for interacting with ARC-AGI-3 environments. It handles configuration, environment discovery, and scorecard management.

​
Constructor Parameters

The Arcade constructor accepts the following parameters. All parameters can be overridden by environment variables, with constructor arguments taking precedence. 
from arc_agi import Arcade, OperationMode
import logging

arc = Arcade(
    operation_mode=OperationMode.OFFLINE,
    arc_api_key="your-api-key",
    environments_dir="./my_games",
    recordings_dir="./my_recordings",
    arc_base_url="https://three.arcprize.org",
    logger=logging.getLogger("my_agent")
)
All parameters are optional. See details below for each option.

​
operation_mode

Controls where games are loaded from. See Local vs Online for guidance on which mode to use.
ModeDescription
OperationMode.NORMALLoad both local and remote games (default)
OperationMode.OFFLINELoad local games only — fast, no rate limits
OperationMode.ONLINELoad remote games only — enables scorecards and replays
from arc_agi import Arcade, OperationMode

# Default: both local and remote games
arc = Arcade()

# Local only (recommended for development)
arc = Arcade(operation_mode=OperationMode.OFFLINE)

# Remote only (for scorecards and replays)
arc = Arcade(operation_mode=OperationMode.ONLINE)
You can also set this via environment variable: 
export OPERATION_MODE=OFFLINE

​
arc_api_key

API key for the ARC API. Required for ONLINE mode. If empty and not in offline mode, an anonymous key will be automatically fetched. 
# Explicitly set API key
arc = Arcade(arc_api_key="your-api-key")

# Or use environment variable (recommended)
# export ARC_API_KEY="your-api-key"
arc = Arcade()
See API Keys for setup instructions.

​
environments_dir

Directory to scan for local game files (metadata.json). Default: "environment_files". 
arc = Arcade(environments_dir="./my_games")
Environment variable: ENVIRONMENTS_DIR

​
recordings_dir

Directory to save game recordings in JSONL format. Default: "recordings". 
arc = Arcade(recordings_dir="./my_recordings")
Environment variable: RECORDINGS_DIR

​
arc_base_url

Base URL for the ARC API. Default: "https://three.arcprize.org". 
arc = Arcade(arc_base_url="https://custom-endpoint.example.com")
Environment variable: ARC_BASE_URL

​
logger

Optional logger instance. If not provided, a default logger logging to STDOUT is created. 
import logging

my_logger = logging.getLogger("my_agent")
arc = Arcade(logger=my_logger)

​
Methods

​
make()

Create and initialize an environment wrapper for a specific game. Signature: make(game_id, seed=0, scorecard_id=None, save_recording=False, render_mode=None, renderer=None) Parameters:
  • game_id (str): Game identifier in format 'ls20' or 'ls20-1234abcd'. The first 4 characters are the game_id, everything after '-' is the version.
  • seed (int, optional): Random seed for the game. Defaults to 0.
  • scorecard_id (str, optional): Scorecard ID for tracking runs. If None is provided (the default), the system will create and maintain a single default scorecard that is automatically reused across all make() calls. This allows you to track multiple games in the same scorecard without explicitly managing scorecard IDs.
  • save_recording (bool, optional): Whether to save recordings to JSONL file. Defaults to False.
  • render_mode (str, optional): Render mode string ("human", "terminal", "terminal-fast"). If provided, creates a renderer automatically.
  • renderer (Callable[[int, FrameDataRaw], None], optional): Custom renderer function. If both render_mode and renderer are provided, renderer takes precedence.
Returns:
  • EnvironmentWrapper or None: Returns an EnvironmentWrapper instance if successful, None otherwise.
Example: 
env = arc.make("ls20", render_mode="terminal")
env = arc.make("ls20-1234abcd", seed=42, save_recording=True)

​
get_environments()

Get the list of available environments (both local and remote). Returns:
  • list[EnvironmentInfo]: List of EnvironmentInfo objects representing available environments.
Example: 
envs = arc.get_environments()
for env in envs:
    print(f"{env.game_id}: {env.title}")

​
create_scorecard()

Create a new scorecard for tracking game runs. Signature: create_scorecard(source_url=None, tags=None, opaque=None) Parameters:
  • source_url (str, optional): Optional source URL for the scorecard.
  • tags (list[str], optional): Optional list of tags for the scorecard. Defaults to ["wrapper"].
  • opaque (Any, optional): Optional opaque data for the scorecard.
Returns:
  • str: The ID of the newly created scorecard.
Example: 
scorecard_id = arc.create_scorecard(
    source_url="https://github.com/my/repo",
    tags=["experiment", "v1"]
)

​
open_scorecard()

Alias for create_scorecard(). Opens a new scorecard. Signature: open_scorecard(source_url=None, tags=None, opaque=None) Parameters: Same as create_scorecard(). Returns:
  • str: The ID of the newly created scorecard.

​
get_scorecard()

Get a scorecard by ID, converted to EnvironmentScorecard. Signature: get_scorecard(scorecard_id=None) Parameters:
  • scorecard_id (str, optional): Scorecard ID. If None is provided (the default), returns the default scorecard that the system is currently using (the same one created automatically when make() is called with scorecard_id=None).
Returns:
  • EnvironmentScorecard or None: Scorecard object if found, None otherwise.
Example: 
scorecard = arc.get_scorecard()
if scorecard:
    print(f"Score: {scorecard.score}")
    print(f"Games played: {len(scorecard.games)}")

​
close_scorecard()

Close a scorecard and return the final scorecard data. Signature: close_scorecard(scorecard_id=None) Parameters:
  • scorecard_id (str, optional): Scorecard ID. If None is provided (the default), closes the default scorecard that the system is currently using (the same one created automatically when make() is called with scorecard_id=None). After closing, the default scorecard is cleared and a new one will be created on the next make() call.
Returns:
  • EnvironmentScorecard or None: Final scorecard object if found, None otherwise.
Example: 
final_scorecard = arc.close_scorecard()
if final_scorecard:
    print(f"Final score: {final_scorecard.score}")