World-of-Warcraft-Addon programmieren: TOC-Datei, Lua und die erste Ausgabe

Ein eigenes Add-on für World of Warcraft beginnt mit wenigen Dateien: einem Ordner, einer TOC-Datei mit Metadaten und einem Lua-Skript. Für eine erste sichtbare Ausgabe genügt eine einzige Zeile Code. Entscheidend ist, dass Ordnername, Dateinamen und die Einträge in der TOC-Datei zusammenpassen.

Dieser Artikel führt Sie von der Ordnerstruktur bis zur ersten Meldung im Spiel und zur ersten Reaktion auf ein Ereignis. Eine vollständige Lua-Einführung ist er nicht. Die Sprachgrundlagen erklärt der Artikel Lua fürs Modding.

Was Sie brauchen

Für den Einstieg genügen eine Installation des Spiels, ein Texteditor und Zugriff auf den Add-on-Ordner. Eine spezielle Entwicklungsumgebung ist nicht nötig: Lua- und TOC-Dateien sind reine Textdateien.

Add-ons liegen im Verzeichnis Interface\AddOns der jeweiligen Spielversion, bei der aktuellen Hauptversion zum Beispiel unter World of Warcraft\_retail_\Interface\AddOns. Der genaue Pfad hängt davon ab, welche Spielversion Sie nutzen und wo das Spiel installiert ist. Ein Add-on im Ordner der falschen Version taucht in der Add-on-Liste nicht auf.

Legen Sie in AddOns einen neuen Ordner an, im Beispiel ErstesAddon. Darin kommen eine TOC-Datei und eine Lua-Datei. Die TOC-Datei muss genauso heißen wie der Ordner:

AddOns/
└── ErstesAddon/
    ├── ErstesAddon.toc
    └── ErstesAddon.lua

Achten Sie auf identische Schreibweise und darauf, dass Ihr Editor nicht unbemerkt eine Endung wie .txt anhängt.

TOC und Lua haben unterschiedliche Aufgaben

Die Lua-Datei enthält den ausführbaren Code: Befehle, die beim Laden laufen, und später Funktionen und Reaktionen auf Ereignisse im Spiel.

Die TOC-Datei ist eine Textdatei mit Metadaten und der Liste der Lua-Dateien, die das Spiel laden soll. Sie verbindet den Ordner mit dem Code. Fehlt sie oder verweist sie auf einen falschen Dateinamen, kann das Spiel das Add-on nicht einlesen.

Die TOC-Datei anlegen

Öffnen Sie ErstesAddon.toc im Editor. Für den Anfang genügen ein paar Metadaten und der Name der Lua-Datei:

## Interface: <Interface-Nummer>
## Title: Erstes Add-on
## Notes: Gibt beim Laden eine Meldung aus
ErstesAddon.lua

Zeilen mit ## sind Metadaten, Zeilen mit einem einfachen # gelten als Kommentar, alle übrigen Zeilen als Dateinamen. Title ist der Name in der Add-on-Liste, Notes der Hinweistext, der dort beim Überfahren mit der Maus erscheint. Die letzte Zeile nennt die Lua-Datei, exakt so geschrieben wie im Ordner.

Die passende Interface-Nummer finden

Die Zeile ## Interface: braucht die Interface-Nummer der installierten Spielversion. Der Platzhalter oben ist kein gültiger Wert und muss ersetzt werden. Die Nummer ändert sich mit Spielupdates, übernehmen Sie deshalb keine aus älteren Beispielen. Am zuverlässigsten fragen Sie sie im Spiel selbst ab, indem Sie in das Chatfenster eingeben:

/dump select(4, GetBuildInfo())

Das Spiel gibt dann die aktuelle Interface-Nummer aus, die Sie in die TOC-Datei übernehmen. Passt die Angabe nicht, kennzeichnet die Add-on-Liste das Add-on als veraltet.

Speichern Sie die Datei als reinen Text unter dem Namen ErstesAddon.toc und kontrollieren Sie im Dateimanager, dass keine ausgeblendete Endung angehängt wurde.

Das erste Lua-Skript

Öffnen Sie ErstesAddon.lua und schreiben Sie diese Zeile hinein:

print("Hallo! Das Add-on wurde geladen.")

print gibt den Text im Chatfenster aus. Damit sehen Sie sofort, dass das Skript beim Laden ausgeführt wurde. Ein eigenes Fenster oder eine Schaltfläche brauchen Sie für diesen ersten Schritt nicht. Gerade weil der Code so kurz ist, lassen sich Probleme mit Ordner, Dateinamen und TOC-Eintrag eindeutig erkennen, bevor weitere Funktionen dazukommen.

Auf ein Ereignis reagieren

