ninelands-reddit/CLAUDE.md

CLAUDE.md – Ninelands für Reddit (Devvit)

Diese Datei lädt Claude Code in jeder Sitzung. Sie hält fest, was dieses Projekt ist, wie gearbeitet wird und wo wir stehen. Stand: 2026-11-13, frisch angelegt aus der Devvit-Vorlage Bare.

Projekt

• Ninelands auf Reddit: eine Basic-Version von Ninelands als Reddit-Spiel (Devvit Web) für den Jam Reddit Game of the Day 2026 – https://redditgameofday2026.devpost.com/ (Regeln: /rules). Besitzer: Lukas Müllner (StackTeam). Mit dem Besitzer Deutsch sprechen.
• App-Name in devvit.json: ninelands-game. Ordner: /data/Documents/projects/ninelands-game.
• Repo: git@git.stackteam.at:DieLustigeTierwesen/ninelands-reddit.git (Forgejo, privat, angelegt 2026-11-13).
• Umfang und Phasen stehen in PLAN.md (vereinbart 2026-11-13): 9×9, nur Englisch, Karte des Tages mit Bestenliste, Streak und Ergebniskarte, kein Menü/Footer. Spieldesign entscheidet weiterhin der Besitzer.

Woher Fragen beantwortet werden

• Das Hauptspiel (Regeln, Engine, Gestaltung): Repo DieLustigeTierwesen/DokuHive, lokal /data/Documents/projects/hivedoku – dort README.md, hicedoku_plan.md (Entscheidungen „as built“), Leitfaden guide/chapters/. Bei Fragen zu Regeln oder Absicht dort nachlesen, nicht raten.
• Allgemeiner Spiele-Blueprint (Arbeitsweise, Fallstricke, Releases): Repo DieLustigeTierwesen/game-blueprint, lokal /data/Documents/projects/game-blueprint/AGENT.md. Erkenntnisse, die für künftige Spiele gelten (z. B. „wie baut man ein Devvit-Spiel“), dort nachtragen.

Grenzen zum Hauptspiel

• In /data/Documents/projects/hivedoku nichts ändern, committen oder pushen. Jeder Push auf dessen main deployt die Live-Seite; Releases dort (itch, Desktop, Android) laufen über npm run release und gehören nicht zu diesem Projekt.
• Die Engine von Ninelands (hivedoku/src/core, reines TypeScript ohne DOM/Server, seeded RNG, applyMove, legalMoves, Replay) darf übernommen werden – als Kopie mit festem Stand (z. B. Sync-Skript, das src/core von einem Ninelands-Tag holt und den Tag notiert). Die Kopie hier nicht von Hand ändern; Änderungen an der Engine gehören ins Hauptspiel. Achtung: src/core importiert JSON aus ../campaign/ und ../puzzles/ – nur mitnehmen, was die Basic-Version braucht.
• Lizenz: GPL-3.0 (entschieden 2026-11-13). Das Gerüst der Vorlage bleibt BSD-3-Clause (LICENSE-TEMPLATE.md). Fremd-Assets mit Nachweis in CREDITS.md: Musik CC BY-SA 4.0 (Nennung im Spiel nötig), Sprites CC0.

Jam – Regeln (Stand 2026-11-13)

Quelle: Übersichtsseite, vom Besitzer kopiert nach rules/ (lokal, in .gitignore). Devpost blockt automatische Abrufe (403).

