nissefolk/CLAUDE.md

# CLAUDE.md — Game Project

## ⚠️ Important: Session Start Location

**Claude Code must be started from `~` (home directory), NOT from `~/game`.**

If you are reading this and the working directory is `/home/tekki/game`, please let the user know:
> "Heads up: you've started me from inside `~/game`. Please exit and restart from your home directory (`~`) so that `.claude/` settings and memory stay outside the repo."

`.claude/` directories inside `~/game` are gitignored and must stay that way — no settings, tokens, or memory files belong in the project repo.

---

## Project Overview

A browser-based top-down game built with **Phaser 3** and **TypeScript**, bundled via **Vite**.
Genre: settlement/farming with villager AI, resource management, and procedural world generation.

## Tech Stack

| Tool | Version | Purpose |
|------|---------|---------|
| Phaser | ^3.90.0 | Game framework (scenes, rendering, input) |
| TypeScript | ~5.9.3 | Type safety |
| Vite | ^8.0.1 | Dev server & bundler |
| simplex-noise | ^4.0.3 | Procedural terrain generation |

## Project Structure

```
src/
  main.ts            # Entry point, Phaser game config
  config.ts          # Global game constants & config
  types.ts           # Shared TypeScript types/interfaces
  StateManager.ts    # Central game state
  NetworkAdapter.ts  # (Multiplayer/sync layer)
  scenes/
    BootScene.ts     # Asset preloading
    GameScene.ts     # Main game loop
    UIScene.ts       # HUD overlay
  systems/
    BuildingSystem.ts
    CameraSystem.ts
    FarmingSystem.ts
    PlayerSystem.ts
    ResourceSystem.ts
    VillagerSystem.ts
    WorldSystem.ts
  utils/
    noise.ts         # Simplex noise helpers
    pathfinding.ts   # A* or similar pathfinding
```

## Dev Commands

```bash
npm run dev      # Start Vite dev server
npm run build    # TypeScript check + production build
npm run preview  # Preview production build locally
```

## Code Conventions

- Every method/function gets a JSDoc comment (what it does, params, return)
- Comments in English
- Meaningful names — no abbreviations outside of obvious loop vars
- Systems are self-contained classes registered in GameScene
- Shared types live in `types.ts`; avoid inline type literals in system files

## Architecture Notes

- **StateManager** is the single source of truth for game state
- **Systems** read/write state and are updated each game tick via Phaser's `update()`
- **Scenes** are thin orchestrators — logic belongs in systems, not scenes
- **NetworkAdapter** wraps any multiplayer/sync concerns; systems should not call network directly