Red Ball Render Tools

This repository contains tools for rendering a robust, visual leaderboard of TAS-transcribed Red Ball speedruns, including combined level playback, splits, and audio.

Setup

1. Clone the repository to your local machine.
2. Install Miniforge: Download and install from conda-forge.org.
3. Initialize Conda: Open the Miniforge prompt and run:

   conda init

4. Create Environment: Set up the conda environment using the provided YAML file:

   conda env create -f redball_render.yml

5. Activate Environment:

   conda activate redball_render

6. VS Code Setup: If using Visual Studio Code, open a Python file and select Python 3.13 (redball_render) as the Python interpreter.

Usage

Python Scripts

render_combined_leaderboard.py

Visualizes gameplay for a specific level, combining multiple players/ghosts. It renders the playback as a .png sequence, ready for import to video editing software.

Command:

python render_combined_leaderboard.py [level] [options]

Arguments:

• level: The level number to render (1-12). Default: 1.
• --start_frame: Frame number to start rendering from. Default: 0.
• --interpolation_steps: Number of frames to generate between keyframes for smoother motion. Default: 0.
• --render_scale: Resolution scale factor (relative to default game size). Default: 2.
• --preview: Run in preview mode (opens a window) instead of saving to disk.
• --json: Sub-directory in json/ folder containing the run data. Default: combinedRTA/top10.

render_sidebar.py

Generates the sidebar overlay showing the timer, player splits, and time deltas against the World Record.

Command:

python render_sidebar.py [options]

Arguments:

• --duration: Total duration of the sidebar render in seconds. Default: 180.0.
• --preview: Show the sidebar in a window instead of exporting.
• --scale: Size scale of the sidebar. Default: 1.0.
• --start_time: Time offset to start the timer at. Default: 0.0.

render_sounds.py

Synthesizes a combined audio track by mixing game sound effects triggered by the event data in the player JSON files.

Command:

python render_sounds.py [options]

Arguments:

• --json: Sub-directory in json/ folder containing the run data. Default: combinedRTA/top10.

PowerShell Scripts

render_all_levels.ps1

A helper script to batch render all 12 levels sequentially using render_combined_leaderboard.py.

Usage:

.\render_all_levels.ps1 -InterpolationSteps 5 -RenderScale 5

Exporting TAS Data

To generate the JSON data files required for rendering, you will need the modified Red Ball SWF and the provided AutoHotkey scripts.

Prerequisites

1. Open TAS Export/Red Ball - TAS Export.swf. Keep the window at the default 550x400 size.
2. Copy the run's TAS strings from your spreadsheet. Each string must be in a separate cell.

Export Process

1. Run the appropriate AutoHotkey script:
   • exportWRRun.ahk: Use this for runs where sprite animation data is needed (e.g., the primary/WR run).
     • Note: You may need to modify the sleep times in the script if any level is slower than in DividedByZero's 2:27 run.
   • exportRun.ahk: Use this for standard runs where only position, joint, and/or sound data is needed.
2. Press F12 to start the script.
3. The script will automate the process of interacting with the SWF to export data for all levels.
4. Once finished, paste the content into a new .json file in the appropriate json/ subfolder.