Star-Edit/docs/research/CAMPAIGN-RESEARCH.md

# Star-Edit MCP — Grounded Research Report für eine SC:BW-Kampagnen-Vorlage

> Geltungsbereich: Der Star-Edit-MCP-Server bearbeitet ausschließlich **Daten/Logik existierender Karten** (Trigger, Texte, Locations, Player-Setup, Sounds). **Kein Terrain-Generieren.** Jede Mission startet von einer bestehenden Basis-Karte in `SC_MAPS_DIR` (Default `/data/maps`). Alle Fähigkeitsaussagen in Abschnitt A sind strikt aus dem Quellcode abgeleitet — autoritativ sind `server.py`, `triggers.py`, `enums.py`, `workspace.py`. Abschnitt B/C/D verknüpfen das mit der SC:BW-Domänenforschung.

---

## A) Was Star-Edit heute wirklich kann

### A.1 Architektur & Session-Modell

- **Server:** `FastMCP("starcraft-campaign-mcp")` mit **13** `sc_`-Tools. Transport per Env `SC_TRANSPORT` (Default `stdio`; Streamable-HTTP-Branch unter `http://0.0.0.0:8000/mcp` vorhanden, server.py:505–511). *(Hinweis: Der oft genannte Docker-Default `http`, die Python-3.12-Laufzeit und konkrete Dependency-Pins wie `richchk==0.1.1`/`mcp[cli]==1.28.0`/`PyYAML>=6.0` lassen sich aus den vier autoritativen Quelldateien `server.py`/`triggers.py`/`enums.py`/`workspace.py` **nicht** verifizieren — sie stammen aus `Dockerfile`/`requirements.txt`, die hier nicht als geprüfte Quelle vorliegen, und sind daher unbestätigt.)*
- **Session = Dateiname.** Es gibt **keinen** Session-Token. Jeder Tool-Call ruft `workspace.open_workspace(map)`; Schlüssel ist `os.path.basename(map)`. Workspaces liegen in einem **prozessweiten Singleton-Dict** (`_WORKSPACES`, lock-geschützt) und leben **so lange wie der Prozess** — kein TTL, keine Per-Client-Isolation. Alle Aufrufer im Prozess teilen sich denselben Workspace pro Karte.
- **In-Memory-Editmodell.** Edits ersetzen ganze CHK-Sektionen (`Workspace.replace(...)`) und akkumulieren auf dem gecachten Workspace. **Nichts wird auf Platte geschrieben außer bei `sc_save_map`.** Edit-Tools liefern `"hinweis": "Aenderung ist im Speicher. Mit sc_save_map persistieren."`
- **Basis-Karte unangetastet.** `sc_save_map` schreibt **immer eine neue Ausgabedatei** (Basis als Template). Aus einer Basis lassen sich viele Missionen erzeugen.
- **Reset/Discard.** `sc_reset_map` → `open_workspace(map, fresh=True)`: liest frisch von Platte, **verwirft alle ungespeicherten Edits**.
- **Pfad-Confinement.** `map_path()` reduziert jeden Namen auf `basename` → kein Ausbrechen aus `SC_MAPS_DIR`. Gilt für Lesen, Speichern und WAV-Quellen.
- **Fehler:** Validierungsfehler werfen (`ValueError`/`FileNotFoundError`/`KeyError`/`FileExistsError`), statt Error-Dicts zurückzugeben.
- **Annotations:** `_READONLY`, `_EDIT`, `_DESTRUCTIVE` (Letzteres: `sc_remove_trigger`, `sc_clear_triggers`, `sc_reset_map`; server.py:352, 379, 463).

### A.2 Die 13 Tools (Signatur + Kernverhalten)

**Read**
| Tool | Parameter | Liefert / Verhalten |
|---|---|---|
| `sc_list_maps` | — | `{maps_dir, count, maps}` aus `workspace.list_maps()` (alle `.scm`/`.scx` in `MAPS_DIR`). |
| `sc_describe_map` | `map` | Überblick: `tileset`, `size{width,height}`, **genau 8** `players` (PLAYER_1..8; fehlend → `"?"`), `forces`, `locations` (Box `[left_x1,top_y1,right_x2,bottom_y2]`), `trigger_count`, `triggers` (Klartext-Summaries), `pending_wav_embeds`. Spiegelt In-Memory-Stand. |
| `sc_list_locations` | `map` | Locations mit `name`/`index`/`box`. |
| `sc_list_triggers` | `map` | `trigger_count` + pro Trigger `index`, `players`, Bedingungs-/Aktions-Summaries. |

**Location**
| Tool | Parameter (Defaults) | Verhalten / Grenzen |
|---|---|---|
| `sc_create_location` | `map`, `name`, `center_x`, `center_y`, `width=96`, `height=96` | `ws.add_location(...)`. Name muss **eindeutig** sein (sonst `ValueError`). Liefert `index` + `box`. Tool-Doku nennt explizit die Konvention „Koordinaten in Pixeln (32 px = 1 Kachel)" (server.py:173–174). |
| `sc_rename_location` | `map`, `old_name`, `new_name` | Umbenennen; wirft bei fehlendem `old_name` oder kollidierendem `new_name`. Kein `hinweis` im Return (server.py:209 liefert `{"ok", "name", "index"}`). |

