# Game Sites - Complete Documentation

> A Next.js-based HTML5 game aggregator platform serving games from multiple sources with a modern, responsive interface.

This is a static game catalog website built with Next.js 15, React 19, TypeScript, and Tailwind CSS 4. The platform aggregates and displays games from various platforms, featuring both self-hosted HTML5 games and embedded third-party games. The site uses static site generation (SSG) for optimal performance and is deployed to Cloudflare Pages.

## Project Overview

**Purpose**: Serve as a centralized platform for hosting and playing HTML5 games from multiple sources, providing a unified, user-friendly interface for game discovery and playback.

**Key Features**:
- Game catalog with 200+ games aggregated from multiple platforms
- Static site generation for fast load times and SEO
- Game search functionality with platform filtering
- Responsive masonry layout with gradient-based or icon thumbnails
- Fullscreen iframe player with fallback support
- Daily randomized homepage collections using date-seeded Fisher-Yates shuffle
- Game icons with optimization workflow (512×512 PNG, ~20-180KB)
- "New" badges for recently added games

## Documentation

- [CLAUDE.md](CLAUDE.md): Complete architecture overview, development patterns, and workflows
- [README.md](README.md): Project structure, setup instructions, and deployment guide
- [Game Library](/src/lib/games.ts): Core utilities for game data fetching and URL handling
- [Game Player Component](/src/components/GamePlayer.tsx): Iframe embedding and playback logic
- [Game Card Component](/src/components/GameCard.tsx): Game thumbnail display with hover effects

## Architecture

### Data Flow

1. **Game Data Source**: `public/games.json` contains complete catalog
   - Fields: `name`, `url`, `embed_url`, `iframe_url`, `platform`, `scraped_at`, `icon`
   - Fetched client-side via `getGames()` in `src/lib/games.ts`

2. **Game Library Utilities** (`src/lib/games.ts`):
   - `getGames()` - Fetches game data from JSON
   - `getGameSlug()` - Converts names to URL-safe slugs
   - `getGameEmbedUrl()` - Returns best embed URL (iframe_url → embed_url → url)
   - `getPlatformGames()` - Groups games by platform

3. **Static Assets**:
   - Self-hosted HTML5 games in `public/html5/` (47 games)
   - Game icons in `public/images/games/{slug}.png`

### Routing Structure

**Pages** (App Router):
- `/` - Homepage with date-seeded randomized collections
- `/game/[slug]` - Game details page with metadata
- `/game/[slug]/play` - Game player with iframe embed
- `/search` - Client-side search with platform filtering
- `/about`, `/privacy`, `/terms` - Static content pages

**Key Route Logic**:
- Homepage uses Fisher-Yates shuffle with date-based seed for consistent daily randomization
- Game pages read from disk at build time via `fs.readFileSync()` for SSG
- All game routes use `generateStaticParams()` for static generation

### Component Architecture

**Client Components**:

1. `GamePlayer` - Handles game embedding and playback
   - Props: `embedUrl`, `fallbackUrl`, `title`, `icon?`
   - Features: Fullscreen toggle, share functionality, loading states
   - Shows game icon as background before play button clicked
   - Error fallback handling

2. `GameCard` - Displays game thumbnails
   - Shows icon if available, otherwise generates gradient with initials
   - "New" badge based on `scraped_at` date (within 7 days)
   - `toneIndex` prop for gradient color selection
   - Hover effects and animations

**Server Components**:
- Homepage collections (2-column masonry layout)
- Game detail pages with metadata and similar games section
- Static pages (About, Privacy, Terms)

### Styling System

- **Tailwind CSS 4** with utility-first approach
- Color palette: slate grays, sky blues, vibrant accents
- Large rounded corners (28px, 32px, 38px) for modern aesthetic
- Custom shadows: `shadow-[0_32px_64px_-34px_rgba(15,23,42,0.45)]`
- Responsive design with mobile-first breakpoints

