🏀 BREAK THE RULES — Basketball

No ball. No controller. No limits. A browser-based basketball game where your body IS the controller.

---

What Is This?

BREAK THE RULES is a hackathon basketball game controlled entirely by real-time AI pose detection. Using your computer's webcam and MediaPipe Holistic, every move you make — dribbles, crossovers, pump fakes, jump shots — is translated directly into in-game actions.

The entire game lives in a single index.html file. No install. No build step. No dependencies to download. Just open it in Chrome.

---

Theme: "Rules Are Meant To Be Broken"

Rule	How We Break It
You need a controller to play video games	Your body is the controller
You need a basketball to play basketball	You mime it with empty hands
Physics limits your moves on the court	Physics-defying crossovers & jump shots

---

Features

• 7 gesture-controlled actions — dribble, crossover, shoot, pump fake, pass, jump, move
• Real-time AI vision sidebar — live webcam feed with skeleton overlay, velocity bars, gesture history, shoot state machine, cooldown indicators
• AI defender — 4-state AI (GUARDING → CHASING → CONTESTING → STUMBLE) that reacts to your moves
• Physics-based ball — quadratic arc trajectory, rim collision, bounce, motion trail, rotation spin
• 2pt / 3pt detection — shot value determined by your distance from the hoop
• Streak system — consecutive baskets trigger ON FIRE milestones
• Crowd animation — 200 fans wave and light up on every score
• Particle effects + screen flash — on-court confetti on basket
• Web Audio API sounds — synthesized dribble, shoot, squeak, arpeggio score fanfare
• CRT scanline overlay — retro arcade aesthetic
• Responsive scaling — auto-scales to fit any screen size

---

How To Play

Quick Start

# Clone the repo
git clone https://github.com/LeSingh1/break-the-rules-basketball-v2.git
cd break-the-rules-basketball-v2

# Serve locally (required for webcam access)
python3 -m http.server 3000
# Then open http://localhost:3000 in Chrome

Why a local server? The getUserMedia webcam API requires either localhost or HTTPS — opening the file directly (file://) won't work.

Steps

1. Allow camera access when prompted
2. Stand 4–6 feet from your webcam so your full upper body is visible
3. Make sure you have good lighting — MediaPipe works best in well-lit rooms
4. Review the gesture guide on the loading screen
5. Click ALLOW CAMERA & PLAY and hit the court

---

Gesture Controls

Gesture	Body Movement	Game Action
Dribble	Pump both hands downward repeatedly	Player dribbles forward
Crossover	Sweep one hand across your body midline	Speed burst, defender stumbles for 1.5s
Shoot	Raise both hands above shoulders, hold 8 frames	Ball launches in physics arc toward hoop
Pump Fake	Start to raise arms, drop before shoulder height	Defender jumps early, you stay grounded
Pass	Thrust ONE arm sideways fast (other stays still)	Ball flies to off-screen teammate
Jump	Bend knees and physically jump	Player leaps off the court
Move	Lean your whole body left or right	Player slides in that direction

Priority order: SHOOT > JUMP > CROSSOVER > PUMP FAKE > PASS > DRIBBLE > MOVE

---

AI Vision Sidebar

The sidebar on the right gives you a real-time view into what the AI is seeing and deciding:

Panel	Description
LIVE TRACKING	Webcam feed with green skeleton, red/blue wrist dots, and full finger bones
DETECTED	Current gesture with color coding and one-line detection explanation
BODY METRICS	Animated velocity bars (L/R wrist VX/VY), body lean indicator (←→), state chips
SHOOT ENGINE	4-step state machine (READY → LOAD → FIRE → COOL) lights up as you raise arms
COOLDOWNS	Per-gesture ready/cooling indicators
MOVE LOG	Timestamped history of every gesture you trigger

---

Tech Stack

Technology	Purpose
MediaPipe Holistic	33-point body pose + 21-point hand landmarks at 30fps
HTML5 Canvas 2D	Court, characters, ball, particles, HUD — all drawn with JS
Web Audio API	Synthesized SFX — no external audio files
OffscreenCanvas	Court cached to offscreen canvas for rendering performance
Vanilla JS (ES2022)	No framework, no build tool, no bundler
Google Fonts	Press Start 2P (pixel HUD) + Chakra Petch (data panels)

---

Project Structure

break-the-rules-basketball/
├── index.html          # The entire game — all JS/CSS inline, one file
├── README.md           # This file
├── LICENSE             # MIT License
├── .gitignore          # Git ignore rules
└── docs/
    ├── GESTURE_REFERENCE.md     # Detection algorithms & tuning guide
    ├── GAME_DESIGN_DOCUMENT.md  # Full 22-section technical spec
    └── ITCH_IO_GUIDE.md         # itch.io submission checklist & description copy

---

Architecture Overview

getUserMedia (webcam)
       │
       ▼
MediaPipe Holistic (every 2nd frame for perf)
       │
       ├─ poseLandmarks[33]    ──▶  Gesture Engine
       ├─ leftHandLandmarks[21]      │
       └─ rightHandLandmarks[21]     │
                                     ├─ poseHistory[15 frames]
                                     ├─ velocity calculations
                                     ├─ cooldown system
                                     └─ priority detection
                                            │
                                            ▼
                                      Game Actions
                                    (SHOOT/JUMP/MOVE...)
                                            │
                                 ┌──────────┴──────────┐
                                 ▼                     ▼
                           Game Loop (60fps)     AI Sidebar (20fps)
                         ┌──────────────┐       ┌──────────────────┐
                         │ Court render │       │ miniCam + skeleton│
                         │ Characters   │       │ Velocity bars     │
                         │ Ball physics │       │ Shoot state mach. │
                         │ Defender AI  │       │ Cooldowns + log   │
                         │ Particles    │       └──────────────────┘
                         │ HUD          │
                         └──────────────┘

---

Gesture Detection Thresholds (tunable in CONFIG)

Gesture	Threshold	Default	Notes
Dribble wrist speed	DRIBBLE_VY_THRESHOLD	0.015	Lower = more sensitive
Crossover horizontal	CROSSOVER_VX_THRESHOLD	0.020
Shoot height	SHOOT_WRIST_ABOVE_SHOULDER	0.05	How far above shoulder
Shoot hold frames	SHOOT_LOAD_FRAMES	8	Frames held before shot fires
Pump fake rise	PUMP_FAKE_RISE	0.05	Min rise before detection
Movement lean	MOVEMENT_VX_THRESHOLD	0.015
Pass speed	PASS_VX_THRESHOLD	0.04

All thresholds are in the CONFIG object at the top of index.html.

---

Browser Requirements

Browser	Support
Chrome 99+	✅ Recommended
Firefox 90+	✅ Supported
Edge 99+	✅ Supported
Safari	⚠️ Limited (WebRTC quirks)
Mobile	❌ Not supported (needs full body space)

Hardware: Any webcam. Works best in well-lit environments with a plain background.

---

Running on itch.io

1. Zip index.html → break-the-rules.zip
2. Upload to itch.io → New Project → Kind: HTML
3. Set viewport to 1280 × 720
4. Enable "Click to play" (required for AudioContext)
5. See docs/ITCH_IO_GUIDE.md for full description copy

---

Local Development

The game is a single self-contained HTML file — no build step needed.

# Edit index.html and serve
python3 -m http.server 3000

# Or with Node
npx serve .

To tune gesture sensitivity, edit the CONFIG object at the top of the <script> tag in index.html.

---

License

MIT — see LICENSE

---

Pixel Forge Hackathon · April 2026 · Theme: Rules Are Meant To Be Broken