> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcprize.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Arcade

> ARC-AGI 3 Client for Interactive Environments

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.

```python theme={null}
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")
)
```

<Note>
  All parameters are optional. See details below for each option.
</Note>

### `operation_mode`

Controls where games are loaded from. See [Local vs Online](/local-vs-online) for guidance on which mode to use.

| Mode                    | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `OperationMode.NORMAL`  | Load both local and remote games (default)              |
| `OperationMode.OFFLINE` | Load local games only — fast, no rate limits            |
| `OperationMode.ONLINE`  | Load remote games only — enables scorecards and replays |

```python theme={null}
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:

```bash theme={null}
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.

```python theme={null}
# 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](/api-keys) for setup instructions.

### `environments_dir`

Directory to scan for local game files (`metadata.json`). Default: `"environment_files"`.

```python theme={null}
arc = Arcade(environments_dir="./my_games")
```

Environment variable: `ENVIRONMENTS_DIR`

### `recordings_dir`

Directory to save game recordings in JSONL format. Default: `"recordings"`.

```python theme={null}
arc = Arcade(recordings_dir="./my_recordings")
```

Environment variable: `RECORDINGS_DIR`

### `arc_base_url`

Base URL for the ARC API. Default: `"https://three.arcprize.org"`.

```python theme={null}
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.

```python theme={null}
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:**

```python theme={null}
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:**

```python theme={null}
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:**

```python theme={null}
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:**

```python theme={null}
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:**

```python theme={null}
final_scorecard = arc.close_scorecard()
if final_scorecard:
    print(f"Final score: {final_scorecard.score}")
```