**Player-Setup**
| Tool | Parameter | Verhalten |
|---|---|---|
| `sc_set_player_setup` | `map`, `players: list[dict]`, `force_names: Optional[list[dict]]=None` | Pro Eintrag `player` **Pflicht** (`KeyError` sonst, server.py:242); `type`/`race`/`force` optional. Setzt OWNR/SIDE/FORC; `force_names` benennt FORCE_1..4 (`force`+`name` Pflicht, server.py:271–272). |

Erlaubte Strings (toleranter Resolver, case-insensitiv, Identifier/Display-Name/Numeric-ID):
- **type (OWNR):** `INACTIVE, COMPUTER_GAME, HUMAN_OCCUPIED, RESCUE_PASSIVE, COMPUTER, HUMAN, NEUTRAL, CLOSED`
- **race (SIDE):** `ZERG, TERRAN, PROTOSS, INDEPENDENT, NEUTRAL, USER_SELECT, RANDOM, INACTIVE`
- **force:** `FORCE_1..FORCE_4`

**Trigger**
| Tool | Parameter (Defaults) | Verhalten / Grenzen |
|---|---|---|
| `sc_add_trigger` | `map`, `players: list[str]`, `conditions: list[Condition]`, `actions: list[Action]`, `preserve=True` | Fügt **genau einen** Trigger an. `players` leer → `ValueError`; jeder Eintrag via `resolve_player`, dedupliziert in `set`. `conditions` leer → **`always`**. `preserve=True` hängt `PreserveTrigger()` an (zählt als Aktion!). Ohne Aktion **und** `preserve=False` → `ValueError`. |
| `sc_remove_trigger` | `map`, `index` | Entfernt Trigger per 0-basiertem Index; Out-of-Range → `ValueError`. |
| `sc_clear_triggers` | `map` | Entfernt **alle** Trigger. Nur per `sc_reset_map` rückholbar. |

**Sound / Save / Reset**
| Tool | Parameter (Defaults) | Verhalten |
|---|---|---|
| `sc_embed_wav` | `map`, `wav_filename` | WAV **muss als Datei in `MAPS_DIR` liegen** (Existenzprüfung `os.path.exists` im Tool, server.py:408). Registriert In-MPQ-Pfad `staredit\wav\<basename>` und queued physisches Einbetten (`pending_wavs`). Liefert `wav_path` (= genau diesen In-MPQ-Pfad) für `play_wav`. Fehlende Datei → `FileNotFoundError` mit Liste verfügbarer `.wav`. |
| `sc_save_map` | `map`, `output_name`, `overwrite=False` | Schreibt neue `.scm`/`.scx`. Endung `.scx` wird **nur** auto-ergänzt, wenn der Name nicht bereits auf `.scx` **oder** `.scm` endet (workspace.py:178–180) → ein angegebenes `.scm` bleibt erhalten. Existiert Ziel & `overwrite=False` → `FileExistsError`. Bettet `pending_wavs` physisch ein. Liefert `output`, `path`, `embedded_wavs`, `triggers`, `locations`. **Leert `pending_wavs` nicht** → erneutes Speichern bettet erneut ein. |
| `sc_reset_map` | `map` | Frisch von Platte; verwirft Edits. |

### A.3 Unterstützte Trigger-CONDITIONS (exakte `type`-Strings)

`type` wird `strip().lower()`-normalisiert. `comparator` Default `AT_LEAST` (`AT_LEAST`/`AT_MOST`/`EXACTLY`; triggers.py:143). `amount` ist bei allen Vergleichs-Conditions effektiv Pflicht (`_require`-geprüft). Alle neun `type`-Strings entsprechen exakt `build_condition` (triggers.py:239–294).

| `type` | Pflichtfelder | Optional | Bedeutung |
|---|---|---|---|
| `always` | — | — | Immer wahr (Default bei leerer Liste). |
| `never` | — | — | Nie wahr (deaktiviert). |
| `elapsed_time` | `seconds` | `comparator` | N Sekunden seit Spielstart. |
| `countdown_timer` | `seconds` | `comparator` | Countdown-Timer-Vergleich. |
| `bring` | `player`,`amount`,`unit`,`location` | `comparator` | N Einheiten eines Typs **an Location**. |
| `command` | `player`,`amount`,`unit` | `comparator` | N Einheiten gesamt (ganze Karte). |
| `kill` | `player`,`amount`,`unit` | `comparator` | N getötete Einheiten. |
| `deaths` | `player`,`amount`,`unit` | `comparator` | N Death-Count eines Unit-Typs. |
| `accumulate` | `player`,`amount`,`resource` | `comparator` | N Ressource (`ORE`/`GAS`/`ORE_AND_GAS`; triggers.py:154–156). |
| `opponents` | `player`,`amount` | `comparator` | N verbleibende Gegner. |

### A.4 Unterstützte Trigger-ACTIONS (exakte `type`-Strings)