Add-ons arbeiten ereignisgesteuert: Ein Skript meldet an, über welche Ereignisse es informiert werden möchte, und das Spiel ruft dann eine Funktion auf. Dafür legen Sie einen unsichtbaren Rahmen an, registrieren ein Ereignis und hinterlegen eine Funktion für das Skript OnEvent:

local frame = CreateFrame("Frame")
frame:RegisterEvent("PLAYER_LOGIN")
frame:SetScript("OnEvent", function(self, event)
    print("Erstes Add-on: " .. event)
end)

Das Ereignis PLAYER_LOGIN tritt beim Einloggen und beim Neuladen der Oberfläche ein. Welche Ereignisse es sonst gibt und welche Daten sie mitliefern, steht in der Dokumentation der Spiel-API. Prüfen Sie jedes Ereignis und jede Funktion dort, bevor Sie sie verwenden, denn die Schnittstelle ändert sich mit Spielversionen.

Laden und die Ausgabe finden

Ein neu angelegtes Add-on erkennt das Spiel erst nach einem Neustart. Starten Sie das Spiel also neu und öffnen Sie in der Charakterauswahl die Add-on-Liste. Dort sollte „Erstes Add-on“ erscheinen. Ist es als veraltet markiert, prüfen Sie zuerst die Interface-Nummer. Eine Option zum Laden veralteter Add-ons ersetzt keine korrekte Angabe.

Aktivieren Sie das Add-on und betreten Sie die Spielwelt. Die Meldung erscheint im Chatfenster. Änderungen am Code laden Sie künftig ohne Neustart mit dem Befehl /reload.

Damit Lua-Fehler sichtbar angezeigt werden, schalten Sie die Fehleranzeige mit /console scriptErrors 1 ein. Bleibt die Meldung aus, gehen Sie die häufigsten Ursachen der Reihe nach durch:

• Add-on fehlt in der Liste: Liegt der Ordner im AddOns-Verzeichnis der richtigen Spielversion, und wurde das Spiel seitdem neu gestartet?
• TOC-Datei wird nicht erkannt: Stimmen Ordner- und Dateiname überein, und hängt keine zusätzliche .txt-Endung an?
• Skript wird nicht geladen: Entspricht der Dateiname in der TOC-Datei genau dem Namen der Lua-Datei?
• Keine Meldung im Chat: Ist das Add-on aktiviert, und haben Sie nach dem Speichern neu geladen?
• Fehlermeldung beim Laden: Lesen Sie den Wortlaut genau. Ein Schreibfehler im Code oder ein falscher Dateiname verhindert die Ausführung.

Ändern Sie immer nur eine Sache und laden Sie danach neu. So sehen Sie, welche Änderung welche Wirkung hatte. Sichern Sie außerdem eine funktionierende Version, bevor Sie neue Funktionen ergänzen.

Häufige Stolperstellen beim Einstieg

Ausgeblendete Dateiendungen sind der Klassiker: Der Editor speichert ErstesAddon.lua.txt, im Fenster steht aber nur ErstesAddon.lua. Kontrollieren Sie den vollständigen Namen im Dateimanager und speichern Sie immer als reinen Text.

Ebenso wichtig ist die Zuordnung. Die TOC-Datei muss im Add-on-Ordner liegen und denselben Namen tragen wie der Ordner, und der Dateieintrag in der TOC muss genau auf die vorhandene Lua-Datei verweisen. Eine einzige Abweichung genügt, und das Skript wird nicht geladen.

Verwechseln Sie eine fehlende Ausgabe außerdem nicht vorschnell mit einem Fehler im Lua-Code. Ist das Add-on deaktiviert, liegt es im falschen Verzeichnis oder wird die TOC-Datei nicht gelesen, kommt der Code gar nicht erst zur Ausführung. Prüfen Sie deshalb zuerst den Weg vom Spielverzeichnis bis zur Lua-Datei.

Halten Sie das erste Add-on so klein, dass Sie jede Zeile verstehen. Zusätzliche Dateien, Fenster oder Ereignisse erschweren die Fehlersuche, solange die Grundstruktur noch nicht sicher funktioniert.

Fazit

Für die erste Ausgabe brauchen Sie nur einen richtig benannten Ordner, eine passende TOC-Datei mit der aktuellen Interface-Nummer und ein kurzes Lua-Skript. Steht diese Grundlage, ergänzen Sie Schritt für Schritt Ereignisse, gespeicherte Einstellungen und eigene Oberflächen und prüfen jede Änderung einzeln. Welche Regeln für Mods und Add-ons allgemein gelten, beschreibt die Übersicht Mods für Spiele programmieren. Wie Erweiterungen ohne Skriptsprache funktionieren, zeigt das Beispiel Minecraft-Datenpaket erstellen.