rpg-westreiche/AGENTS.md

13 KiB
Raw Blame History

Projekt-Hinweise: RPG Westreiche

FTP-Zugang (Deployment)

Zugangsdaten stehen in credentials.txt im Projektwurzelverzeichnis (per .gitignore ausgeschlossen, niemals committen).

  • Methode: explizites FTPS – also klassisches ftp:// auf Port 21 mit erzwungener TLS-Aushandlung (--ssl-reqd / AUTH TLS).
  • Nicht verwenden: unverschlüsseltes FTP (Server antwortet 550 SSL/TLS required on the control channel) und implizites FTPS (ftps:// auf Port 990 – läuft in einen Timeout).
  • Host: FTP_URL aus credentials.txt (z. B. www19.your-server.de), Login FTP_USER, Passwort FTP_PASSWORD.

Weitere Schlüssel in credentials.txt

  • APP_DIRECTORY (westreiche_website) – ausschließlich für die geplante Web-App. Alle bestehenden Veröffentlichungen bleiben, wo sie sind: Website/Protokolle/Regel-Changelog weiter nach public_html/, PDF-Handouts (Spiel-Zusammenfassungen, Zauber-/Liturgie-Summarien, SL-Material) bleiben lokal in RPG/7-Prep/… bzw. am bisherigen Ablageort. Nichts davon in APP_DIRECTORY verschieben oder umleiten.
  • DB_HOST (mxzh.your-database.de, Hetzner Managed MariaDB) + DB_NAME, DB_USER, DB_PASSWORD – erreichbar über Port 3306 von außen, DB derzeit ohne Tabellen. Achtung: In der Datei steht ein nachgestelltes Leerzeichen, vor Nutzung trimmen (tr -d '[:space:]'). Nicht FTP_URL als DB-Host nutzen.

Upload-Befehl

set -a; . ./credentials.txt; set +a

# Verzeichnis listen
curl -s -S --ssl-reqd --user "$FTP_USER:$FTP_PASSWORD" \
  "ftp://$FTP_URL/" --list-only

# Einzelne Datei hochladen
curl -s -S --ssl-reqd --user "$FTP_USER:$FTP_PASSWORD" \
  -T lokal/datei.html "ftp://$FTP_URL/public_html/datei.html"

# Verzeichnis rekursiv hochladen
curl -s -S --ssl-reqd --user "$FTP_USER:$FTP_PASSWORD" \
  -T ./lokal/ "ftp://$FTP_URL/public_html/"

Beim rekursiven Upload keine abschließende Slash-Verwechslung: -T ./dir/ lädt den Inhalt von dir/ in das Zielverzeichnis.

Server-Struktur (Wurzelverzeichnis)

public_html, westreiche, www_logs, tippspiel_backup, vmail, .phpversion, .tmp.

Web-App: Charakterverwalter (westreiche_website/)

Geschlossene PHP/MariaDB-App für Charakterbögen (OSE-alike), technische Basis wie ../drink-it-cold (kein Composer, server-gerendertes HTML). Theme analog zauberturm.de: Nachtblau/Schwarz/Gold, Pergament, Animationen.

  • Ort: westreiche_website/ im Repo = public_html/westreiche_website/ auf dem Server (App-Wurzel, base_path = /westreiche_website).
  • Deploy:
    cd westreiche_website && ./tools/deploy_app.sh --dry-run   # Vorschau
    ./tools/deploy_app.sh                                      # hochladen
    
    Das Skript liest credentials.txt und erzeugt app/config.local.php (gitignored) mit DB_HOST/DB_NAME/DB_USER/DB_PASSWORD, APP_DIRECTORY (als base_path) und INSTALL_TOKEN. app/, views/, sql/, storage/ sind per .htaccess gesperrt.
  • Installation / erster Admin: …/install.php?token=$INSTALL_TOKEN (legt Tabellen, Kataloge und das erste Admin-Konto an). Eingerichtet: Benutzer Torsten mit Rolle admin. Danach zeigt install.php nur noch einen Hinweis.
  • Login mit Benutzername oder E-Mail; Konten nur durch den Admin, entweder mit Startpasswort oder per Einladungslink (7 Tage, einmalig).
  • Datenmodell: users, user_invites, auth_tokens, login_attempts, characters, skills + character_skills, spells + character_spells, character_items, weapons/armors (Katalog) + character_weapons/ character_armors. Attributsboni nach Hausregel V1.1.
  • Fertigkeitengruppen: WS_SKILL_CATALOG in app/rules.php bildet den Charakterbogen (RPG/6-Dokumente/Charakterbogen.pdf) 1:1 ab: 33 Fertigkeiten in den Gruppen Körper, Wildnis, Sozial, Wissen (Reihenfolge = WS_SKILL_GROUPS). skills_sync_catalog() gleicht die DB an diese Liste an – nach Änderungen dort einmal aufrufen (Installer tut es automatisch), alte Einträge landen unter „Sonstiges“.
  • Startwerte: neue Bögen bekommen alle Katalogfertigkeiten mit Fertigkeitsstufe = Attributsbonus; Rettungswürfe stammen aus WS_SAVE_TABLES (app/rules.php, OSE-SRD-Werte, Westreiche-Klassen auf die Grundklassen abgebildet) und werden bei Stufen-/Klassenwechsel neu gesetzt. Falls der SL eigene RW-Tabellen führt: dort in app/rules.php ändern, nicht in der DB.
  • Ableitungen im Bogen: Trefferwurf = Grundangriff + Attributsbonus (Nahkampf STR, Fernkampf DEX) + Waffenbonus; Schaden = Würfel + Bonus; RK = 10 + DEX-Bonus + angelegte Rüstung (Feld characters.ac = manueller Override, leer/0 = automatisch). Waffen-/Rüstungskatalog: sql/seed_equipment.sql, Admin-Ansicht /admin/equipment.
  • Zauberkatalog wird aus dem Vault erzeugt: python3 tools/build_spell_seed.py → westreiche_website/sql/seed_spells.sql (147 arkane Zauber, 74 Liturgien). Nach neuen Zauberdateien erneut bauen, hochladen und in einer frischen Installation einspielen.
  • PDF-Export: eigener kleiner PDF-Writer (app/pdf.php + app/sheet.php), A4-Pergamentbogen mit Goldrahmen – kein Composer, keine externen Dienste. JPEG-Bilder werden als XObject eingebettet.
  • Porträts: Upload im Bogen (POST /characters/{id}/portrait), serverseitig per GD neu als JPEG kodiert (max. 900 px) nach uploads/portraits/ (gitignored, PHP-Ausführung dort gesperrt). Ohne Upload greift assets/portraits/<klasse>.webp – 12 gemalte Platzhalter, mit fal.ai (flux/schnell) erzeugt; Skript-Idee: Prompts im Chat dokumentiert.
  • Website-Nav: tools/build_site.py hat APP_CHARACTERS_URL (https://zauberturm.de/westreiche_website/) – Nav-Punkt „Charaktere“ auf allen Seiten plus Karte auf der Startseite. Nach Änderungen dort build_site.py + deploy_web.sh laufen lassen.

Website (zauberturm.de)

Statischer Auftritt, aus dem Vault generiert:

python3 tools/build_site.py     # baut web/ (Startseite, Galerie, Protokolle, Regel-Changelog)
./tools/deploy_web.sh           # Upload nach public_html/ per FTPS
./tools/deploy_web.sh --dry-run # nur zeigen, was hochgeht
  • web/index.php – Startseite mit beiden Projekten (aktuell nur Westreiche + Regel-Changelog)
  • web/weltenauge.php – Bildergalerie, liest serverseitig public_html/weltenauge/. Ruht seit 20.11.2026: Schalter SHOW_WELTENAUGE = False in tools/build_site.py → Seite wird nicht gebaut, Nav-Punkt und Startseiten-Karte entfallen, Footer sagt nur „Westreiche“. Zum Wiederbeleben: Schalter auf True, bauen, deployen (das Deploy-Skript lädt die Seite dann automatisch mit). Der Bilderordner public_html/weltenauge/ bleibt auf dem Server unberührt, public_html/weltenauge.php wurde gelöscht (FTP DELE). Zusätzlich liegt dort eine .htaccess mit Require all denied – Bilder sind auch per Direkt-URL 403 (vorher 200, also direkt verlinkbar). Zum Reaktivieren: .htaccess löschen, dann SHOW_WELTENAUGE = True setzen.
  • web/westreiche/index.html + protokolle/*.html – nur die Protokolle; (Notizen)-Dateien sind per PUBLISH_KINDS in tools/build_site.py ausgeschlossen (Spieltisch-Notizen bleiben im Vault). PUBLISH_KINDS steht auf {"Geschehnisse"}: Notizen und ältere Kurzprotokolle (Protokoll Sitzung #N.md) werden nicht veröffentlicht, weil sie redundant zu den Geschehnissen sind.
  • web/westreiche/regeln.html – datiertes Changelog aller Hausregel-Änderungen (Nav-Punkt „Regeln"). Quelle ist RPG/5-Regeln/Hausregeln/Regeländerungen (Changelog).md; build_regeln() in tools/build_site.py rendert sie, neueste Einträge oben. Achtung: Diese Datei ist eine Spieler-Übersicht – wenige, offizielle Einträge. Neue Einträge nur mit ausdrücklicher Zustimmung des SL; Arbeitsstände und Details gehören in die jeweilige Hausregeldatei, nicht hierher (Format im Kopf der Datei: Datum + Betrifft/Vorher/Jetzt/Warum/Am Tisch, Zeilen nicht umbrechen), damit Website und Vault nicht auseinanderlaufen.
  • web/assets/style.css, web/assets/logo_zauberturm.png (per fal.ai erzeugt)

Hochgeladen wird ausschließlich web/; Bilder im Galerieordner werden nie überschrieben. Alte index.php liegt als index.php.alt auf dem Server, der frühere Bildordner image_log/ wurde nach weltenauge/ umbenannt. FTP-Rename braucht absolute Pfade (RNFR /public_html/...).

Wissenslandkarte

Schnellzugriff auf Spieler, Welt, Regeln und Konventionen: .pi/wissensindex.md – bei Fragen zu Figuren, Fraktionen, Hausregeln oder Dateistruktur zuerst dort nachsehen, statt den Vault zu durchsuchen. Wichtige Einstiege: RPG/2-Spieler/ (je ein Ordner pro Spieler), RPG/1-Sessions/Geschehnisse-Index.md, RPG/3-Welt/Weltstatus & Offene Enden.md, RPG/5-Regeln/Hausregeln/ (vorrangig vor SRD), RPG/offene_faeden.md.

Sitzungsprotokolle

Roh-Mitschnitte (~/Dokumente/whisper/*.txt) werden mit dem festen Prompt tools/prompt_sitzung_kondensieren.md zu Protokoll Sitzung NNN (Geschehnisse).md verdichtet. Diese Kondensate sind maßgeblich, stehen im RPG/1-Sessions/Geschehnisse-Index.md und werden als web/westreiche/protokolle/ veröffentlicht (PUBLISH_KINDS = {"Geschehnisse"}). Bei neuen Sitzungen: Prompt verwenden, Datei exakt so benennen, Index ergänzen.

Tooling

Setup (einmalig, gilt für Linux und macOS):

python3 -m venv .venv
.venv/bin/pip install -r tools/requirements.txt   # reportlab, markdown, pillow

Systemwerkzeuge: ghostscript (A4-Skalierung in den PDF-Builds), pandoc (ODT-Konvertierung), DejaVu-Schriften. Auf macOS per Homebrew: brew install ghostscript pandoc && brew install --cask font-dejavu. Die Schriften suchen die Skripte über tools/fontpicker.py (Linux-Pfade, ~/Library/Fonts, Override WESTREICHE_FONT_DIR). Alle PDF-Skripte und build_site.py mit .venv/bin/python starten – das System-Python bringt weder reportlab noch markdown mit.

  • tools/md2odt.sh, tools/make_reference_odt.py, tools/autowidth.lua: Markdown → ODT-Konvertierung für Druckmaterial.
  • tools/build_zauber_almanach.py: erzeugt das PDF-Handout RPG/7-Prep/prep_2026-11-20/Arkane Zaubersprueche - Summarium von Rambastulon.pdf (Titelblatt, Vorwort, Gildenregeln, Zauber nach Grad, Kurzreferenz) direkt aus RPG/5-Regeln/Zauber/Arkan/Grad */*.md. Braucht reportlab (python3 -m venv .venv && .venv/bin/pip install reportlab, ohne pandoc).
  • tools/build_liturgie_summarium.py: klerikales Gegenstück – erzeugt RPG/7-Prep/prep_2026-11-20/Goettliche Liturgien - Summarium fuer Terian.pdf (Titelblatt, Vorwort von Vater Damian, Hausregeln aus Liturgien und Glaubensgemeinschaften, Liturgien nach Grad mit „Gelehrt von“, Kurzreferenz, Anhang Naturzirkel).
  • tools/build_sl_tabellen.py: SL-Handout zum Ausdrucken (RPG/7-Prep/prep_2026-11-20/SL-Tabellen - Ausbrennen und Entrueckung.pdf, A4; mit --a5 als Heftchen nach RPG/7-Prep/prep_2026-11-20/pdf_export/SL-Tabellen - Ausbrennen und Entrueckung (A5).pdf) – liest die Burnout-Tabelle aus RPG/3-Welt/Geheimnisse/Es gibt kein unbegrenztes Zaubern.md und die Entrückungstabelle aus Liturgien und Glaubensgemeinschaften §9. SL-Wissen, nie veröffentlichen.
  • tools/build_sl_schirm.py: baut den verdeckten SL-Schirm (A5 quer, 8 Karten: Fraktionen, offene Fäden als „Uhren“, NSC-Register, Gruppenstatus, Hausregeln, Improvisationshilfen, Kalender, Reveal-Warteschlange) nach RPG/7-Prep/<prep>/SL Schirm/SL-Schirm (A5 quer).pdf. Inhalt und Layout sind getrennt: die Karten stehen als Markdown in SL Schirm/SL-Schirm Inhalt.md (## Karte … = eine Seite, farbe: = Farbcode, Pipe-Tabellen + Stichpunkte; Frontmatter titel/untertitel/ingame – ingame steht im Kopf jeder Seite). Für eine neue Prep-Session die Markdown-Datei kopieren, aktualisieren und build_sl_schirm.py -s … -o … neu bauen – das Skript muss dafür nicht angepasst werden. Ebenfalls SL-Wissen.
  • tools/pdf_sync.py: hält die ausgelagerten Fremd-PDFs (Regelwerke, Abenteuer, Magazine, ~1 GB) synchron. Sie liegen nicht in Git, sondern auf dem Server unter pdf_archiv/blobs/<sha256>.pdf – außerhalb von public_html, also für Crawler unerreichbar. tools/pdf_manifest.json (Pfad → SHA-256 + Größe) ist versioniert und lädt einen frischen Checkout nach: --pull; hochladen: --push; prüfen: --check; Manifest neu schreiben: --scan. Auf dem Server liegt zusätzlich pdf_archiv/index.json (dieselbe Tabelle), damit das Archiv auch ohne Repo lesbar bleibt. Eigene Handouts (Summarien, SL-Tabellen, SL-Schirm) bleiben bewusst in Git.
  • tools/add_guild_notes.py / tools/add_gemeinschaft_notes.py: schreiben die Zugangs-Abschnitte (## Gilde bzw. ## Gemeinschaft) in die Zauberdateien – inkl. Sonderlehrstätten (Tote erwecken & Co., Hausregel §3.5). Nach Änderung der MAPPING-Tabellen --force laufen lassen und das PDF neu bauen.