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:

Background removal (détourage)
Size reduction and graphic simplification
Spritesheet creation (64x64 or 128x128 per frame)
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

3.1 KiB Raw Blame History