• Abgabe: 9. Dezember 2026, 03:00 MEZ (Jam 11. Nov. bis 8. Dez.).
• Aufgabe: ein Daily Game auf Devvit Web (Interactive Posts): kurzer täglicher Ablauf, frische Inhalte (tägliche Challenges, Rätsel, Karten), leicht zu lernen, wiederspielbar.
• Portierung erlaubt: eigene Kategorie „Best Ported Daily Game“ (6.000 $). Das Original (die IP) muss man selbst besitzen; bei der Einreichung angeben, dass es eine Portierung ist.
• Einreichung: App-Listing auf developers.reddit.com und Demo-Post (Link zu einem Subreddit mit öffentlichem Post, in dem das Spiel läuft – danach wird bewertet, also selbsterklärend machen). Optional: Feedback-Umfrage. Kein Repo-Link, kein Video verlangt.
• Nicht veröffentlichen (devvit publish / App Review): hochladen und playtesten reicht, die App darf privat bleiben.
• Bewertung: Delightful UX, Polish (nahe an Veröffentlichungsqualität, Devvit-Regeln einhalten), „Reddit-y“ (Gemeinschaft, eigene Identität), Daily Content.
• Pluspunkte: schneller Einstieg ohne Textwände, klare eigene Optik, Startbildschirm mit Name/Datum/Statistik, Ergebniskarte am Ende (Statistik, Streak, Kommentar, Abo-Hinweis), Devvit Journeys für Ereignisse, Bestenliste und Streaks; Reddit-Funktionen wie Flair, Kommentare, Snoovatare.
• Nicht gewollt: offensichtliche „KI-Optik“ (KI-Nutzung ist erlaubt), Reddit-Klischees als Thema, bekannte Spielideen ohne eigenen Dreh, Spiele, die nicht auf Reddit laufen.
• Offizielle Regeln (rules/…rules.md, vom Besitzer kopiert):
  • Einreichung bis Di 8. Dez. 18:00 PT (= 9. Dez. 03:00 MEZ); Bewertung 9.–16. Dez., Gewinner ca. 17. Dez. Das Spiel muss während der Bewertung laufen (Tagesposts, Bestenliste) – in dieser Zeit keine riskanten Uploads.
  • Bestehende Projekte zählen nur, wenn sie ab dem 11. Nov. „significantly updated“ wurden, und das muss in der Einreichung erklärt werden. Die Devvit-Portierung ist eine neue Codebasis – das in der Beschreibung ausführen.
  • Pflicht: Textbeschreibung, App-Link developers.reddit.com/apps/ninelands-game, ausführliche README.md im Repo-Wurzelverzeichnis (Spiel und Anleitung, Englisch), Demo-Post in einem öffentlichen Subreddit mit < 200 Mitgliedern (oder App dr-admin-approve installieren).
  • Optional: Video (< 1 min, öffentlich auf YouTube/Vimeo), öffentliches Repo, Feedback-Umfrage. Die Jury darf auch nur nach Beschreibung, Bildern und Video urteilen → Video und Screenshots lohnen sich.
  • Nur Material mit passenden Rechten (Sprites CC0, Musik CC BY-SA mit Nennung – erfüllt). Ein Projekt gewinnt höchstens einen Preis. Teilnahme als Einzelperson oder Organisation (StackTeam) – entscheidet der Besitzer bei der Anmeldung.
  • Gleichstand: entscheidet zuerst „Delightful UX“.

Technik (Vorlage Bare)

