README.md

metadata

title: RunRate Lab
emoji: 🏏
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 8501
pinned: false
short_description: Learn cricket analytics through a T20 chase.

🏏 RunRate Lab

Play. Analyze. Improve.

RunRate Lab is an interactive cricket analytics learning game. You play a T20 chase in a 2.5D cricket arcade, choose shot intent and aim lane, swing at live deliveries, and learn how analytics explains every outcome through expected runs, wicket risk, variance, Monte Carlo simulation, and decision quality.

What You Learn

• Expected runs: the long-run value of a shot before the random result appears.
• Wicket risk: the chance that a shot leads to dismissal.
• Variance: why a good decision can fail and a bad decision can succeed.
• Decision quality: whether the shot created enough value for the risk accepted.
• Monte Carlo simulation: repeated trials that estimate the probability of 0, 1, 2, 3, 4, 6, or W.
• Match pressure: how required run rate changes which risks are rational.

How To Play

1. Click Start T20 Chase.
2. Choose Defend, Drive, Cut / Pull, or Loft.
3. Choose Leg Side, Straight, or Off Side.
4. Hold mouse, touch, or Space to start the delivery and charge your shot.
5. Release near the green impact band.
6. Read the Analytics Coach panel after every ball, then press Next Ball.
7. Use the Interactive Analytics Lab to recreate a shot and change one input at a time.
8. Complete the Learning Path missions to build analytics intuition.

Keyboard controls:

• 1: Defend
• 2: Drive
• 3: Cut / Pull
• 4: Loft
• A and D: change aim lane
• Space: hold and release swing
• Enter: next ball during review

Game Features

• 2.5D batting-end view with pitch depth, field ring, crease, stumps, and ball scaling.
• Keyframed batter rig with helmet, torso, pads, arms, gloves, and an attached bat.
• Shot intent and aim lane choices before every delivery.
• Required review pause after each ball so the coach panel remains readable.
• Result toast, boundary flash, wicket shake, shot trails, and replay-style commentary.
• Process streak and Process Score after every over showing average xRuns, actual runs, average wicket risk, best decision, and variance flag.
• In-game settings for reduced flashing, color-safe feedback, and the first-ball hold-release prompt.

Learning Path

RunRate Lab includes five guided modules:

1. Expected Runs: compare two shot intents against the same delivery.
2. Wicket Risk: complete an over using only shots under a target risk budget.
3. Variance And Luck: identify lucky and unlucky outcomes.
4. Timing Sensitivity: compare early, perfect, and late releases for the same setup.
5. Match Pressure: compare Drive and Loft at different required run rates.

Project Structure

• app.py: Streamlit app, browser game, analytics lab, learning path, and charts.
• requirements.txt: minimal runtime dependencies.
• Dockerfile: Hugging Face Docker Space deployment.
• .streamlit/config.toml: app theme and Streamlit settings.
• tests/test_runrate_lab.py: focused analytics tests.

Local Setup

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt

Run Locally

.venv/bin/streamlit run app.py

Open:

http://localhost:8501

Test

make check

Or run only unit tests:

.venv/bin/python -m unittest discover -s tests

Docker

Build and run locally:

docker build -t runrate-lab .
docker run --rm -p 8501:8501 runrate-lab

Open:

http://localhost:8501

Deploy To Hugging Face Spaces

1. Create a new Hugging Face Space.
2. Choose Docker as the SDK.
3. Clone the Space repository.
4. Copy these files into the Space repository:
   • app.py
   • requirements.txt
   • Dockerfile
   • .streamlit/config.toml
   • README.md
5. Commit:

git add .
git commit -m "Build RunRate Lab cricket analytics coach"

6. Push:

git push

7. Wait for the Space build logs to finish.
8. Open the Space URL and verify:
   • the app loads
   • the game starts
   • shot intent and aim lane controls work
   • hold-and-release swing works
   • the bat remains attached to both glove anchors during the swing
   • a delivery pauses on the review state until Next Ball is pressed
   • the Analytics Coach updates after each ball
   • Analytics Lab charts render
   • no app console errors appear

Notes

• No external APIs, model downloads, database, login, or webcam access are required.
• The canvas game runs client-side for smooth animation.
• The analytics lab uses deterministic simulation seeds so repeated slider setups are stable for learning.