---
title: HAWK ONE
emoji: 🏈
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: "4.44.1"
python_version: "3.11"
app_file: app.py
pinned: false
---

# HAWK ONE

A football film room built on one simulation engine with two rule profiles (NFL and college).
Watch a play run, click a player, redraw his path or change his reaction time, and see what would have happened.

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

## What it does

- **Run play / Next play.** Offensive and defensive coaches call the snap ("Coach decides") or you pick the calls. Next play carries the drive forward (down, distance, field position, hash spotting). The play auto-plays.
- **Level switch.** NFL or college reruns the play under that level's rules and hash width (catch, down by contact, pass interference, ineligible linemen downfield, hash marks).
- **Player card.** Click any player for height, weight, 40 time, top speed, separation from the nearest opponent over time, and speed over time.
- **What-if.** Drag the points on a player's path (add, remove, retime), or change a defender's or the QB's reaction time. Press **Run what-if**: the original and your version are replayed hundreds of times on the same random seeds, with a verdict, the numbers, a histogram, reasons, and a check of whether his body can run what you drew. Several edits at once are supported, with the credit split between them.
- **Path Lab.** The engine tries variations of one player's path and ranks them.
- **Recorded plays.** Load a tracking CSV (format in `tracking.py`) to inspect and annotate a real play. "Save this play as CSV" writes a sample.

## Run locally

    pip install -r requirements.txt
    python app.py

## Files

| File | Role |
|---|---|
| `app.py` | Gradio app (single screen) |
| `film.py` | Film viewer (HTML/SVG/JS served in an iframe) |
| `render.py` | Result panels (verdict, numbers, credit split, Path Lab) |
| `whatif.py` | Paired Monte Carlo, feasibility, path suggestions |
| `engine.py` | Physics, collisions, blocking, coverage, rule hooks |
| `coach.py` | Play calling and the drive loop |
| `attrs.py`, `playbook.py`, `formations.py` | Player attributes, plays and calls, alignments |
| `rules.py` | NFL and NCAA rule profiles and rule functions |
| `tracking.py` | Tracking CSV import and export |

## Status and caveats

- The simulation is plausible but not fitted to league data. Use the direction and the reasons more than the exact yardage.
- What-if runs on simulated plays. Recorded plays can be inspected and annotated; running them through the engine needs an adapter that starts from recorded alignments.
- Rules marked "verify" in `rules.py` (game clock, pass interference flat vs capped, overtime, kickoffs, targeting) need confirmation against the current NFL and NCAA rulebooks.
- Engine, what-if maths, result panels and the viewer (including the iframe-to-page bridge) were run headlessly. The Gradio app itself still needs a first run in your environment.