• Devvit Web: Client src/client/ (Splash splash.ts → public/splash.html, Spiel game.ts → public/game.html), Server src/server/ (index.ts, server.ts, Speicher db.ts), gemeinsame Typen src/shared/api.ts. Gebaut mit esbuild nach public/ und dist/server/.
• Werkzeuge der Vorlage beibehalten: Biome (Lint + Format, npm run lint / npm run format) statt Prettier, Tests mit node --test (*.test.ts), Typprüfung tsc --build.
• Befehle: npm run test (Typen, Lint, Unit-Tests, Build – das ist die Prüfung vor jedem Merge), npm run playtest [r/sub] (baut, lädt hoch, installiert im Test-Subreddit), npm run publish (lädt hoch und stellt einen Review-Antrag bei Reddit – nur nach Rückfrage beim Besitzer).
• Node 24 über nvm (global ist 20): Befehle mit source ~/.nvm/nvm.sh && nvm use 24 >/dev/null && beginnen.
• Kein eigener Server, keine eigene Datenbank, keine eigenen Konten: Spieler sind Reddit-Nutzer, gespeichert wird über Devvit (Redis). Externe Netzaufrufe sind bei Devvit eingeschränkt – vor jeder Idee, die das Ninelands-Backend anspricht, in der Devvit-Doku prüfen (https://developers.reddit.com/docs).
• Aktuelle Devvit-Doku lesen, bevor etwas gebaut wird – die Plattform ändert sich schnell; nicht aus dem Gedächtnis arbeiten.
• Engine-Kopie: scripts/sync-engine.sh <ninelands-tag> (Stand in src/engine/VERSION), holt auch Sprites und Musik nach public/. src/engine/ nie von Hand ändern; Biome ignoriert es. Unit-Tests werden vor node --test mit esbuild gebündelt (die Engine importiert ohne Dateiendung).
• .github/workflows/ci.yaml stammt aus der Vorlage. Forgejo führt .github/workflows aus, wenn es kein .forgejo/workflows gibt; runs-on: ubuntu-latest ist der gemeinsame Hetzner-Runner (für npm run test reicht er).

Arbeitsweise

• Ein Branch pro Änderung (feat/…, fix/…, chore/…), auch für Doku.
• Merge nur, wenn npm run test mit Exit-Code 0 endet. Ausgabe in eine Log-Datei, dann $? prüfen – nie mit | grep … && oder ; verketten. Muster: npm run test > log 2>&1; code=$?; if [ $code -eq 0 ]; then … merge; fi.
• git merge --no-ff, Branch löschen, main pushen (sobald ein Remote existiert), im Bericht erwähnen.
• Conventional Commits; Ende jeder Nachricht: Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>.
• Code-Kommentare auf Deutsch.
• Größere Entscheidungen und Fallstricke in PLAN.md (Abschnitt „as built“, Deutsch) festhalten; am Ende eines Schritts Erkenntnisse von sich aus nennen.
• Innerhalb eines vereinbarten Plans selbstständig weitermachen; anhalten bei Spieldesign, Geschmack, externen Konten, Geld, Lizenz und allem, was öffentlich wird (devvit publish, Posts in echten Subreddits).
• Kein Geld ausgeben.

Geheimnisse – nie ausgeben, nie committen

• Devvit-Token ~/.devvit/token (Reddit-Anmeldung des Besitzers): nie lesen, ausgeben oder kopieren; die devvit-Befehle nutzen ihn selbst.
• Forgejo-Token ~/.config/forgejo-token: nur innerhalb von Befehlen lesen.
• Nutzer sollen nie Schlüssel in den Chat kopieren.

Stand (2026-11-13)

• Vorlage Bare committet, Repo DieLustigeTierwesen/ninelands-reddit angelegt, main gepusht. Lint der Vorlage repariert (Biome-Schema 2.6.4 → 2.6.6, package.json ohne Schlusszeilenumbruch); npm run test lokal grün.
• CI: Die parallel:-Stufe der Vorlage ersetzt (Forgejo-Runner v13: „Invalid run/uses syntax“), Schritte laufen nacheinander.
• PLAN.md angelegt, Lizenz auf GPL-3.0 umgestellt.
• Phase 0 erledigt (Engine v0.11.0, Tageskarte src/shared/daily.ts, Assets). Nächster Schritt: Phase 1.
• Texte und Checkliste für Devpost und Portal: docs/submission.md (neue Texte dort eintragen).
• Subreddit r/Ninelands angelegt (2026-11-13, Restricted). Bis zum Go-live postet der Besitzer dort nichts. App erst zum Go-live installieren: Die Installation legt sofort den Tagespost an (onAppInstall), danach postet der Scheduler täglich um 00:01 UTC.

Diese Datei bei neuen Arbeitsregeln und Entscheidungen aktualisieren.