# CLAUDE.md

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

## Project Overview

iPuzzle is a browser-based multiplayer puzzle game built with **Phaser 3.9** and vanilla **ES6 JavaScript**. No package manager or build step — the game runs directly in a browser.

## Running the Game

Open `index.html` in a browser. Because Phaser loads assets via XHR, you need a local HTTP server (not `file://`):

```bash
python3 -m http.server 8080
# then open http://localhost:8080
```

## Architecture

The game is organized into Phaser scenes:

- **MainMenuScene** — entry point; "New Puzzle" and "Join Puzzle" buttons
- **NewPuzzleScene** — image picker (`/assets/images/puzzles/`, 16×9 images) and piece-count selector (40 / 60 / 100); generates puzzle piece geometry before transitioning
- **PuzzleScene** — core gameplay; owns the piece objects, interaction logic, room code, and completion state

### Key design constraints

- **No build tool / no npm** — all Phaser and game code is loaded via `<script>` tags or ES6 modules without a bundler.
- **Multiplayer-ready state** — puzzle state (piece positions, locked pairs, room code) must be kept in `localStorage` so it can later be synced to other players. Design state updates to be serializable and event-driven.
- **Room code** — a random 4-character uppercase-alphanumeric code is generated when a new puzzle starts. All state must be keyed to this code to support future multi-room play.

### Puzzle piece generation

Pieces are procedurally generated to look like interlocking puzzle pieces. The generator takes the source image and piece count, divides the image into a grid, and renders each piece with tab/blank connectors on each edge. Connector geometry must be consistent (piece A's tab must match piece B's blank) so that adjacency detection and auto-lock work correctly.

### Interaction model

- Click to pick up a piece; click again to release.
- Held piece always renders on top (highest `depth`/z-order).
- While a piece is held, check all edges against their matching neighbors — highlight matching edges with a glow effect when close.
- On release, if within snap distance of a matching neighbor, lock the pieces together (they move as a unit thereafter).

## Asset conventions

- Puzzle images: `/assets/images/puzzles/` — 16×9 aspect ratio PNG/JPG files.