first

CLAUDE.md

@@ -0,0 +1,84 @@
+# 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