Cozypaw-Hospital/CLAUDE.md

# CLAUDE.md — Cozypaw Hospital

> Dieses Dokument ist der Primär-Kontext für Claude Code. Beim Start lesen und die hier dokumentierten Konventionen einhalten.

## Projekt in einem Satz

Cozypaw Hospital ist ein werbefreies 2D-Sandbox-Spiel für Kinder (3+) im Stil von Yasa Pets Hospital — ein dreistöckiges Tier-Krankenhaus mit Häschen und Kätzchen als digitale Puppenstube, gebaut in Godot 4 für Android und iOS.

## Aktueller Status

- **Phase:** Sprint 0 (Setup)
- **Repo:** git.race-cave.cloud/steven/Cozypaw-Hospital (self-hosted Gitea)
- **Godot-Projekt:** noch nicht initialisiert
- **Nächster Meilenstein:** Godot 4 installieren, Android-Export einrichten, Proof-of-Concept-Raum

Der vollständige 16-Wochen-Sprintplan liegt in `docs/development-plan.md`. Immer dort nachschlagen, bevor neue Features beschlossen werden.

## Tech-Stack (fix)

- **Engine:** Godot 4.x (keine Unity, keine Alternativen mehr zur Debatte)
- **Sprache:** GDScript (statisch typisiert, wo möglich)
- **Zielplattformen:** Android zuerst, iOS später
- **VCS:** Git mit self-hosted Gitea
- **Asset-Strategie:** Hybrid — Kinder malen Helden-Figuren, Freelancer macht Hintergründe

## Nicht-verhandelbare Produkt-Prinzipien

Diese Punkte sind Teil der Produkt-DNA. Niemals vorschlagen, davon abzuweichen — auch nicht "nur für Testing" oder "vorübergehend":

1. **Keine Werbung.** Keine Ad-SDKs, keine Rewarded Ads, kein AdMob, nichts.
2. **Keine Datensammlung.** Keine Analytics (Firebase, GA, Sentry, etc.), kein Tracking, keine Telemetrie, keine Crash-Reports ohne Opt-in.
3. **Offline-first.** Das Spiel muss vollständig ohne Internetverbindung funktionieren.
4. **Keine In-App-Käufe.** Keine Premium-Features, keine Diamonds, kein Gacha.
5. **Keine externen Links** ohne Parental Gate (derzeit: gar keine).
6. **Keine "Gift"-Mechaniken** (im Original: grüne Flaschen, die Tiere krank machen). Alle Medikamente sind neutral/positiv.
7. **Sandbox-Charakter.** Kein Scheitern, keine Zeitlimits, kein Scoring, keine Achievements.
8. **COPPA/DSGVO-konform.** Play-Store-Data-Safety: "Keine Daten erhoben" — und das auch tatsächlich einhalten.

## Architektur-Überblick

### Scene-Hierarchie (geplant)

```
Main (Node2D)
├── Hospital (Node2D)
│   ├── Floor0 — Empfang, GiftShop, Restaurant, Emergency
│   ├── Floor1 — XRay, Pharmacy, Lab, PatientRooms
│   └── Floor2 — Ultrasound, DeliveryRoom, Nursery
├── Home (Node2D) — GardenParty
├── Characters (Autoload)
└── UI (CanvasLayer)
```

### Core Systems (als Autoloads)

- `GameState` — globaler Zustand, Positionen aller Figuren/Objekte
- `SaveManager` — JSON-Persistenz in `user://savegame.json`, Auto-Save nach jeder Interaktion
- `AudioManager` — Musik- und SFX-Steuerung mit Cross-Fade zwischen Räumen
- `InputManager` — Touch/Drag-Abstraktion

### Datenmodell-Konvention

Character- und Object-States immer als `Resource`-Subklassen (nicht als dict), damit Godot-Editor damit arbeiten kann und Serialisierung sauber läuft.

## Verzeichnisstruktur

```
cozypaw-hospital/
├── project.godot
├── scenes/
│   ├── main/
│   ├── rooms/{floor0,floor1,floor2,home}/
│   ├── characters/
│   ├── objects/
│   └── ui/
├── scripts/
│   ├── autoload/
│   ├── characters/
│   ├── objects/
│   └── systems/
├── assets/
│   ├── sprites/{characters,rooms,objects,ui}/
│   ├── audio/{music,sfx,voices}/
│   └── fonts/
├── localization/
├── addons/
├── docs/
└── builds/   # nicht im Git
```

## Konventionen

### Commits (Conventional Commits)

- `feat:` neues Feature
- `fix:` Bugfix
- `refactor:` Refactoring ohne Funktionsänderung
- `assets:` Asset-Updates (Sprites, Sounds)
- `docs:` Dokumentation
- `chore:` Build, Config, Tooling

Mit Scope: `feat(reception): add waiting number system`

Commit-Messages in **Englisch** (auch wenn die Doku auf Deutsch ist).

