proteus/game/engine/README.md

proteus.game.engine

The game engine subpackage for PROTEUS. Wraps the vendored ARC-AGI 64×64 grid/sprite engine (arcengine/) with PROTEUS-specific layers: grid game logic, difficulty scaling, ASCII visualization, and the core renderer.

proteus/game/engine/
├── __init__.py        # re-exports the full public surface (engine + renderer)
├── rendering.py       # visualization: 16-color palette, frame -> RGB / terminal
├── grid.py            # MotiveGridGame: PROTEUS grid game subclass of ARCBaseGame
├── difficulty.py      # difficulty scaling helpers
├── ascii_view.py      # ASCII/ANSI terminal view utilities
└── arcengine/         # vendored engine (arcprize/ARCEngine, MIT)
    ├── enums.py       # FrameData / FrameDataRaw, GameAction, GameState, color/mode enums
    ├── sprites.py     # Sprite: the pixel-grid primitive (rotation, scale, collision)
    ├── interfaces.py  # RenderableUserDisplay / ToggleableUserDisplay (UI overlays)
    ├── camera.py      # Camera: sprites -> 64×64 frame (auto-scale + letterbox)
    ├── level.py       # Level: a group of sprites + placeable areas
    ├── base_game.py   # ARCBaseGame: the turn-based game loop
    ├── OVERVIEW.md    # engine design notes
    ├── LICENSE        # MIT (ARC Prize Foundation)
    └── py.typed

What's the "grid"?

A frame is a list of layers; each layer is a 64×64 array of integers 0–15 (palette indices). Two representations of the same data live in arcengine/enums.py:

Type	frame field	Use
FrameData (pydantic)	list[list[list[int]]]	JSON / wire format
FrameDataRaw	list[numpy.ndarray] (int8)	runtime format

Engine invariants: 64×64 output · 16 colors · 6 actions + RESET · turn-based · each input yields 1–N frames.

Dependencies

Need	Requires
Engine (proteus.game.engine.arcengine)	numpy, pydantic
Renderer core (frame_to_rgb_array, COLOR_MAP)	numpy
Animated display (render_frames)	matplotlib (optional; guarded by a try-import)

pip install numpy pydantic        # minimum
pip install matplotlib            # only if you use render_frames()

Usage

Draw a raw 64×64 grid (engine not required)

import numpy as np
from proteus.game.engine import frame_to_rgb_array, COLOR_MAP

frame = np.zeros((64, 64), dtype=np.int8)
frame[10:20, 10:20] = 8           # a red square (palette index 8)

rgb = frame_to_rgb_array(0, frame, scale=4)   # -> (256, 256, 3) uint8
# COLOR_MAP maps each 0–15 index to its hex color.

Render in the terminal

from proteus.game.engine import render_frames_terminal
from proteus.game.engine import FrameDataRaw, GameState

fd = FrameDataRaw()
fd.frame = [frame]                # list of 64×64 arrays
fd.state = GameState.NOT_FINISHED
render_frames_terminal(0, fd)     # ANSI true-color, in-place

Build a game with the engine

from proteus.game.engine import ARCBaseGame, Camera, Level, Sprite

# Subclass ARCBaseGame, populate Levels with Sprites, drive it with GameActions.
# See arcengine/OVERVIEW.md and the upstream examples for the full loop.

Provenance

• Engine — vendored verbatim from the arcengine pip package (v0.9.3). Internal imports are all relative, so the folder works unmodified inside arcengine/.
• Renderer — copied from the ARC-AGI toolkit's arc_agi/rendering.py; the single external import from arcengine import FrameDataRaw was changed to the relative from .arcengine import FrameDataRaw so the subpackage is self-contained.

The arcengine/ boundary is preserved: to keep the engine fresh, re-vendor from upstream (arcprize/ARCEngine) or swap arcengine/ for a pip dependency on arcengine. No changes outside this subpackage are needed.

Attribution & License

The arcengine/ subpackage is vendored from arcprize/ARCEngine, © 2026 ARC Prize Foundation, MIT License (see arcengine/LICENSE). The renderer originates from the ARC-AGI toolkit (same foundation). Retain these notices when redistributing.