Mini Runner

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

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, model 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/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.

Raw model I/O is written to __data1/agent-debug.log with local rotation.

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.
• Puzzle game: Lode Runner rules and puzzle-solving concepts.
• Assessment: high-level assessment of the legacy runtime.

Screenshots