### Branching

- `main` — stabiler Stand, releasebar
- `develop` — aktive Entwicklung
- `feature/<name>` — einzelne Features
- `sprint/<nr>-<name>` — Sprint-Branches

Keine direkten Pushes auf `main`. Merges aus `develop` nur, wenn Build grün und auf echtem Tablet getestet.

### GDScript Code-Style

- **Typisierung:** Statische Typen überall wo möglich (`var x: int = 5`)
- **Nomenklatur:** `snake_case` für Variablen/Funktionen, `PascalCase` für Klassen und Scenes, `SCREAMING_SNAKE_CASE` für Konstanten
- **Signals:** Zukunftsform-Verben: `character_picked_up`, `room_entered`
- **Private Member:** Unterstrich-Präfix: `_internal_state`

### Dokumentation

Stevens Präferenz (aus bisheriger Arbeit): **Keine Inline-Kommentare im Code.** Stattdessen konsolidierte Dokumentation als Header-Block am Dateianfang. Code soll selbsterklärend sein durch gute Namen. Diese Regel gilt auch für GDScript-Dateien.

Ausnahme: Komplexe mathematische Berechnungen oder nicht-offensichtliche Workarounds dürfen einen einzigen Kommentar haben, der das *Warum* erklärt (nicht das Was).

### Tests

Für ein Spiel dieser Größe keine Unit-Tests nötig. Stattdessen:
- **Scene-Tests** manuell auf echtem Android-Tablet pro Sprint
- **Smoke-Test-Checkliste** in `docs/smoke-tests.md` (wird im Laufe der Entwicklung gepflegt)
- **Kinder als UAT** — wöchentliches Zeigen der Builds

## UI/UX-Regeln

- **Touch-Targets:** Minimum 48dp, besser 64dp
- **Keine Text-UI** für Spiel-Interaktionen (Kinder unter 6 Jahren lesen nicht). Icons, Symbole, Farben.
- **Zurück-Button** immer sichtbar, groß und an festem Platz
- **Musik-Default:** 60%, nicht 100%
- **Idle-Animationen:** Jede Figur atmet/blinzelt auch im Stand
- **Sound-Feedback** für jede Interaktion (Ploppen, Quietschen, etc.)

## Out of Scope (bewusst nicht gemacht)

- ❌ Multiplayer, Online-Features, Cloud-Saves
- ❌ Prozedurale Generierung
- ❌ Physik-Engine (nicht nötig für Puppenhaus-Interaktionen)
- ❌ Character-Editor / Customization
- ❌ Level-System, Achievements, Scoring
- ❌ Tutorial (außer dezenter Hinweis beim allerersten Start)
- ❌ Rechtschreibung/Text-Eingabe durch Kinder

## Wie Claude Code arbeiten soll

### Proaktiv sein
- Bei Godot-spezifischen Fragen: Godot-4-Docs konsultieren, nicht Godot-3-Patterns nutzen (Syntax hat sich geändert).
- Bei neuen Scenes: An der oben definierten Verzeichnisstruktur orientieren.
- Code immer mit statischen Typen schreiben.

### Keine Überraschungen
- Keine neuen Dependencies / Addons hinzufügen ohne explizite Rücksprache.
- Keine Änderungen am `.gitignore`, `README.md` oder dieser Datei ohne explizite Aufforderung.
- Keine automatischen Commits. Stevens Workflow: Er committed selbst nach Review.

### Bei Unsicherheit nachfragen
- Wenn unklar, ob ein Feature in den Sandbox-Charakter passt → fragen.
- Wenn unklar, wie etwas visuell/interaktiv funktionieren soll → fragen, nicht raten.

### Sprach-Konvention
- **Code & Commits:** Englisch
- **Dokumentation & Gespräch:** Deutsch
- **Spiel-Inhalte (UI, ggf. Texte):** Später lokalisiert — primär Deutsch, dann Englisch

## Referenz-Dokumente

- `docs/development-plan.md` — 16-Wochen-Sprintplan mit Details
- `README.md` — öffentliche Projektbeschreibung
- `docs/` — alle weiteren Design-Docs (werden im Laufe der Sprints ergänzt)

## Kontext zum Entwickler (Steven)

- Java-Entwickler, kommt aus dem Backend/Enterprise-Umfeld
- Präferiert clean, concise technical work — keine Verbose-Erklärungen
- Kommuniziert primär auf Deutsch
- Baut das Spiel für seine eigenen Kinder (nicht für einen kommerziellen Launch)
- Hat parallel laufende Projekte (All-in Creative Print, RaceCave) — dieses Projekt ist Abendbeschäftigung, nicht Vollzeit
- Arbeitet gerne mit klaren Conventions und durchdachter Struktur statt Ad-hoc-Lösungen

## Versions-Log dieser Datei

- 2026-04-17: Initiale Version, Sprint 0 gestartet