Mini Runner

An LLM-based game agent plays Lode Runner Total Recall, an HTML5 remake of the classic 1983 game Lode Runner.

Technical Highlights

• Game Engine: Preserves the legacy CreateJS runtime with bundled levels and demo data under public/game/*.
• Wrapper Frontend: Vite app with an overlay UI for AI play, leveraging the legacy game as executor, recorder, renderer, and playback engine.
• Python Backend: Flask APIs for recordings, traces, agent calls, model profiles, and local JSON stores.
• Candidate Agent: Backend generates legal candidate actions, the LLM chooses one candidate id, and the backend translates it into legacy key/tick input.

Project Structure

public/game/*             # Legacy Lode Runner runtime, physics, rendering, demo engine
src/*                     # Vite entrypoint, record & playback UI, game-loop, agent control
agent/*                   # Candidate generation, prompting, model calls, stall handling
app.py                    # Flask APIs for agent planning, tracing, and recordings
__data1/                  # Local JSON gameplay recordings, agent traces, and debug logs

The legacy codebase remains the source of truth for game physics, guard behavior, digging, death, level completion and god mode. All development happens in the wrapper and the backend. Legacy files only need to expose existing runtime state.

Getting Started

Prerequisites

• Node.js
• Python 3.11+
• One supported LLM provider key

Install dependencies

git clone https://github.com/tombay3/mini-runner.git
cd mini-runner

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

npm install

Configure a model

Create .env.local with one model profile. Example using OpenAI:

AGENT_MODEL_PROFILE=openai
OPENAI_MODEL=gpt-4.1-mini
OPENAI_API_KEY=your_openai_api_key

Start the backend

npm run api

Start the frontend

npm run dev

Open http://localhost:8283.

Click AI to start or cancel an agent run. Use Play, Prev, Next, and Delete to inspect stored recordings.

Configure Model Profiles

Supported profiles:

• openai
• minimax
• gemini

You can override the active profile from the browser URL:

http://localhost:8283/?profile=minimax

Model secrets live in .env or .env.local. Experiment control knobs live in public/agent-config.json.

Observability

The wrapper stores retained runs in __data1/recordings.json in legacy demo format. Agent runs link to trace data in __data1/agent-traces.json.

Set AGENT_DEBUG_LOG=1 to write the latest 10 raw model I/O turns to __data1/agent-debug.log.

scripts/trace-analytics.ipynb provides read-only pandas/matplotlib analysis of retained recordings, runs, steps, candidates, outcomes, and stalls.

Sanity Tests

Run the lightweight backend/frontend sanity checks with:

npm test

These tests use direct helper and Flask test-client checks. They do not run the legacy game engine or call the LLM.

Documentation

• Codebase overview: architecture, boot flow, and module map.
• LLM agent: candidate agent, snapshot flow, prompt, and stall handling.
• Candidate design: scoring, coverage, failure classification, and validation.
• Backend spec: Flask APIs, JSON stores, model profiles, and logging.
• Recording and playback: wrapper rail, run selection, pause/step controls, and fullscreen behavior.
• Sanity tests: quick backend/frontend regression checks.
• Puzzle game: Lode Runner rules and puzzle-solving concepts.
• Legacy runtime: the original CreateJS game architecture and features.

Screenshots

Credits

The game runtime is based on SimonHung/LodeRunner_TotalRecall.