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

---

## Gitea Workflow (repo: tekki/nissefolk)

**Tool:** `tea` CLI (installed at `~/.local/bin/tea`, login `zally` configured).
Never use raw `curl` with `${CLAUDE_GITEA_TOKEN}` for Gitea — use `tea` instead.
All `tea` commands run from `~/game` (git remote `gitea` points to the repo).

**Git commands:** Always use `git -C ~/game <cmd>` — never `cd ~/game && git <cmd>` (triggers security prompt).

```bash
# Create PR (always wait for user approval before merging)
# Use ~/scripts/create-pr.sh — pass \n literally for newlines, the script expands them via printf.
# Never use heredocs or $(cat file) — they trigger permission prompts.
~/scripts/create-pr.sh "PR title" "Fixes #N.\n\n## What changed\n- item one\n- item two" feature/xyz

# List open PRs / issues
tea pr list --login zally
tea issue list --login zally

# View a single issue (body + comments)
tea issue --login zally --repo tekki/nissefolk <ISSUE_NUMBER>

# Merge PR — ONLY after explicit user says "merge it"
tea pr merge --login zally --style merge <PR_NUMBER>

# Close issue
tea issue close --login zally --repo tekki/nissefolk <ISSUE_NUMBER>

# List labels
tea labels list --login zally --repo tekki/nissefolk

# Set/remove labels on an issue (use label names, not IDs)
tea issue edit --login zally --repo tekki/nissefolk --add-labels "status: done" <N>
tea issue edit --login zally --repo tekki/nissefolk --remove-labels "status: in discussion" <N>


# Both flags can be combined; --add-labels takes precedence over --remove-labels
tea issue edit <N> --add-labels "status: done" --remove-labels "status: in progress" --repo tekki/nissefolk

# Note: "tea labels" manages label definitions in the repo — not issue assignments
```

**Label IDs** (repo-specific, don't guess):
| ID | Name |
|----|------|
| 1  | feature |
| 2  | improvement |
| 3  | bug |
| 6  | status: backlog |
| 8  | status: ready |
| 9  | status: in progress |
| 10 | status: review |
| 11 | status: done |

**PR workflow rules:**
1. Commit → push branch → `tea pr create` → **share URL, stop, wait for user approval**
2. Only merge when user explicitly says so
3. After merge: close issue + set label to `status: done`

**master branch is protected** — direct push is rejected. Always use PRs.

**Routine load issue**
1. Load Issues
if-> If the label is status: ready
    -> work as it says
    -> use a new branch for each issue
    -> test your code
    -> commit your code
    -> change the issue label
    -> do an pr to master

if-> If the label is status: discussion
    -> think if you need more information
    -> ask questions as comment in gitea

**Issue create**
If i say something like "create an issue about..." you need to attach the labels to it to. Use status: discussion and feature/bug