The browser and Python share the same maze generation, action rules, and WebGL renderer. A Python environment is independent of the playable browser tab.
python -m pip install -e '.[render]' python -m playwright install chromium
Python 3.9+ and Node.js 18+ are required. Rendering starts an isolated headless browser only when render() is first called. It accesses local assets and requires no model key.
from mirror_maze import MirrorMaze
with MirrorMaze(topology="hex", difficulty="easy", seed="MIRROR-042") as env:
png = env.render(width=1280, height=720)
result = env.perform(["left", "forward"], stop_on_collision=False)
print(result["results"])| Method | Behavior |
|---|---|
MirrorMaze(...) | Create and initialize an independent environment. Topologies: square, triangle, hex. Difficulties: easy, medium, hard. Default reflections: 10. |
initialize(...) / reset(...) | Restart. Omitted parameters retain their values. Difficulty selects side length 7/11/15; an explicit side_length accepts integers 2–31. |
render(path=None, width=960, height=600) | Return PNG bytes, optionally writing a file. The default view is first person with no map or HUD. view="minimap" and view="review" are for human inspection. Rendering does not change state. |
perform(action_or_sequence) | Execute left, right, or forward. By default the sequence stops at its first collision, retaining the executed prefix. Set stop_on_collision=False to continue. |
preview_sequence(actions) | Inspect executability without mutating the episode. This reveals future feasibility and is not exposed to agents in the formal visual protocol. |
info() / state() | Public configuration, rules, counters, and terminal status. Hidden position, heading index, goal, and the map are omitted. |
export_episode(path=None) | Privileged review data: geometry, pose, goal, actions, and render history. Do not pass this to a vision-only agent. |
debug_solution() | A privileged shortest action sequence from the current state to the goal. |
close() | Close the worker, rendering browser, and temporary local server. Prefer a context manager. A rendering instance must be used and closed on its creating thread. |
collisionType distinguishes a wall from a triangle vertex. blockedAt is a zero-based sequence index. allExecutable is false if any action is blocked; completed only describes whether all actions were accepted. Invalid actions are rejected before any sequence action runs.
| Topology / outline | Easy: side 7 | Medium: side 11 | Hard: side 15 |
|---|---|---|---|
| Square / square | 49 | 121 | 225 |
| Triangle / hexagon | 294 | 726 | 1,350 |
| Hexagon / hexagonal arrangement | 127 | 331 | 631 |
Triangle turns are 60° and preserve heading when crossing a cell edge. Cell-center spacing is 2.6. The default is 10 reflections, with at most 12 reflections and 160 segments per ray.
Reproduction requires the same environment version, seed, size, resolution, mirror settings, and assistance policy. GPU/browser differences may cause pixel-level differences.