### Image Optimization Workflow

When adding new game icons to `public/images/games/`:

1. Add PNG files named after game slug
2. Run optimization script: `node optimize-images.mjs`
   - Resizes to 512×512px
   - Compresses with sharp
   - Skips files < 200KB
   - Backs up originals as `.png.bak`
3. Update `games.json` with `"icon": "/images/games/{slug}.png"`
4. Target: 512×512px PNG, ~20-180KB after optimization

## Development Guide

### Commands

```bash
# Development
pnpm dev          # Start dev server with Turbopack (http://localhost:3000)
pnpm build        # Build standalone production output
pnpm start        # Run production server
pnpm lint         # Run ESLint checks

# Image optimization
pnpm optimize:games  # Optimize game icons with sharp
```

**Package Management**:
- Always use `pnpm` (not npm or yarn) for lockfile consistency
- Run `pnpm install` after pulling changes

### Configuration

**next.config.js**:
- `output: 'standalone'` for Cloudflare Pages deployment
- Image optimization enabled (WebP/AVIF support)
- Static HTML5 games served via rewrites for `/html5/` paths
- External image domains configured for game thumbnails

**ESLint**:
- Uses Next.js preset via `eslint.config.mjs`
- TypeScript strict mode enabled

### Development Patterns

**Adding a new game**:
1. Add entry to `public/games.json` with required fields
2. Optionally add icon to `public/images/games/{slug}.png`
3. Run `pnpm optimize:games` to compress icon
4. Game auto-generates routes via `generateStaticParams()`

**Modifying game display**:
- Homepage logic: `src/app/page.tsx` (collections, featured sections)
- Card appearance: `src/components/GameCard.tsx`
- Player UI: `src/components/GamePlayer.tsx`

**Search/Filter logic**:
- Client-side filtering in `/search` page
- Uses `getGameSlug()` for URL matching
- Platform grouping via `getPlatformGames()`

## File Structure

```
game-sites/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── page.tsx           # Homepage with collections
│   │   ├── game/[slug]/       # Game detail pages
│   │   ├── search/            # Search page
│   │   └── about|privacy|terms/
│   ├── components/            # React components
│   │   ├── GameCard.tsx      # Game thumbnail card
│   │   └── GamePlayer.tsx    # Iframe player
│   ├── lib/
│   │   └── games.ts          # Game utilities
│   └── hooks/                # Custom React hooks
├── public/
│   ├── games.json            # Complete game catalog
│   ├── html5/                # Self-hosted HTML5 games
│   └── images/games/         # Game icons (512×512 PNG)
├── CLAUDE.md                 # Developer documentation
├── README.md                 # Project overview
├── package.json              # Dependencies and scripts
├── next.config.js            # Next.js configuration
├── tailwind.config.ts        # Tailwind CSS config
└── optimize-images.mjs       # Icon optimization script
```

## Tech Stack

- **Framework**: Next.js 15 (App Router, standalone output mode)
- **UI Library**: React 19
- **Language**: TypeScript 5
- **Styling**: Tailwind CSS 4
- **Icons**: Heroicons React
- **Image Processing**: Sharp (for icon optimization)
- **Linting**: ESLint with Next.js preset
- **Package Manager**: pnpm
- **Deployment**: Cloudflare Pages

## Deployment

The project is configured for Cloudflare Pages with standalone output:

1. Build: `pnpm build`
2. Deploy `.next` folder to Cloudflare Pages
3. Configure platform to serve standalone build

**Build Output**: Standalone mode creates a self-contained deployment package in `.next/standalone/` with all necessary dependencies.

## Key Integrations

- Multiple game platforms aggregated via `games.json`
- Self-hosted HTML5 games in `/public/html5/`
- Third-party game embeds via iframe
- Static site generation for performance
- Date-seeded randomization for consistent daily homepage

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes following project patterns
4. Run `pnpm lint` to check code quality
5. Submit a pull request

## License

[Specify license information]