Skip to content

About

An LLM-based game agent plays a classic puzzle game.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Mini Runner

Mini Runner is an LLM-driven game agent for Lode Runner Total Recall, an HTML5 remake of the classic 1983 game Lode Runner. The project preserves the original game as the authoritative executor while adding a candidate agent, recording and replay tools, an agent evaluator, and a trace dashboard for decision-level debugging.

Architecture

  • Legacy game engine: public/game/* owns physics, guard behavior, digging, death, level completion, rendering, demo recording, and demo playback.
  • Wrapper frontend: src/* provides Vite bootstrapping, AI controls, stored-run playback, trace-aligned stepping, and the debug overlay.
  • Python backend: app.py exposes Flask APIs for planning, recordings, traces, model profiles, and local JSON stores.
  • Candidate agent: agent/* analyzes each snapshot, generates and scores legal actions, asks the LLM to choose a candidate ID, validates the choice, and translates it into legacy key/tick input.
  • Trace tooling: trace-dash.py provides a read-only Streamlit and pandas view of retained runs, individual decisions, outcomes, loop events, and candidate selection.
public/game/*             Legacy Lode Runner runtime, levels, rendering, and demos
src/*                     Vite wrapper, recording/playback UI, and browser agent loop
agent/*                   Analysis, candidate generation, prompting, validation, and traces
app.py                    Flask APIs for planning, tracing, and recordings
trace-dash.py             Streamlit and pandas agent-trace dashboard
scripts/*                 Sanity checks, evaluator, and offline trace analytics
__data1/                  Local recordings, traces, evaluation reports, and debug logs

Getting Started

Prerequisites

  • Node.js
  • Python 3.11+
  • An API key for one supported LLM provider

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. For example:

AGENT_MODEL_PROFILE=openai
OPENAI_MODEL=gpt-5-nano
OPENAI_API_KEY=your_openai_api_key

Supported profiles are openai, minimax, and gemini. Secrets belong in .env or .env.local; non-secret experiment controls belong in public/agent-config.json.

The browser URL can override the configured profile for runs started from that page:

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

Start Game

Start the backend and frontend in separate terminals:

npm run api
npm run dev

Open http://localhost:8283. Click AI to start or cancel an agent run. Use Play, Prev, Next, and Delete to inspect retained recordings.

Trace Dashboard

Use the read-only trace dashboard to compare runs and inspect each decision: state, candidates, model request, backend selection, issued input, and observed result. It reads existing stores without requiring the frontend or backend.

Start it in another terminal with the Python environment activated:

npm run dash

Open http://localhost:8601. It reads __data1 by default; use AGENT_DATA_DIR or the sidebar path to choose another folder. Press Reload data after the JSON changes. See Trace dashboard.

Observability And Local Data

The wrapper stores replayable demos in __data1/recordings.json. Agent recordings link to decision traces in __data1/agent-traces.json through traceId. See Trace API and store for stored data.

Set AGENT_DEBUG_LOG=1 to write the latest 10 raw model I/O turns to __data1/agent-debug.log. Raw prompts and model responses are excluded from normal traces.

For aggregate offline analysis, trace-analytics.ipynb reads recordings, runs, steps, candidates, outcomes, loop events, and fallbacks without changing them.

To launch the trace notebook interface, run npm run notebook and open http://127.0.0.1:8081/.

Testing And Evaluation

Sanity checks

Run the backend and frontend quick checks with:

npm test

These smoke checks use small fixtures and the Flask test client. They make no model calls.

Command Purpose
npm test Fast code smoke checks
npm run test:regression Focused Python and JavaScript regressions
npm run data:check Read-only checks of local recordings, traces, cohorts, and debug log
npm run cohorts:check Check cohort links and uncataloged traces

See Testing for coverage and limitations.

Agent evaluator

Run repeatable attempts against the real browser game and configured model:

npm run eval -- --runs 5

Use npm run eval -- --smoke to verify the browser, wrapper, backend, and legacy runtime without calling the model. See Agent evaluator.

Documentation

Screenshots

Screenshot 1 Screenshot 2

Credits

The game runtime is based on SimonHung/LodeRunner_TotalRecall.

About

An LLM-based game agent plays a classic puzzle game.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages