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

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