# Werkzeuge

Hilfsmittel für den Spieltisch – und ein kleines **Portal**, das sie
zusammenführt.

## Portal

`index.php` zeigt alle Werkzeuge als Übersicht und öffnet sie in einem
gemeinsamen Rahmen. Das Portal **durchsucht beim Aufruf seinen eigenen
Ordner**: Jeder Unterordner mit einer Startseite wird als Werkzeug
aufgeführt. Es muss nirgends eine Liste gepflegt werden.

Dafür wird **PHP 8.4 oder neuer** gebraucht. Zum Ausprobieren genügt der
eingebaute Server:

```
cd Werkzeuge
php -S localhost:8000
```

und dann <http://localhost:8000/> im Browser öffnen.

## Auf einen Webserver hochladen

Der fertige Stand liegt im Ordner [`_Export`](../_Export) – **schon gebaut,
nichts auszuführen**. Den Inhalt in den Webordner legen, fertig. Ein
Unterordner geht genauso, etwa `https://beispiel.de/dungeonslayers/`; alle
Pfade sind relativ. Rechte wie üblich (Ordner `755`, Dateien `644`),
geschrieben wird nichts. Danach einmal `pruefung.php` aufrufen – die Seite
sagt, ob alles passt, und darf anschließend gelöscht werden.

In `_Export` liegt derselbe Stand zusätzlich als
`dungeonslayers-werkzeuge.zip`, falls ein Archiv bequemer ist.

**Voraussetzungen**

- PHP 8.4 oder neuer (nur für das Portal – die Werkzeuge selbst sind reines
  HTML und JavaScript)
- keine Datenbank, keine Erweiterungen, keine Schreibrechte

**Serverkonfiguration**

Für Apache liegt eine `.htaccess` bei: Startseite `index.php`, keine
Ordnerlisten, UTF-8, versteckte Dateien gesperrt, Zwischenspeicher für CSS
und JavaScript. Bei nginx oder Caddy gehören dieselben Punkte in die
Serverkonfiguration:

```nginx
index index.php index.html;
autoindex off;
location ~ /\. { deny all; }
```

**Nach Änderungen**

`_Export` wird aus diesem Ordner erzeugt:

```
sh Werkzeuge/export-auffrischen.sh
```

Das gehört zu jeder Änderung an einem Werkzeug oder am Portal dazu, damit
der Auslieferungsstand nicht hinterherhinkt.

**Neues Werkzeug nachreichen**

Ordner hochladen – fertig. Das Portal liest bei jedem Aufruf neu ein, es
muss nichts angepasst werden.

## Die Werkzeuge laufen auch ohne Portal

Jedes Werkzeug ist für sich vollständig: Ein Doppelklick auf seine
`index.html` genügt, ohne Server, ohne PHP, ohne Internet. Die Anbindung ans
Portal ist reine Zugabe – fehlt sie, ändert sich am Werkzeug nichts.

Ein Werkzeug erkennt selbst, wie es geladen wurde
(`window.WERKZEUG_PORTAL`):

| Lage | Bedeutung | Wirkung |
|---|---|---|
| `eigenstaendig` | direkt geöffnet | nichts ändert sich |
| `imRahmen` | im Portal eingebettet | eigene Überschrift wird ausgeblendet, das Werkzeug meldet Name und Fassung ans Portal |
| `ausPortal` | aus dem Portal in eigenem Fenster (`?portal=1`) | ein Rücksprung „← Werkzeuge" erscheint |

## Inhalt

| Ordner | Werkzeug |
|---|---|
| [`Szenengenerator`](./Szenengenerator) | Übersichtskarten und bespielbare Flächen erzeugen, nachzeichnen, als PDF und JSON ausgeben |
| [`_Vorlage`](./_Vorlage) | Gerüst zum Kopieren für ein neues Werkzeug |
| [`gemeinsam`](./gemeinsam) | geteilte Gestaltung, Portal-Logik und Portal-Anbindung |

## Ein Werkzeug ergänzen

1. `_Vorlage` kopieren und ohne führenden Unterstrich benennen.
2. `werkzeug.json` ausfüllen – Name, Symbol, Kurztext, Punkte, Fassung.
3. Im Kopf der Startseite dieselben Angaben als
   `<meta name="werkzeug-…">` setzen und
   `../gemeinsam/portal-anbindung.js` einbinden.
4. Eigene Inhalte einbauen, `README.md` und `CHANGELOG.md` anlegen.

Beim nächsten Aufruf steht das Werkzeug im Portal. Ordner, die mit `_`
beginnen, sowie `gemeinsam` bleiben außen vor.

### werkzeug.json

```jsonc
{
  "name": "Szenengenerator",     // Anzeigename
  "symbol": "🗺️",                 // Zeichen auf der Karte im Portal
  "version": "1.0.0",            // HAUPT.NEBEN.KORREKTUR
  "stand": "fertig",             // sonst z. B. "in Arbeit" – steht dann auf der Karte
  "start": "index.html",         // Startseite im Ordner
  "kurz": "Ein Satz zum Werkzeug.",
  "punkte": ["Stichpunkt", "Stichpunkt"]
}
```

Fehlt die Datei, nimmt das Portal den Titel und die Beschreibung aus der
Startseite – gefunden wird das Werkzeug trotzdem.