`amount` Default `1` (`0` = „Alle" bei Unit-Aktionen; triggers.py:184–186). `modifier` Default `SET_TO` (`SET_TO`/`ADD`/`SUBTRACT`; triggers.py:195–197). Alle `type`-Strings entsprechen exakt `build_action` (triggers.py:305–393).

| `type` | Pflichtfelder | Optional | Bedeutung |
|---|---|---|---|
| `display_text` | `text` | — | Display Text Message. |
| `set_mission_objectives` | `text` | — | Set Mission Objectives (In-Game-Ziele). |
| `play_wav` | `wav_path` | `duration_ms` | Play WAV (`wav_path` = Return von `sc_embed_wav`). |
| `create_unit` | `player`,`unit`,`location` | `amount` | Create Unit. |
| `kill_unit_at_location` | `player`,`unit`,`location` | `amount` | Kill Unit at Location (mit Death-Count). |
| `remove_unit_at_location` | `player`,`unit`,`location` | `amount` | Remove Unit (lautlos). |
| `move_unit` | `player`,`unit`,`location`,`destination` | `amount` | Move Unit (Quelle→Ziel). |
| `give_units` | `player`,`target_player`,`unit`,`location` | `amount` | Give Units to Player. |
| `set_resources` | `player`,`amount`,`resource` | `modifier` | Set Resources. |
| `set_deaths` | `player`,`unit`,`amount` | `modifier` | Set Death Counts (Integer-Variable; Pflichtfelder `player`/`unit`/`amount`, triggers.py:358–364). |
| `set_countdown_timer` | `seconds` | `modifier` | Set Countdown Timer. |
| `pause_timer` / `unpause_timer` | — | — | Timer pausieren/fortsetzen. |
| `run_ai_script` | `ai_script` | — | Run AI Script (ganze Karte). |
| `run_ai_script_at_location` | `ai_script`,`location` | — | Run AI Script at Location (Wellen/Angriffe). |
| `center_view` | `location` | — | Center View (Kamera). |
| `minimap_ping` | `location` | — | Minimap Ping. |
| `set_alliance_status` | `player`,`alliance_status` | — | Set Alliance Status. Werte `ENEMY`/`ALLY`/`ALLIED_VICTORY` stammen aus dem RichChk-Enum `AllianceStatus` (importiert, enums.py:20) und der Docstring (triggers.py:49, 207) — also eine dokumentierte, nicht direkt aus diesen Dateien enumerierbare Angabe. |
| `victory` / `defeat` | — | — | Mission gewonnen/verloren. |

**`ai_script`:** entweder bekannter Name (z. B. `JUNKYARD_DOG`) oder exakt 4-stelliger Rohcode (z. B. `TMCx`). Sonst `ValueError` (triggers.py:220–233).

**Wert-Parsing (`enums.resolve`):** alle `player`/`unit`/`comparator`/`modifier`/`resource`/`alliance_status` akzeptieren Identifier (`TERRAN_MARINE`), Display-Name (`Terran Marine`) oder Numeric-ID (`0`) — case-insensitiv, getrimmt, **exakt** (kein Fuzzy). Der Index mappt Identifier, Display-Name und `str(member.id)` (enums.py:38–40). `player` umfasst u. a. `PLAYER_1..8`, `ALL_PLAYERS`, `FORCE_1..4`, `FOES`, `CURRENT_PLAYER`.

### A.5 WAV-Embedding (zweiphasig)

1. **`sc_embed_wav` (Registrierung):** In-MPQ-Pfad fest = `staredit\wav\<basename>`; registriert String in WAV-Sektion und queued `(disk_path, in_mpq)` in `pending_wavs` (Dedup nach `in_mpq` via `if not any(...)` → gleicher Basename kollidiert, erster Disk-File gewinnt; workspace.py:167–172). **Keine Existenzprüfung der Bytes in `embed_wav` selbst** — die Existenzprüfung liegt im Tool (`os.path.exists`, server.py:408).
2. **`sc_save_map` (physisch):** kopiert `pending_wavs` per StormLib in die Ausgabe-MPQ und `compact_archive` (workspace.py:192–209). Bis dahin existieren keine Audiobytes, nur der String-Tabelleneintrag.

### A.6 Location-Geometrie

- Die **Arithmetik** verwendet `center_x/y`, `width/height` **roh** als Koordinaten (workspace.py:108–113); es gibt **keine px-pro-Tile-Konstante in der Rechenlogik**. **Die Tool-Doku dokumentiert die Konvention aber explizit:** `sc_create_location` beschreibt „Koordinaten in Pixeln (32 px = 1 Kachel)" und die Parameter sind als „in Pixeln" dokumentiert (server.py:173–174). Der Code ist also **nicht** stumm zur 32-px-Konvention; nur die Geometrie-Rechnung klammert nicht an ein Raster. Tool-Defaults `width=height=96`.
- `half_w = max(1, width//2)`, `half_h = max(1, height//2)`; `left_x1/top_y1 = max(0, center−half)` (auf ≥0 geklammert), `right_x2/bottom_y2 = center+half` (**nicht** nach oben geklammert → kann Kartenrand überschreiten). Ungerade Größen schrumpfen durch Integer-Division.
- **Location-Namen: exakt, case-sensitiv** (kein toleranter Resolver, anders als Enums — `resolve_location` nutzt schlichte Dict-Membership `if name in self.locations`, workspace.py:87). Wirft bei Fehlschlag mit Liste verfügbarer Namen. Trigger, die Locations referenzieren, brauchen diese **vorher**.

### A.7 Verifizierte Ende-zu-Ende-Pipeline (selftest)

`sc_list_maps → sc_create_location → sc_add_trigger (display_text + create_unit, always) → sc_save_map (.scx) → unabhängiges Reload via RichChk` bestätigt, dass Location „Basis" und beide Action-Typen den MPQ-Roundtrip überleben. Das ist der bewiesene Kernpfad. *(Die selftest-Beschreibung ist hier als Domänen-/Beispielpfad referenziert; `selftest.py` zählt nicht zu den vier autoritativen Quelldateien.)*

### A.8 Bemerkenswert / planungsrelevant

- `preserve=True` maskiert den „mind. eine Aktion"-Check (PreserveTrigger zählt; server.py:327–330) → leerer-Aktions-Trigger mit `preserve=True` wird erstellt, ist aber nutzlos.
- 8-Player-Cap in `sc_describe_map` ist hart (`range(8)`, server.py:86); Force-Ops nur FORCE_1..4.
- Workspace-Cache nur nach Basename (workspace.py:225) → zwei gleichnamige Dateien in verschiedenen Verzeichnissen aliasen.
- `sc_save_map` setzt Edits/`pending_wavs` **nicht** zurück (workspace.py:176–210); erneutes Speichern wiederholt das WAV-Embed.
- **Switch-Infrastruktur teilweise vorhanden, aber nicht erreichbar:** Das Enum `SwitchState` und der Resolver `resolve_switch_state` existieren in `enums.py` (Zeilen 23, 94–95). Es ist jedoch **keine** Switch-Condition und **keine** Switch-Action in `build_condition`/`build_action` verdrahtet — Switches sind daher über `sc_add_trigger` **nicht ansprechbar** (siehe C). Korrekt formuliert: das Switch-Enum + Resolver sind im Codebestand vorhanden, nur das Trigger-Wiring fehlt.

---

## B) Was eine vollständige SC:BW-Kampagne braucht

### B.1 Kampagnen-Ebene (campaign-level)

- **Arc-Struktur.** Bewährtes Blizzard-Template: Episode = **7–12 Missionen** (Standalone), Trilogie ≈ **3×10**. Eine Episode = ein Akt mit eigenem Protagonisten, die Missionen verketten zur Saga. Brood War macht Missionen bewusst **strategischer/weniger linear** als Vanilla.
- **Schwierigkeitskurve & Story-Beats.** Klassischer Rhythmus: (1) Tutorial/Helden-only ohne Ökonomie → (2–3) sanfter Base-Build, je 1 Unit-Typ → (Mitte) „Twist"-Mission mit Spezialregeln → (7–9) Eskalation (mehrere Basen, Ally-AI, Timer, defend-then-counter) → (Finale) Set-Piece. Höhere Schwierigkeit fügt **Verhalten** hinzu (mehr Wellen, engere Timer, aggressivere AI), nicht nur HP.
- **Story-Vermittlung.** Tragende Handlung gehört in **gescriptete Szenen** (Briefing/Debrief/Cutscene). In-Mission-Zeilen tragen Flavour + Zielhinweise, nicht den Kernplot.
- **Mission-Verkettung.** `Set Next Scenario` kettet Karten (Kampagnenfortschritt).
- **Globale Konsistenz:** Player/Force-Setup, Rassen-Zuordnung, Ressourcen-Startwerte, Allianzen, Namen/Texte, Audio-Budget über alle Missionen.

### B.2 Missions-Ebene (per-mission)

- **Konzept & Rolle im Arc** (welcher Beat, ein neues Konzept).
- **Objectives:** ein Pflichtziel (treibt `Victory`), explizite `Defeat`-Bedingungen, 0–2 optionale Ziele mit Belohnung; Just-in-time enthüllt.
- **Objective-Surfacing über drei Kanäle:** (1) Briefing-Objective-Box (MBRF), (2) In-Game-Liste via **Set Mission Objectives**, (3) On-Screen via **Display Text** + **Transmission** + **Minimap Ping**/**Center View**.
- **Trigger-Systeme:** Win/Lose-Trigger, Gegner-AI (`Run AI Script (At Location)`), Wellen (`Create Unit`+Timer+Preserve), Helden (`Create Unit With Properties`), **Hyper Triggers** für feine Taktung, **Switches/Death-Counter** als State/Variablen, benannte Locations.
- **Story-Präsentation:** Pre-Mission-**Briefing** (Show Portrait → Speaking Portrait/Transmission → Play WAV → Text → **Wait**), In-Mission-**Transmission** (Talking Portrait + WAV + Text + Center), Cutscenes (Center View + Create/Remove + Transmission + Wait), Debrief-Hook.
- **Polish & Test:** Win- und jeden Lose-Pfad testen; Timing prüfen (keine Wait-Blocks, kein 2-Sekunden-Stottern); günstige Conditions zuerst.

### B.3 Mission-Archetypen (Win/Lose + Trigger-Bedarf)

| # | Archetyp | Win | Lose | Trigger-Bedarf |
|---|---|---|---|---|
| 1 | Destroy-all (Base-Build) | alle Gegner weg | keine Gebäude | `opponents==0` / `command/deaths(enemy)==0` → `victory`; Default „no buildings = defeat" |
| 2 | Defend / Survive-timed | Timer abgelaufen | Schlüsselobjekt zerstört | `set_countdown_timer`; Wellen `create_unit`+`run_ai_script_at_location` (always+preserve); `deaths(protected)≥1`→`defeat` |
| 3 | Escort | VIP an Exit (`bring`) | VIP tot | `bring(VIP,exit)`→`victory`; `deaths(VIP)≥1`→`defeat` |
| 4 | Hero-only / RPG | Ziel erreicht/Target tot | Held tot | kein Base-Build; Create-with-Properties (HP/Invinc); `bring`/`kill`; viel Transmission |
| 5 | Hunt / Find | Target gefunden/getötet | optional Timer/Heldentod | `bring(any,secret)`; `minimap_ping`+`center_view`; Switch „found" |
| 6 | Gather-resources | `accumulate≥X` | Base verloren/Timer | `accumulate`; optional Harass |
| 7 | Rescue / Hold | Allies befreit / Location T s gehalten | Allies sterben | `bring`→`give_units`; Command-the-Most-at-Location über Zeit |
| 8 | Assassination | `deaths(target)≥1` | Armee weg | `deaths`/`kill` auf eindeutiges Target |
| 9 | Puzzle / Spezialregeln | Sequenz fertig | Fehlaktion | Switch-State-Machine; `bring`/`deaths`-Gates |
| 10 | Defend-then-counter (Finale) | Phase 1 überleben → Destroy-all | Base in einer Phase weg | Phasen-Flag (Switch/Timer); AI defensiv→passiv flippen |

---

## C) Gap-Analyse: Kampagnen-Bedarf ↔ Tool-Fähigkeiten

Legende: ✅ direkt unterstützt · 🟉 (Workaround) · ❌ nicht möglich mit den `sc_`-Tools.

| Bedarf (SC:BW-Domäne) | Status | Wie / Workaround / unmöglich |
|---|---|---|
| Karten auflisten/inspizieren | ✅ | `sc_list_maps`, `sc_describe_map`, `sc_list_locations`, `sc_list_triggers`. |
| Locations anlegen/umbenennen | ✅ | `sc_create_location`/`sc_rename_location`. **Achtung:** Geometrie rechnet roh (kein Raster-Clamp), die Tool-Doku nennt aber die Konvention 32 px = 1 Kachel; Namen case-sensitiv & exakt. |
| Player-Typ/Rasse/Force/Force-Namen | ✅ | `sc_set_player_setup` (OWNR/SIDE/FORC). Nur FORCE_1..4; `player`-Key Pflicht. |
| Allianzen setzen | ✅ | Action `set_alliance_status` (`ENEMY`/`ALLY`/`ALLIED_VICTORY`). |
| Ressourcen-Start setzen | ✅ | Action `set_resources` (`SET_TO`/`ADD`/`SUBTRACT`). |
| Win/Lose | ✅ | `victory`/`defeat` + Conditions `opponents`/`command`/`deaths`/`bring`/`accumulate`/`elapsed_time`/`countdown_timer`. |
| In-Game-Ziele | ✅ | Action `set_mission_objectives`. |
| On-Screen-Text | ✅ | Action `display_text`. |
| Einheiten erstellen/töten/entfernen/bewegen/geben | ✅ | `create_unit`,`kill_unit_at_location`,`remove_unit_at_location`,`move_unit`,`give_units`. |
| Wellen / Reinforcements | ✅ | `create_unit` + Timer-Condition + `preserve=True`; Aggression via `run_ai_script_at_location`. |
| Gegner-/Ally-AI | ✅ | `run_ai_script`, `run_ai_script_at_location` (Name oder 4-Char-Code). |
| Timer-Logik | ✅ | `set_countdown_timer`/`pause_timer`/`unpause_timer`/`countdown_timer`/`elapsed_time`. |
| Kamera / Minimap | ✅ | `center_view`, `minimap_ping`. |
| WAV einbetten + abspielen | ✅ | `sc_embed_wav` → `wav_path` → Action `play_wav` (+`duration_ms`); WAV muss vorher in `MAPS_DIR` liegen. Format-Pflege (PCM 16-bit mono 11025 Hz, keine Leerzeichen) liegt beim Autor — Tool prüft nur Existenz. |
| **In-Game-Transmission (Talking Portrait + WAV + Text + Center, getimt)** | 🟉 **Workaround** | **Keine native `transmission`-Action.** Komponieren aus `play_wav` + `display_text` + `center_view` (+`minimap_ping`) — exakt dieser Workaround ist auch in der Docstring dokumentiert (triggers.py:53–56). **Ohne animiertes Portrait und ohne echte synchronisierte Halte-Dauer**: `display_text`/`play_wav` feuern sofort; Synchronisation/„Hold" ist nicht erzwingbar (kein `wait`-Primitiv exponiert). `duration_ms` an `play_wav` steuert nur die WAV-Länge. |
| **Talking Portrait (animiertes Gesicht)** | ❌ | Kein Action-Typ vorhanden. Nicht reproduzierbar mit den `sc_`-Tools. |
| **Pre-Mission-Briefing (MBRF-Sektion)** | ❌ | Tools bearbeiten nur MRGN (Locations), OWNR/SIDE/FORC (Player), TRIG (Trigger), WAV, STR (Force-Namen via RichString) — **keine MBRF-API**. Briefing-Room (Show Portrait/Speaking Portrait/Wait/Objectives-Box) **nicht erstellbar**. Notbehelf: In-Mission-„Intro" zu Spielbeginn via `always`+`display_text`/`play_wav`/`center_view` — kein echter Briefing-Screen. |
| **Switches (256 benannte Booleans, Set/Clear/Toggle/Randomize)** | ❌ | Weder Condition `switch` noch Action `set_switch` in `build_condition`/`build_action` verdrahtet → über `sc_add_trigger` **nicht ansprechbar**, kein Sequencing/OR-Emulation/Randomize über Switches. *(Hinweis zur Genauigkeit: Das Enum `SwitchState` + der Resolver `resolve_switch_state` existieren bereits in `enums.py`:23,94–95 — die Switch-Infrastruktur ist also nicht vollständig abwesend, es fehlt nur das Trigger-Wiring. Praktisch bleibt Switch-Funktionalität dennoch unerreichbar.)* |
| State-Machine / Phasen-Flags / Zähler | 🟉 **Workaround** | Über **Death-Counter** emulierbar: Condition `deaths` (lesen, triggers.py:275–281) + Action `set_deaths` (`SET_TO`/`ADD`/`SUBTRACT`, triggers.py:358–364). Damit Phasen-Flags/Zähler/Timer. Erfordert „Marker"-Unit-Disziplin; kein `switch`-Komfort. |
| **Hyper Triggers (feine Taktung ~12 Hz)** | 🟉 **Workaround/eingeschränkt** | Kein `wait`-Action und kein dedizierter Hyper-Trigger-Helper. Klassische 63×Wait(0)-Konstruktion **nicht baubar**. Engine läuft sonst ~alle 2 s. „Complex Hyper" über Death-Counter-Bedingungen theoretisch nachbaubar, aber umständlich; **flüssige Cutscene-Taktung praktisch nicht erreichbar**. |
| `Wait`-Action (Dramaturgie-Pausen, Sync) | ❌ | Nicht exponiert. Timing nur grob über `elapsed_time`/`countdown_timer`/Death-Counter. |
| **Set Next Scenario (Missionsverkettung)** | ❌ | Kein Action-Typ. Kampagnen-Verkettung **nicht innerhalb der Karte** setzbar; muss extern/manuell gelöst werden. |
| Create Unit **With Properties** (HP/Invinc/Energy/Cloak) | ❌ | Nur schlichtes `create_unit` (Anzahl/Typ/Location, triggers.py:314–320). Helden-Properties nicht setzbar. Teil-Workaround: HP via separate Modify-Action — **auch nicht vorhanden** (kein `modify_unit_hp`). |
| Modify Unit HP/Energy/Shields/Hangar | ❌ | Keine entsprechende Action. |
| Order / Move Location / Set Doodad State / Set Invincibility | ❌ | Nicht exponiert. (Bewegung nur via `move_unit` Teleport.) |
| Leaderboard, Score, Highest/Most/Least-Familie, Kill/Command-the-Most | ❌ | Nicht in den unterstützten Conditions/Actions. |
| Mute/Unmute Unit Speech | ❌ | Nicht vorhanden (Default-Unit-Sounds nicht stummschaltbar). |
| Mehrere Trigger atomar / Reihenfolge garantieren | 🟉 | `sc_add_trigger` fügt je 1 Trigger **ans Ende** an → Reihenfolge = Einfügereihenfolge; bewusst sequenzieren. |
| Terrain / Doodads / Einheiten-Vorplatzierung | ❌ | **Außerhalb des Scopes** — Karten müssen Terrain/Startobjekte bereits enthalten. |

**Kernbotschaft der Gap-Analyse:** Logik-, Einheiten-, Ressourcen-, AI-, Timer-, Sound- und Kamera-Bausteine sind solide abgedeckt. **Vier echte Lücken** prägen das Template-Design: (1) **kein MBRF-Briefing**, (2) **keine native Transmission / kein Talking Portrait**, (3) **keine erreichbaren Switches & keine Hyper/Wait-Taktung** (State nur per Death-Counter, Timing nur grob; Switch-Enum/Resolver existieren zwar in `enums.py`, sind aber nicht an Trigger gebunden), (4) **kein Set Next Scenario / keine Create-with-Properties / Modify-Unit**. Für all diese existieren entweder dokumentierte Workarounds (Transmission-Komposit, Death-Counter-State) oder die Funktion ist mit den `sc_`-Tools **nicht** umsetzbar.

---

## D) Empfohlene Vorlagen-Struktur

Konkrete, tool-verknüpfte Vorlage. Jeder Schritt nennt das exakte `sc_`-Tool und Kern-Parameter. Designprinzip: **alle Edits sammeln, einmal speichern** (Filename = Session). Reihenfolge respektiert Abhängigkeiten (Locations & WAVs **vor** Triggern, die sie referenzieren).

### D.1 Kampagnen-Header (einmal pro Kampagne festlegen)

```
Kampagne: <Titel>
Episode/Akt: <Name>  ·  Geplante Missionen: 7–12 (Standalone) | 3×10 (Trilogie)
Protagonist/Fraktion: <…>  ·  Rasse: TERRAN|ZERG|PROTOSS
Arc-Beats (pro Mission ein Eintrag):
  M1 Tutorial/Helden-only · M2–3 Base-Build · Mitte Twist · 7–9 Eskalation · Finale Set-Piece
Globale Konventionen:
  - Basis-Karten in SC_MAPS_DIR (1 Basis kann mehrere Missionen erzeugen)
  - Player/Force-Schema (PLAYER_1..8, FORCE_1..4) konsistent über alle Missionen
  - Ressourcen-Startwerte, Allianz-Defaults
  - Audio: PCM 16-bit mono 11025 Hz, Dateinamen OHNE Leerzeichen, in MAPS_DIR ablegen
  - Naming: Location-Namen case-sensitiv & exakt; einmal festlegen
  - Location-Koordinaten in Pixeln (Tool-Konvention 32 px = 1 Kachel); Rand beachten (right/bottom nicht geklammert)
WORKAROUND-/LÜCKEN-Hinweise (siehe C):
  - Kein MBRF-Briefing  → Intro als In-Mission-Sequenz (always + display_text/play_wav/center_view)
  - Keine Transmission  → play_wav + display_text + center_view (kein Portrait, kein echter Hold)
  - Keine erreichbaren Switches → State/Phasen über deaths/set_deaths (Marker-Unit-Disziplin)
  - Keine Hyper/Wait    → Timing nur grob via elapsed_time/countdown_timer/Death-Counter
  - Kein Set Next Scenario → Missionsverkettung extern lösen
```

### D.2 Wiederholbarer Per-Mission-Block (Checkliste mit exakten Tool-Calls)

> **Konvention:** `<map>` = Basis-Kartendatei (Session-Key). Erst sammeln, am Ende `sc_save_map`. Bei Fehlversuch `sc_reset_map(<map>)`.

**Schritt 0 — Bestandsaufnahme**
- [ ] `sc_describe_map(map=<map>)` — Tileset, Größe, 8 Player, Forces, Locations, Trigger, `pending_wav_embeds` prüfen.
- [ ] `sc_list_locations(map=<map>)` und `sc_list_triggers(map=<map>)` — vorhandenen Stand erfassen.
- [ ] *(Neustart sauber?)* `sc_clear_triggers(map=<map>)` **nur** wenn die Basis-Trigger ersetzt werden sollen (DESTRUCTIVE; nur per `sc_reset_map` rückholbar).

**Schritt 1 — Player- & Force-Setup**
- [ ] `sc_set_player_setup(map=<map>, players=[{"player":"PLAYER_1","type":"HUMAN","race":"TERRAN","force":"FORCE_1"}, {"player":"PLAYER_2","type":"COMPUTER","race":"ZERG","force":"FORCE_2"}, …], force_names=[{"force":"FORCE_1","name":"<Allianz>"}])`
  - jeder Eintrag braucht `player` (Pflicht); nur FORCE_1..4.

**Schritt 2 — Locations (vor Triggern!)**
- [ ] Pro benötigter Stelle: `sc_create_location(map=<map>, name="<eindeutig>", center_x=<px>, center_y=<px>, width=96, height=96)`
  - Koordinaten in Pixeln (Tool-Konvention 32 px/Tile); `right_x2/bottom_y2` werden nicht geklammert → Kartenrand beachten.
- [ ] Umbenennen falls nötig: `sc_rename_location(map=<map>, old_name=…, new_name=…)`.

**Schritt 3 — Audio (vor `play_wav`-Triggern)**
- [ ] WAV-Datei in `MAPS_DIR` ablegen (PCM 16-bit mono 11025 Hz, kein Leerzeichen im Namen).
- [ ] `sc_embed_wav(map=<map>, wav_filename="<funk1.wav>")` → Rückgabe `wav_path` = `staredit\wav\funk1.wav` notieren.

**Schritt 4 — Mission-Init-Trigger (einmalig zu Spielbeginn)**
- [ ] `sc_add_trigger(map=<map>, players=["ALL_PLAYERS"], conditions=[{"type":"always"}], actions=[`
  `{"type":"set_mission_objectives","text":"<Pflichtziel>"},`
  `{"type":"set_resources","player":"PLAYER_1","resource":"ORE_AND_GAS","amount":<n>,"modifier":"SET_TO"},`
  `{"type":"set_alliance_status","player":"FORCE_2","alliance_status":"ENEMY"},`
  `{"type":"run_ai_script","ai_script":"<SCRIPT_ODER_4CHAR>"},`
  `{"type":"set_countdown_timer","seconds":<n>,"modifier":"SET_TO"},`
  `{"type":"create_unit","player":"PLAYER_1","unit":"TERRAN_MARINE","location":"<Basis>","amount":4},`
  `{"type":"center_view","location":"<Basis>"}], preserve=False)`
  - **`preserve=False`** für einmalige Init (sonst feuert er erneut).

**Schritt 5 — Intro-„Briefing"-Ersatz (Workaround, da kein MBRF)**
- [ ] `sc_add_trigger(map=<map>, players=["PLAYER_1"], conditions=[{"type":"always"}], actions=[`
  `{"type":"center_view","location":"<Szene>"},`
  `{"type":"play_wav","wav_path":"staredit\\wav\\funk1.wav","duration_ms":<ms>},`
  `{"type":"display_text","text":"<Intro-Zeile>"},`
  `{"type":"minimap_ping","location":"<Ziel>"}], preserve=False)`
  - Kein Portrait, keine echte Sync/Hold-Garantie (siehe C). Mehrere kurze Zeilen statt langer Reden.

**Schritt 6 — Objective-/Wellen-/Phasen-Trigger (archetyp-spezifisch)**
- [ ] **Wellen:** `sc_add_trigger(players=["PLAYER_2"], conditions=[{"type":"elapsed_time","seconds":<t>,"comparator":"AT_LEAST"}], actions=[{"type":"create_unit","player":"PLAYER_2","unit":"<Zerg>","location":"<Spawn>","amount":6},{"type":"run_ai_script_at_location","ai_script":"<ATTACK_SCRIPT>","location":"<Ziel>"}], preserve=True)`
- [ ] **Phasen-Flag via Death-Counter** (Switch-Ersatz): zum Setzen `actions=[{"type":"set_deaths","player":"PLAYER_1","unit":"<MARKER_UNIT>","amount":1,"modifier":"SET_TO"}]`; zum Lesen `conditions=[{"type":"deaths","player":"PLAYER_1","unit":"<MARKER_UNIT>","amount":1,"comparator":"AT_LEAST"}]`.
- [ ] **Optionale Ziele:** eigener Trigger, der bei Erfüllung `give_units`/`set_resources` belohnt und `set_mission_objectives` aktualisiert.

**Schritt 7 — Win/Lose (immer explizit, je `preserve=True`)**
- [ ] **Win:** `sc_add_trigger(players=["PLAYER_1"], conditions=[{"type":"opponents","player":"PLAYER_1","amount":0,"comparator":"AT_MOST"}], actions=[{"type":"display_text","text":"Mission erfüllt"},{"type":"victory"}], preserve=True)`
  - Archetyp-Varianten: `bring(VIP,exit)` (Escort), `deaths(target)≥1` (Assassination), `accumulate≥X` (Gather), `countdown_timer≤0`/`elapsed_time` (Survive).
- [ ] **Lose:** `sc_add_trigger(players=["PLAYER_1"], conditions=[{"type":"deaths","player":"PLAYER_1","unit":"<VIP_ODER_KEY_STRUCTURE>","amount":1,"comparator":"AT_LEAST"}], actions=[{"type":"defeat"}], preserve=True)`
  - Plus ggf. Timer-Lose / „no buildings"-Lose.

**Schritt 8 — Kontrolle vor dem Speichern**
- [ ] `sc_list_triggers(map=<map>)` — Reihenfolge, Player, Conditions/Actions gegen den Plan prüfen.
- [ ] `sc_describe_map(map=<map>)` — `pending_wav_embeds` enthält alle erwarteten WAVs? Locations vollständig?
- [ ] Falsch eingefügt? `sc_remove_trigger(map=<map>, index=<i>)` (0-basiert).

**Schritt 9 — Persistieren (eine neue Missionsdatei)**
- [ ] `sc_save_map(map=<map>, output_name="mission<NN>.scx", overwrite=False)`
  - Rückgabe prüfen: `embedded_wavs`, `triggers`, `locations`. Bei `FileExistsError` neuen Namen oder `overwrite=True`.
  - **Hinweis:** Endung `.scx` wird nur ergänzt, wenn der Name nicht schon auf `.scx`/`.scm` endet (ein `.scm` bleibt erhalten). Erneutes `sc_save_map` bettet `pending_wavs` erneut ein und nutzt denselben In-Memory-Stand (kein Reset durch Save).

### D.3 Per-Mission-Designcheck (vor Schritt 9 abhaken)

- [ ] Genau **ein** Pflichtziel → treibt `victory`; Text in `set_mission_objectives`.
- [ ] **Alle Lose-Pfade** verdrahtet (Held/VIP-Tod, Timer, Key-Structure).
- [ ] Gegner-AI gesetzt (`run_ai_script`/`_at_location`), Aggression passend zum Beat.
- [ ] Wellen-Trigger `preserve=True`; Init-Trigger `preserve=False`.
- [ ] Locations für jedes `create_unit`/`move_unit`/`bring`/`center_view` existieren und exakt benannt.
- [ ] WAVs vorab in `MAPS_DIR`, `sc_embed_wav` aufgerufen, `wav_path` in `play_wav` korrekt (`staredit\wav\…`).
- [ ] Bewusst: **kein** echtes Briefing/Transmission/Portrait, **keine erreichbaren** Switches, **keine** Hyper-Taktung — Workarounds dokumentiert eingesetzt.

### D.4 Kampagnen-Abschluss-Checkliste (closeout)

- [ ] Alle Missionen als eigene `.scx`/`.scm` in `MAPS_DIR` gespeichert; Namensschema `mission01..NN` konsistent.
- [ ] Player/Force/Rassen-Schema über alle Missionen identisch (per `sc_describe_map` stichprobenartig gegengeprüft).
- [ ] Audio-Budget gesamt geprüft (WAV-Anzahl/Größe je Karte; PCM-Spec eingehalten).
- [ ] Jede Mission: Win- **und** jeder Lose-Pfad manuell im Spiel getestet (Timing grob, da keine Hyper-Trigger).
- [ ] **Missionsverkettung extern gelöst** (kein `Set Next Scenario` über die Tools) — Reihenfolge/Übergänge dokumentiert.
- [ ] Briefing-Ersatz (In-Mission-Intro) in jeder Mission vorhanden, da MBRF nicht editierbar.
- [ ] Backup der Basis-Karten unverändert (Save erzeugt stets neue Dateien; Basis bleibt Template).
- [ ] Bei Server-Neustart: In-Memory-Workspaces sind weg → finalisierte `.scx` sind die einzige Persistenz.

---

### Quellenbasis
- **Code (autoritativ für A & Fähigkeitsaussagen):** `G:\Claude\Star-Edit\starcraft_mcp\server.py`, `triggers.py`, `enums.py`, `workspace.py`. *(Ergänzend, nicht als autoritativ geprüft: `__init__.py`, `selftest.py`, `requirements.txt`, `Dockerfile` — Aussagen zu Docker-Transport-Default, Python-Version und Dependency-Pins sind aus diesen vier Kerndateien nicht verifizierbar und entsprechend gekennzeichnet.)*
- **Domäne (B/C-Kontext):** StarEdit Network Wiki (Triggers, List of Trigger Conditions/Actions, Mission Briefings, Hyper Triggers, Wait blocks, Death Counters, Wav Files, Scenario.chk), Campaign Creations Tutorials, StarCraft Fandom/Wikipedia (Episodenstruktur), StrategyWiki Walkthrough, RPGClassics Atrium Campaign Editor, PC Gamer (Blizzard-Storytelling).