# KI-Schemata

> Ein Schema ist eine komplette KI. In Farsight mit einem Klick wechseln – auch in einer laufenden Partie übernimmt sofort die neue KI. Als zip exportieren und teilen, fremde Schemata importieren und testen; die Ergebnisse jedes Schemas werden automatisch erfasst.

Quelle: https://war3ai.com/de/docs/schemes/

Ein **Schema** = eine komplette KI: ein Ordner + ein Manifest `scheme.json` + Code. Jede Spielinstanz verwendet ein Schema; in Farsight wechselst du mit einem Klick, und **selbst in einer laufenden Partie übernimmt sofort das neue Schema**.

Von anderen geteilte Schemata liegen nach dem Import **in einem eigenen Bereich** und beeinflussen deine eigenen nicht; willst du eins ändern, nimm „In Meine kopieren“.

```text
schemes/
  mine/<id>/          Meine: selbst geschrieben oder von einem anderen Schema kopiert und angepasst (frei änderbar, wirkt ab der nächsten Partie)
  installed/<id>/     Installiert: hier werden zips entpackt, die andere geteilt haben (vor dem ersten Start muss Vertrauen bestätigt werden)
brains/xwar3/         Eingebaut: Referenz-Brain (vollständige KI)
brains/examples/      Eingebaut: vier Lehrbeispiele hello / rush / macro / micro, das Begleiter-Beispiel buddy und zwei Gameplay-Mods (Helden-Roguelike, Endlose Verteidigung)
```

