KI-Schemata

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“.

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.

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

{
  "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 (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 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:

# 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)

{"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“):

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.

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.