Fireboy and Watergirl AI Bridge

This repository contains the source code for a Windows-based automation and reinforcement learning setup for Fireboy & Watergirl: The Forest Temple running in Ruffle.

The public repo intentionally excludes local runtime artifacts such as training runs, captures, logs, cached Python files, and generated SWF variants. The original game SWF is included under Game Code/, and the scripts create runs/, captures/, logs/, and models/ as needed.

What is included

• bridge/: Vision, environment, overlay, trace-monitoring, and input control code.
• bridge/templates/: Template images used by the detector.
• Root training and evaluation scripts such as train.py, replay_episode.py, run_parallel_training.py, and stats_viewer.py.
• docs/: Notes on specific systems and experiments.
• fireboy_background_control.ahk: Optional AutoHotkey helper for background controls.

What is not included

• Derived/generated SWF variants and other local game copies.
• Local training runs, captured frames, replay outputs, and logs.
• Virtual environments, __pycache__, and other generated files.

Setup

1. Install Python and the dependencies in requirements-directml.txt.
2. Install Ruffle. By default the scripts look for C:\Program Files\ruffle\bin\ruffle.exe.
3. The repo includes the base SWF at Game Code/Fireboy & Watergirl - The Forest Temple.swf. You can still override it by setting FIREBOY_SWF_PATH.
4. If Ruffle is somewhere else, set FIREBOY_RUFFLE_PATH.

PowerShell example:

$env:FIREBOY_SWF_PATH = "D:\Games\Fireboy\Fireboy & Watergirl - The Forest Temple.swf"
$env:FIREBOY_RUFFLE_PATH = "C:\Program Files\ruffle\bin\ruffle.exe"
py train.py

Quick start

1. Run py main.py to verify the launcher, window detection, and templates.
2. Run py train.py to start the default training flow.
3. Run py stats_viewer.py to inspect progress.
4. Run py replay_episode.py --id <episode_num> to replay a saved episode.
5. Run py test_level.py --target-level 2_4 to jump directly to a level preview.

Parallel profile training

• Named profiles isolate models, logs, captures, and SWF copies under runs/<profile>/....
• Run one profile with py train.py --profile baseline --slot 0.
• Launch multiple workers with py run_parallel_training.py.
• Compare two profiles with py compare_profiles.py --left baseline --right experiment.
• Reset a profile with py reset_training.py.

Verification and debugging

• verify_exact_replay.py: Re-run a saved replay and compare it against recorded state.
• verify_replay_compatibility.py: Check that replay data is still usable after code changes.
• verify_live_debugger_dense.py: Collect dense debug output for live verification runs.
• verify_replay_overlay_alignment.py: Compare overlay rendering against replay output.
• verify_tracking_every_frame_batch.py: Sample replay frames for tracking review.
• verify_tracking_replays.py: Inspect tracking behavior across recorded replays.

Notes

• This project is currently Windows-focused.
• The game window should stay visible on screen for capture to work reliably.
• fireboy_background_control.ahk can be used as an AutoHotkey v2 helper for background input.