Ein Schema muss keine KI sein, die für dich spielt: Ein Schema mit `kind: mod` ist ein Satz **Spielregeln** – du spielst selbst, es stellt die Aufgaben; siehe [Gameplay-Mods](https://war3ai.com/de/docs/mods/).

## In Farsight verwenden

Seite „KI-Schemata“ (Seitenleiste „System → KI-Schemata“):

| Aktion | Was passiert |
|---|---|
| Schema importieren (zip) | wird in `installed/` installiert; ist dieselbe id schon installiert, wirst du gefragt, ob sie ersetzt werden soll (danach muss Vertrauen neu bestätigt werden) |
| Für Instanz verwenden … | Instanz wählen + „Sofort wirksam“ (aktuelle KI stoppen, das neue Schema übernimmt diese Partie) oder „Ab dem nächsten Teststart“ |
| In Meine kopieren | legt eine Kopie in `mine/` an, Autor „ich“, Version 0.1.0, und merkt sich, von welcher Version welches Schemas kopiert wurde |
| Als zip exportieren | packt es als `<id>-<Version>.zip` – an andere schicken heißt teilen |
| Ordner öffnen | öffnet das Schemaverzeichnis im Explorer, um den Code direkt zu bearbeiten |
| Vertrauen | muss bei fremden Schemata vor dem ersten Start geklickt werden (siehe „Vertrauen und Sicherheit“ unten) |
| Letzte Ergebnisse | Sieg/Niederlage, Dauer und Endgrund jeder Partie dieses Schemas |
| Löschen | nur für „Meine“ und „Installiert“; Schemata, die gerade von einer Instanz verwendet werden, lassen sich nicht löschen |

Auf der Instanzkachel gibt es außerdem eine Zeile „KI-Schema“: Schema im Dropdown wählen → „Wechseln (sofort wirksam)“. Läuft die Instanz nicht, heißt der Button „Festlegen“, und beim nächsten „Test starten“ wird die KI mit diesem Schema gestartet.

## Das Manifest scheme.json

```json
{
  "format": 1,
  "id": "fast-rush",
  "name": "Drei-Minuten-Rush",
  "version": "1.2.0",
  "author": "Jemand",
  "description": "Ein Satz dazu, welche Strategie diese KI spielt",
  "entry": "rush_bot.py",
  "class": "RushBot",
  "fair": true,
  "hz": 5,
  "races": ["human", "orc"],
  "license": "MIT"
}
```

| Feld | Pflicht | Beschreibung |
|---|---|---|
| `id` | ✔ | Kleinbuchstaben, Ziffern, `-`, `_`, 2–41 Zeichen |
| `entry` | ✔ | eine `.py`-Datei im Schemaverzeichnis (keine absoluten Pfade, kein `..`) |
| `kind` | | Standard `bot` (Unterklasse von `openwar3.Bot`, spielt für dich); `mod` = [Gameplay-Mod](https://war3ai.com/de/docs/mods/) (Unterklasse von `openwar3.Mod`, läuft nie im Fair-Modus und entscheidet Sieg und Niederlage nicht nach Melee-Regeln) |
| `class` | | Name der Bot- (oder Mod-)Unterklasse in der Einstiegsdatei; ohne Angabe wird die letzte `openwar3.Bot`-Unterklasse der Einstiegsdatei genommen |
| `fair` | | Standard `true`: sieht nur, was in Sicht ist – dieselbe Regel wie in der Arena. `false` = ganze Karte sichtbar, und nur dann ist der [JASS-Kanal](https://war3ai.com/de/docs/jass/) nutzbar (Begleiter brauchen ihn) |
| `judge` | | Standard `true`: Sieg und Niederlage nach Melee-Regeln. RPG- und Begleiter-Schemata setzen `false` |
| `hz` | | wie oft pro Sekunde `on_tick` aufgerufen wird, Standard 5 |
| `format` | | Version des Manifest-Formats, derzeit 1; ein neueres Format, als das lokale OpenWar3 kennt, wird mit dem Hinweis auf ein Update abgelehnt |
| Sonstige | | `name`, `version`, `author`, `description`, `races`, `license`, `homepage`, `forked_from` dienen nur der Anzeige |

Das Schemaverzeichnis wird dem Python-Modulsuchpfad hinzugefügt, die Einstiegsdatei kann also andere Dateien im selben Verzeichnis per `import` laden. Drittanbieter-Pakete (numpy, torch …) werden nicht automatisch installiert – schreib in `description`, was gebraucht wird.

**Das kleinste Schema besteht aus zwei Dateien**:

```python
# my_bot.py
from openwar3 import Bot

class MyBot(Bot):
    def on_tick(self, g):
        for w in g.idle_workers():
            mine = g.nearest(g.gold_mines(), w)
            if mine:
                g.gather(w, mine)
```

```json
{"id": "my-first", "name": "Meine erste KI", "entry": "my_bot.py"}
```

Leg es unter `schemes/mine/my-first/` ab und lade Farsight neu – schon erscheint es. Noch bequemer: unter „Eingebaut“ ein Beispiel wählen und auf „In Meine kopieren“ klicken.

## Ausführung und Ergebnisse

Schemata werden vom **Schema-Runner** ausgeführt (genau den startet Farsight bei „Test starten / Wechseln“):

```bash
python tools/run_scheme.py --inst 20 --scheme builtin/micro --hours 6
```

- Pro Instanz läuft ein dauerhafter Überwachungsprozess, und **für jede Partie wird ein eigener Kindprozess gestartet**, der das Schema ausführt: Stürzt der Schemacode ab, reißt er den Überwachungsprozess nicht mit; änderst du den Code eines Schemas unter „Meine“, wird ab der nächsten Partie automatisch die neue Version verwendet.
- Am Ende jeder Partie wird eine Ergebniszeile festgehalten: Schema, Version, Autor, Sieg/Niederlage, Grund, Spieldauer, Anzahl der Fehler. Daraus berechnet Farsight die Siegquote.

So wird über Sieg und Niederlage entschieden:

| Situation | Eintrag |
|---|---|
| Alle gegnerischen Gebäude zerstört | Sieg |
| Alle eigenen Gebäude zerstört (auch wenn noch Truppen leben – so wird in Melee-Partien eine Niederlage entschieden) | Niederlage |
| Alle eigenen Einheiten tot | Niederlage |
| In Farsight manuell beendet / gestoppt | offen |
| Beim Wechsel lief die Partie schon länger als 60 Spielsekunden (Übernahme mitten im Spiel) | separat gezählt, **nicht in der Siegquote** |
| Spieluhr bewegt sich lange nicht | offen |

Nach der Entscheidung schließt der Runner den Ergebnisbildschirm, startet die nächste Partie gemäß „Einstellungen fürs nächste Spiel“, und das Schema übernimmt wieder – du kannst es eine ganze Nacht laufen lassen und Ergebnisse sammeln. Eine Pause ist kein Ende: Während der Pause läuft der Bot normal weiter, nur die Spieluhr steht.

## Vertrauen und Sicherheit

**Ein Schema ist Code und läuft mit denselben Rechten wie du selbst** (kann Dateien lesen und schreiben, kann aufs Netz zugreifen). Deshalb:

- Schemata in `installed/` sind standardmäßig **nicht vertrauenswürdig**; Farsight und der Runner verweigern die Ausführung, bis du auf „Vertrauen“ klickst;
- wird ein Schema mit derselben id durch eine neue Installation ersetzt, wird **das Vertrauen zurückgesetzt** (neue Version = neuer Code);
- beim Import wird geprüft: zip höchstens 50 MB und höchstens 2000 Dateien; keine absoluten Pfade und kein `..` (damit nichts außerhalb des Schemaverzeichnisses geschrieben wird); ein ungültiges Manifest oder eine fehlende Einstiegsdatei führt zur sofortigen Ablehnung.

> **Achtung**
>
> Bevor du vertraust: mit „Ordner öffnen“ den Code einmal durchlesen. Nimm Schemata nur von Leuten, denen du vertraust.

## API (für Skripte)

| API | Beschreibung |
|---|---|
| `GET /api/schemes` | Schemaliste + Ergebnisse + das pro Instanz gewählte und gerade laufende Schema |
| `GET /api/schemes/results?ref=` | die letzten 30 Partien eines Schemas |
| `POST /api/schemes/import` | zip importieren |
| `GET /api/schemes/export?ref=` | zip herunterladen |
| `POST /api/schemes/fork` | In Meine kopieren |
| `POST /api/schemes/trust` | Vertrauen |
| `DELETE /api/schemes?ref=` | Löschen (abgelehnt, solange eine Instanz es verwendet) |
| `POST /api/instances/{n}/scheme` | Schema einer Instanz wechseln: diese Partie sofort übernehmen oder ab dem nächsten Teststart |

In Python direkt über die Bibliothek: `from openwar3 import schemes` (`list_schemes`, `install_zip`, `export_zip`, `fork`, `trust`, `stats` …).

## Später: Schema-Website

Die exportierte zip ist die Einheit zum Teilen; die Website muss nur eine Schicht darüberlegen: aus Farsight mit einem Klick hochladen; auf der Website herunterladen – mit genau denselben Prüfungen wie beim „Schema importieren“ und ebenfalls mit Vertrauensbestätigung; optional Ergebnisse melden, die Website fasst die Siegquote pro Version zusammen. Der Button „Auf der Schema-Website teilen“ hat in Farsight schon seinen Platz. Den aktuellen Stand findest du in der [Roadmap](https://war3ai.com/de/roadmap/).