Skip to content

README.md

Latest commit

 

History

History
61 lines (47 loc) · 2.41 KB

README.md

File metadata and controls

61 lines (47 loc) · 2.41 KB
Raw

Hadouken - Gesture Combat

A webcam-controlled boxing/combat game. Punch the air toward the camera to attack an AI boss; hold an open palm steady to block its telegraphed attacks. No game engine — just OpenCV + MediaPipe for input and Pygame for rendering.

Setup

pip install -r requirements.txt
python hadouken.py

Controls

  • Punch — thrust your hand quickly (any direction toward the camera works well)
  • Block — hold an open palm (fingers spread) steady for ~0.2s
  • C — toggle the small camera preview (bottom-right)
  • R — restart after game over
  • ESC — quit

Why it stays smooth

The camera capture and MediaPipe hand-tracking run in a separate background thread. The pygame render loop never waits on the camera — it just reads whatever the latest gesture snapshot is, every frame, at a fixed 60 FPS. So even if the camera thread has a slow frame (bad lighting, motion blur, laptop under load), the game itself never stutters.

Other speed choices:

  • MediaPipe processes a downscaled 320×240 frame, not full camera resolution
  • model_complexity=0 (the lightest hand-tracking model)
  • Punch detection uses a simple wrist-velocity spike with hysteresis (arm/disarm thresholds) — cheap to compute, no ML classifier needed
  • Camera preview image is only rebuilt every 2nd frame

Tuning before your demo (important!)

Lighting and camera angle vary a lot between rooms. Do a 2-minute calibration pass on-site:

  1. Run the game, watch the on-screen Cam FPS counter — if it's below ~15, move to better lighting or lower CAM_CAPTURE_W/H further.
  2. If punches don't register: lower PUNCH_SPEED_THRESHOLD in the CONFIG section at the top of the file (try steps of 0.2).
  3. If punches fire too easily from normal hand movement: raise PUNCH_SPEED_THRESHOLD, or raise PUNCH_RESET_THRESHOLD slightly.
  4. If blocking is too easy/hard to trigger: adjust BLOCK_HOLD_TIME or the sum(fingers) >= 3 condition in HandWorker._process_landmarks.

Extending it further

  • Two-player mode: set max_num_hands=2 and split screen zones by x-position of each detected hand.
  • Special move: track the last ~20 wrist positions and match the path shape (e.g. circle) for a bonus attack.
  • Sound: add pygame.mixer hits on punch/block/attack events — the Game.update_playing method already has clearly marked event points (event == "attack_landed" etc.) to hook sounds into.