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

---

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).

# 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