rpg-westreiche/AGENTS.md

229 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```bash
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:**
```bash
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:
```bash
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):**
```bash
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.