How jvarzali/sokoban-environment works
Sokoban is a two-height-grid puzzle environment exposed as a step-based agent API, with a browser replay viewer for inspecting exported runs. The main workflow is: an agent resets an episode, receives a map observation, submits directional actions, and receives updated observations and an efficiency-based win reward. The environment loads authored maps and applies movement, ramp, and box rules. The viewer separately replays exported runs through a JavaScript engine and renders them in 2D or 3D. The graph follows documented wiring; some viewer module details are based on the README rather than sampled source.
Main entry points: env_sdk.py Episode HTTP Server · env.py Game Engine · app.js View Controller · replay.js Replay Playback
Components 17
Game Environment
- Game Engine
env.py - Movement Rules
env.py - Observations & Reward
env.py
Agent Interface
- HTTP Adapter
adapter.py - Episode HTTP Server
src/env_sdk.py
Puzzle Content
- Authored Maps
maps - Benchmark Config
benchanything.json - Agent Rules Prompt
system_prompt.txt
Replay Viewer
- Run Exports
docs/runs - Replay Playback
docs/replay.js - Replay Engine
docs/game.js - View Controller
docs/app.js - 2D Renderer
docs/view2d.js - 3D Renderer
docs/view3d.js - Bundled Maps
docs/maps.js
Other components
- Agent
- Mesocosm Platform
Connections 19
- Mesocosm Platform → Agent: provides prompt
- Mesocosm Platform → HTTP Adapter: sends episode requests
- HTTP Adapter → Episode HTTP Server: starts server
- Episode HTTP Server → Game Engine: routes reset/step
- Agent → Episode HTTP Server: submits actions
- Episode HTTP Server → Agent: returns results
- Game Engine → Authored Maps: loads maps
- Game Engine → Movement Rules: applies moves
- Game Engine → Observations & Reward: builds results
- Observations & Reward → Episode HTTP Server: returns observation/reward
- Benchmark Config → Mesocosm Platform: configures runs
- Agent Rules Prompt → Mesocosm Platform: supplies game rules
- Agent → Run Exports: produces run data
- Run Exports → Replay Playback: loads run
- Replay Playback → Replay Engine: re-simulates moves
- Replay Playback → View Controller: drives playback
- View Controller → 2D Renderer: controls view
- View Controller → 3D Renderer: controls view
- Bundled Maps → View Controller: provides maps