# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Mobile web game - a 2D runner/platformer inspired by Super Mario, playable in mobile browsers (iOS Safari, Android Chrome) with gyroscope controls and touch jump button.

**Target Platform**: Mobile web (landscape orientation) with PWA support for fullscreen experience.

**Core Mechanics**:
- Character controlled by phone gyroscope (tilt right = move forward, tilt left = move backward)
- Touch button for jumping (bottom-right corner)
- Avoid obstacles, collect gifts/bonuses
- Level duration: ~3 minutes (timed or distance-based)

**Custom Character**: The player character is based on a photo of the developer's nephew, converted to animated sprites.

## Technology Stack

- **Game Engine**: Phaser 3
- **Language**: JavaScript or TypeScript
- **Build Tool**: TBD (Vite, Webpack, or Parcel recommended)
- **PWA**: Service worker + manifest.json for app-like experience
- **Mobile APIs**: DeviceOrientationEvent for gyroscope control

## Gyroscope Implementation Requirements

**iOS-specific**: Must call `DeviceOrientationEvent.requestPermission()` after user gesture (e.g., "Start" button).

**Android**: Direct `deviceorientation` event listener, no permission required.

**Normalization**: Convert device tilt to normalized value (e.g., -30° to +30°) with deadzone at center for "idle" state when phone is horizontal.

**Integration with Phaser**: Normalized tilt value controls player horizontal velocity.

## Sprite Workflow

Character sprites created from photo with these steps:
1. Background removal (détourage)
2. Size reduction and graphic simplification
3. Spritesheet creation (64x64 or 128x128 per frame)
4. Multiple animation states: idle, walk/run, jump

Load in Phaser using:
- `this.load.spritesheet()` in preload
- `this.anims.create()` for animation definitions

## Level Design

**Background**: Scrolling background using `tileSprite` or tilemap with camera follow.

**Platforms**:
- Ground and static platforms using `staticGroup`
- Optional: moving platforms

**Objects**:
- Obstacles: collision detection → damage/penalty
- Gifts: overlap detection → score increase

**Level Editor**: Consider using Tiled for level layout (platforms, obstacles, gifts placement) exported as JSON tilemap.

## Game Structure

**3-minute level design**:
- Option 1: 180-second countdown timer → end screen
- Option 2: Fixed level distance calibrated for ~3 minutes at average speed

## Mobile-Specific Requirements

**Fullscreen**: Implement fullscreen API for immersive mobile experience.

**Orientation**: Force landscape mode (CSS + screen orientation API).

**Touch Controls**: Large, accessible jump button (bottom-right) optimized for thumb reach.

**Performance**: Optimize for mobile GPU/CPU constraints.

## Code Style

- Code in English with French comments/documentation
- Provide concrete, copy-paste ready code
- Step-by-step implementation approach: architecture → Phaser init → gyroscope → jump button → background → platforms → objects → 3-min level
- Include inline code comments for clarity