WEBBALL KNOWLEDGE BASE

Generated: 2026-03-25

OVERVIEW

Webcam-controlled basketball game. React UI + BallStateMachine + ShotArc physics + R3F (React Three Fiber) 3D rendering + MediaPipe hand tracking.

STRUCTURE

webball/
├── src/
│   ├── engine/               # Game engine subsystems
│   │   ├── BallStateMachine.ts   # 18-state ball handling FSM
│   │   ├── ShotArc.ts            # 3D projectile physics with collision
│   │   └── input/
│   │       ├── HandTracker.ts        # MediaPipe hand landmarker
│   │       ├── ReleaseDetector.ts    # Legacy velocity-based release
│   │       ├── OneEuroFilter.ts      # Jitter-reducing landmark filter
│   │       └── TwoGateReleaseDetector.ts  # Position + velocity gate shot detection
│   ├── r3f/                  # React Three Fiber 3D components
│   │   ├── GameCanvas.tsx        # Top-level R3F Canvas
│   │   ├── Court.tsx             # Half-court floor + markings
│   │   ├── Hoop.tsx              # Single hoop with backboard + net
│   │   ├── Player.tsx            # Articulated player character
│   │   ├── Ball.tsx              # Basketball with canvas texture
│   │   ├── Lighting.tsx          # 3-point + hemisphere lighting
│   │   └── ThirdPersonCamera.tsx # Smooth-follow camera
│   ├── components/
│   │   ├── GameScreen3D.tsx      # Main game screen (orchestrator)
│   │   ├── MainMenu.tsx          # Landing screen with mode select
│   │   └── MainMenu.css          # Menu styles
│   ├── hooks/
│   │   ├── useHandTracking3D.ts  # Hand tracking with OneEuroFilter
│   │   └── useWebcam.ts          # Webcam access
│   ├── types/index.ts            # Shared type definitions
│   └── App.tsx                   # Root component, screen routing
├── tests/unit/               # Vitest tests
└── public/                   # Static assets

WHERE TO LOOK

ARCHITECTURE

React-driven: No singleton engine. R3F provides frame loop, React owns state.

App.tsx → GameScreen3D.tsx (drives game loop via requestAnimationFrame)
 ├── useHandTracking3D hook
 │   ├── HandTracker (MediaPipe)
 │   ├── OneEuroFilter (jitter reduction)
 │   └── TwoGateReleaseDetector (raise + flick detection)
 ├── BallStateMachine ref (18 states, priority-based transitions)
 ├── ShotArc ref (3D projectile, rim/backboard/floor collision)
 ├── useWebcam hook
 └── GameCanvas (R3F <Canvas>)
     ├── Court (half-court)
     ├── Hoop (single, with net)
     ├── Player (articulated character)
     ├── Ball (textured sphere)
     ├── Lighting (3-point + hemisphere)
     └── ThirdPersonCamera (smooth follow)

Coordinate System: 3D world space. Court is 15x14 units. Hoop at (0, 3.05, -13).

Ball State Flow: IDLE → HELD → DRIBBLE_DOWN/UP → (CROSSOVER|BEHIND_BACK|BETWEEN_LEGS) → GATHER_LOW → GATHER_HIGH → SHOOTING → FOLLOW_THROUGH → (BOUNCE|DEAD) → IDLE

CONVENTIONS

• Components: PascalCase R3F components (Player, Court, Ball)
• Hooks: useXxx pattern
• Engine classes: PascalCase (BallStateMachine, ShotArc)
• Constants: UPPER_SNAKE_CASE at module top
• Types: Centralized in types/index.ts, use import type
• Tests: tests/unit/{ClassName}.test.ts

ANTI-PATTERNS

• NO singleton engine classes — React hooks + state + useFrame
• NO @ts-ignore or type bypasses — strict mode enforced
• NO console.log in production
• NO PixiJS or 2D rendering — removed entirely, 3D only

COMMANDS

npm run dev       # Dev server (Vite)
npm run build     # Type-check + build
npm run lint      # ESLint
npx vitest        # Run tests

GOTCHAS

1. mirrorVideo: Webcam is mirrored. Hand X coordinate flipped: 1 - hand.wrist.x
2. Two-gate shot detection: Requires BOTH hand above shoulder AND velocity reversal (raise then flick)
3. BallStateMachine transitions: Priority-based — higher priority conditions checked first
4. OneEuroFilter params: minCutoff=1.0, beta=0.007 are starting values, tune empirically
5. ShotArc accuracy: Shot meter sweet spot gives +0.2 accuracy bonus to launch angle
6. Half court only: Single hoop at z=-13, player starts at z=8