70d10c4554
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NaZBZofC1on2gkSMb5UWZy
155 lines
6.8 KiB
Markdown
155 lines
6.8 KiB
Markdown
# Star-Edit — StarCraft-Kampagnen-MCP-Server ("Missions-Baumeister")
|
||
|
||
> **Status:** Planung / Spezifikation. Dieses Dokument hält den kompletten Auftrag
|
||
> fest, bevor Code gebaut wird. Es dient als verbindliche Vorlage für die Umsetzung.
|
||
|
||
## Ziel in einem Satz
|
||
|
||
Ein **MCP-Server**, der Claude in die Lage versetzt, aus der Kreativ-Seite einer
|
||
StarCraft-Brood-War-Kampagne (Story, Dialoge, Voiceover, Sounds, Missionsablauf)
|
||
echte, spielbare `.scm`/`.scx`-Missionsdateien zu bauen — also komplette
|
||
Missions-Logik, Texte und Sound-Einbettung.
|
||
|
||
**Wichtig:** Das **Gelände wird nicht generiert**. Jede Mission startet von einer
|
||
vorhandenen Basis-Karte als Leinwand; der Server bearbeitet nur die Daten-/Logik-
|
||
Sektionen darin.
|
||
|
||
## Rollenverteilung
|
||
|
||
- **Ich (Auftraggeber):** liefere die Kreativ-Seite — Story, Dialoge, Voiceover,
|
||
Sounds, Missionsablauf. Null Programmierkenntnisse. Will am Ende **einen Befehl**
|
||
ausführen und eine **URL** in Claude eintragen.
|
||
- **Claude + MCP-Server:** setzt die Kreativ-Vorlage in echte Missionsdateien um.
|
||
|
||
## Technische Basis
|
||
|
||
- **Karten-Manipulation:** Python-Bibliothek **RichChk** (PyPI: `richchk`).
|
||
- `pip install richchk` funktioniert; bringt StormLib mit, läuft auf Linux
|
||
(getestet — `StarCraftMpqIoHelper.create_mpq_io()` startet ohne Fehler).
|
||
- **Bestätigte Einstiegspunkte** (Signaturen vor dem Coden per Introspektion final
|
||
prüfen, da sie je nach Version leicht abweichen):
|
||
|
||
Lesen/Schreiben von Karten (MPQ-Container):
|
||
```python
|
||
from richchk.io.mpq.starcraft_mpq_io_helper import StarCraftMpqIoHelper
|
||
mpq_io = StarCraftMpqIoHelper.create_mpq_io()
|
||
rich_chk = mpq_io.read_chk_from_mpq("/pfad/map.scx") # -> RichChk-Modell
|
||
mpq_io.save_chk_to_mpq(rich_chk, "/pfad/basis.scx", "/pfad/out.scx")
|
||
```
|
||
|
||
Bearbeiten:
|
||
```python
|
||
from richchk.editor.richchk.rich_chk_editor import RichChkEditor
|
||
new_chk = RichChkEditor().replace_chk_section(neue_sektion, rich_chk)
|
||
rich_chk.get_sections_by_name(...) # vorhandene Sektionen abfragen
|
||
rich_chk.chk_sections # alle Sektionen
|
||
```
|
||
|
||
- **Fertige Editoren** unter `richchk.editor.richchk.*`:
|
||
**trig** (Trigger), **mrgn** (Locations), **unis/unix** (Einheiten-Werte),
|
||
**forc** (Forces/Fraktionen), **ownr** (Owner), **side** (Rassen),
|
||
**swnm** (Switches), **uprp** (Unit Properties), **wav** (Sounds).
|
||
- **Rich-Modelle** (Trigger, Conditions, Actions, Locations, …) unter
|
||
`richchk.model.richchk.*`.
|
||
|
||
**Herzstück = Trigger.** Fast die gesamte Kampagnen-Logik wird über Trigger
|
||
abgebildet: Gegnerwellen, Verstärkungen, Einheiten spawnen, Story-Text einblenden,
|
||
Funksprüche mit Portrait, WAV-Sounds abspielen, Missionsziele, Sieg/Niederlage,
|
||
Timer, AI-Skripte starten. Das Trigger-Tool muss ausdrucksstark und gut
|
||
dokumentiert sein (unterstützte Condition-/Action-Typen in der Tool-Beschreibung).
|
||
|
||
### Erster Arbeitsschritt (vor dem Tool-Coding)
|
||
|
||
1. `richchk` installieren.
|
||
2. README/Quellen des GitHub-Repos "richchk" lesen.
|
||
3. Installiertes Paket per Introspektion inspizieren, um die echten Klassen für
|
||
Trigger (Conditions/Actions), Locations, Forces etc. zu lernen.
|
||
4. **Keine erratenen Methodennamen** schreiben.
|
||
|
||
## Stack & Architektur
|
||
|
||
| Aspekt | Wahl |
|
||
|---------------|------|
|
||
| Sprache | Python 3.12 |
|
||
| MCP-Framework | FastMCP (offizielles `mcp`-SDK, `pip install "mcp[cli]"`) |
|
||
| Transport | stdio (lokaler Test) + **Streamable HTTP** (Dauerbetrieb VPS) |
|
||
| Betrieb | Docker-Container, eingebunden ins bestehende docker-compose Setup |
|
||
| Reverse-Proxy | Caddy (läuft bereits) → TLS-Subdomain, z.B. `sc-mcp.pixel-by-design.de` |
|
||
| Karten-Volume | gemountetes Volume (z.B. `/data/maps`) für Basis-Karten, WAVs, Missionen |
|
||
|
||
## Tools (Prefix `sc_`)
|
||
|
||
| Tool | Zweck | Hints |
|
||
|------|-------|-------|
|
||
| `sc_list_maps` | listet `.scm`/`.scx`-Dateien im Karten-Verzeichnis | readOnly |
|
||
| `sc_describe_map` | menschenlesbare Übersicht: Tileset, Größe, Forces/Player-Setup, Rassen, Locations, Trigger-Zusammenfassung | readOnly |
|
||
| `sc_list_locations` | Locations (MRGN) auflisten | readOnly |
|
||
| `sc_create_location` | Location anlegen | — |
|
||
| `sc_rename_location` | Location umbenennen | — |
|
||
| `sc_set_player_setup` | Forces (forc), Owner (ownr), Rassen (side) setzen | — |
|
||
| `sc_add_trigger` | **Kern-Tool.** Trigger mit Conditions + Actions + betroffenen Playern hinzufügen | — |
|
||
| `sc_list_triggers` | Trigger auflisten | readOnly |
|
||
| `sc_remove_trigger` | einzelnen Trigger entfernen | destructive |
|
||
| `sc_clear_triggers` | alle Trigger entfernen | destructive |
|
||
| `sc_embed_wav` | WAV-Datei einbetten und referenzierbar machen (wav-Editor) | — |
|
||
| `sc_save_map` | bearbeitetes Modell als neue `.scm`/`.scx` schreiben (`save_chk_to_mpq`, Basis-Karte als Vorlage) | — |
|
||
| `sc_set_briefing` | **optional / experimentell.** Mission-Briefing (MBRF). Falls kein High-Level-Editor: als TODO markieren, kein Blocker | — |
|
||
|
||
### `sc_add_trigger` — Mindest-Abdeckung
|
||
|
||
Strukturierte Eingabe (Liste von Conditions, Liste von Actions, betroffene Player).
|
||
Muss u.a. abdecken:
|
||
- Einheiten erzeugen an Location
|
||
- Text einblenden (Display Text Message)
|
||
- Transmission mit Portrait + WAV
|
||
- Play WAV
|
||
- Sieg-/Niederlagebedingungen
|
||
- Timer
|
||
- AI-Skript ausführen
|
||
|
||
### Anforderungen pro Tool
|
||
|
||
- Klare Beschreibung.
|
||
- Sinnvolle **Pydantic**-Eingabeschemas mit Feldbeschreibungen.
|
||
- Hilfreiche Fehlermeldungen, z.B.
|
||
`"Location 'Basis' existiert nicht – verfügbar: …"`.
|
||
- `readOnlyHint`/`destructiveHint`-Annotationen passend gesetzt.
|
||
|
||
## Definition of Done — Selbsttest
|
||
|
||
Ein kurzer Selbsttest beweist die ganze Pipeline:
|
||
|
||
1. Basis-Karte aus `/data/maps` laden.
|
||
2. Eine Location anlegen.
|
||
3. Per Trigger hinzufügen: bei Spielstart eine Texteinblendung
|
||
`"Mission 1 – Start"` **und** das Erzeugen von ein paar Einheiten an der Location.
|
||
4. Als neue `.scx` speichern.
|
||
5. Neue Datei erneut laden und bestätigen, dass Trigger + Location wirklich drin sind.
|
||
|
||
Läuft das durch, steht das Fundament.
|
||
|
||
## Liefergegenstände
|
||
|
||
- [ ] Server läuft als Docker-Service, erreichbar über die TLS-Subdomain.
|
||
- [ ] **Ein** Start-/Neustart-Befehl.
|
||
- [ ] Die Connector-URL für Claude (Custom Connector).
|
||
- [ ] Beispiel-Basis-Karte liegt bereits in `/data/maps`.
|
||
- [ ] `README.md` mit Startbefehl, Subdomain-URL und Anleitung für den Custom
|
||
Connector in Claude.
|
||
|
||
## Defaults / Entscheidungen
|
||
|
||
> Hier werden während der Umsetzung die getroffenen Default-Entscheidungen
|
||
> dokumentiert, damit am Ende klar ist, was gewählt wurde (keine technischen
|
||
> Rückfragen, wo selbst entscheidbar).
|
||
|
||
- _(wird ergänzt)_
|
||
|
||
## Offene TODOs
|
||
|
||
- [ ] `richchk` installieren & per Introspektion echte Klassen verifizieren.
|
||
- [ ] Projektstruktur (FastMCP-Server, Pydantic-Schemas, Tool-Module) anlegen.
|
||
- [ ] Self-Test-Skript schreiben.
|
||
- [ ] Dockerfile + docker-compose-Service + Caddy-Reverse-Proxy-Eintrag.
|
||
- [ ] Beispiel-Basis-Karte bereitstellen.
|
||
- [ ] `sc_set_briefing` (MBRF) als best-effort prüfen.
|