Lua-Modding Tutorial

[Tiramisu]

In diesem Thread sollen einige Grundkonzepte und eventuell fortgeschrittenes Wissen zur Lua-Programmierung vorgestellt werden (siehe Inhaltsverzeichnis im 2. Post). Aber fürs Erste werde ich nur einige wenige Themen vorstellen können, weil ich nicht so viel Zeit habe.

Dabei geht es hier nicht nur darum, Lua-Dateien zu modifizieren, sondern auch sofort mithilfe des Firetuners das Spiel zu ändern und dadurch z.B. die Funktionsweisen von Luafunktionen zu testen oder das Spiel relativ einfach zu manipulieren (natürlich nur für ehrenhafte Zwecke und nicht zum Cheaten ).

[Tiramisu]

Inhaltsverzeichnis

1. Was sollte man über Lua wissen?
2. Einführung in den Firetuner

[Tiramisu]

Was sollte man über Lua wissen?

Lua ist eine Skriptsprache, die es einem z.B. ermöglicht, Civ5 zu modifizieren, ohne dass man vorher den ursprünglichen Programmcode ändern muss (der in C++ geschrieben und in Form einer DLL-Datei erstellt wurde).
In diesem Tutorial setze ich grundlegende Kenntnisse dieser Programmiersprache voraus. Anfangs muss man nicht unbedingt alle Details dieser Sprache kennen und es geht meistens um solche grundlegenden Konzepte wie Schleifen, If-Bedingungen etc.
Eine praktische Eigenheit von Lua ist es, dass man die Einheitentypen von Variablen nicht wie z.B. in C++ deklarieren muss. Außerdem gibt es sogenannte "Tables" in Lua, die meistens mit geschweiften Klammern ausgedrückt werden. Das sind sozusagen Tabellen, die Variablen und weitere Tabellen enthalten können. Es kann sich lohnen, sich mit diesem Konzept zur Struturierung von Lua Objekten genauer auszukennen, auch wenn ich es hier nicht genauer erklären werde.
Aber für die einfacheren Dinge, braucht man zunächst keine solchen fortgeschrittenere Kenntnisse (ich kenne mich auch nicht so gut mit Lua aus ).

Im Internet gibt es gute Lua-Tutorials: http://www.lua.org/pil/contents.html
In diesem Tutorial geht es aber nur speziell um die Lua-Programmierung von Civ5.

[Tiramisu]

Einführung in den Firetuner

Installation

Zunächst solltet ihr den SDK von Civ5 installieren (siehe Steam->Bibliothek->Tools), denn der Firetuner ist eines der Modding-Tools des SDKs:




Um den Firetuner dann nutzen zu können, müsst ihr noch die Datei Config.ini in eurem Civ5-Ordner mit einem Editor öffnen und den Wert für "EnableTuner" auf 1 setzen:

EnableTuner = 1 

Firaxis wollte dadurch wohl sicherstellen, dass man nicht so einfach Zugriff auf den Firetuner bekommt, weil das ein mächtiges Tool sein kann.


Firetuner starten und verwenden

Wenn ihr Firetuner ohne Civ5 startet, sollte es so aussehen:



Unten links sieht man dann auch den Status "disconnected", weil der Firetuner gerade nicht mit Civ5 verbunden ist. Damit lässt sich noch nicht viel anfangen. Erst wenn ihr ein Spiel mit Civ5 startet (egal ob im SP oder im MP), sollte sich Firetuner mit diesem Spiel in Verbindung setzen und der Status "connected" anzeigen, sodass eine Menge voreingestellter Tabs (im unteren Bild rot eingerahmt) im Firetuner erscheinen:




Darunter sieht man die Dropdowns "WorldView" sowie "New Control" und weiter unten befinden sich einige voreingestellte Schaltflächen, mit denen man das Spiel manipulieren kann.
Die Schaltflächen lassen sich umprogrammieren, wenn man jeweils darauf rechtsklickt und "Edit" wählt, wobei die Programmiersprache natürlich in Lua geschrieben sein muss.
Um neue Schaltflächen einzufügen, klickt man auf "New Control" und wählt dann einen Typ aus. Wenn man dabei z.B. "Action Control" wählt, erhält man einen Button, der einen Programmcode ausführt, sobald man draufklickt. Es sind aber auch andere Schaltflächen möglich, die spezielle Sachen in einer Tabelle auflisten und dann anwählbar sind oder Schaltflächen, in denen man etwas eingeben kann (z.B. eine Zahl).
Die meisten Schaltflächen sollten eigentlich selbsterklärend sein bzw. sind dazu gedacht, dass man sie als Lernbeispiele verwendet. Daher werde ich auf die meisten davon nicht näher eingehen, sondern am Ende nur ein paar Beispiele zeigen.

Einige Schaltflächen können in manchen Fällen irgendwelche Informationen aus dem Spiel oder Lua-Funktionen verwenden, die man nur in einem dafür geeigneten, sogenannten Lua-Zustand verwenden kann. Z.B. wird das für die folgenden Programmierzeile gebraucht:

local pPlayer = Players[Game.GetActivePlayer()]; 

pPlayer ist hier eine Variable, die den Typ eines Spielers besitzt ("Players" ist in Civ5 eines von vielen Variablentypen) und in diesem Fall als Wert den aktuellen Spieler annimmt. Um den aktuellen Spieler zu erhalten, muss diese Programmzeile aber auf die Funktion "Game.GetActivePlayer()" zurückgreifen können und braucht daher den Lua-Zustand "WorldView".
Ein weiteres Beispiel wäre der Lua-Zustand "CityView", den man braucht, um die Funktion "GetCityByID" verwenden zu können.

Für welche Fälle die Lua-Zustände geeignet sind, weiß ich nicht so genau. Aber normalerweise sind es entweder "WorldView" oder "Ingame". Da muss man wohl herumprobieren oder sich an den voreingestellten Schaltflächen ein Beispiel nehmen. Vielleicht kann ich in Zukunft noch genauere Details dazu herausfinden.
An der Stelle von "WorldView" wie in dem obigen Bild kann also auch ein anderer Zustand stehen.


Neue Tabs erstellen

Wenn man in der Tab-Leiste ganz rechts auf *New Panel* klickt, lässt sich ein neuer Tab erstellen. Dabei erscheint ein Popup, in dem man einige Eintellungen vornehmen muss:



In der ersten Zeile gibt man den Namen des Tabs ein und darunter kann man auswählen, welche Lua-Zustände im Dropdown dieses Tabs auftreten dürfen (es kann aber trotzdem nur ein Lua-Zustand pro Tab gleichzeitig verwendet werden). Man kann diese Einstellungen später auch editieren, indem man auf einer freien Fläche in diesem Tab rechtsklickt.
Die Optionen "On Enter" bzw. "On Exit" bieten einem die Möglichkeit in einem Lua-Programmcode auszudrücken, was der Firetuner machen soll, wenn man diesen Tab anwählt bzw. wenn man diesen Tab wieder verlässt. Das kann man anscheinend dazu verwenden, um z.B. Lua-Variablen beim Verlassen des Tabs wieder zu löschen.


Anwendungsbeispiele

Beispiel 1 (Ressourcen auf der Karte einfügen): Um Ressourcen auf der Karte einzufügen, gibt es zwei Möglichkeiten.
Die erste Möglichkeit ist es, dass man das manuell durch Klicken auf der Karte machen kann, indem man die voreingestellten Schaltflächen im "Map"-Tab nutzt. Dazu wählt man das Häkchen bei "Ressource Plopper Enabled" an (diese Schaltfläche sollte oben mittig im Tab zu finden sein). Bei "Res. Amount" gibt man die Anzahl des Ressourcenvorkommens auf einem Feld ein (standardmäßig ist in diesem Feld 1 eingestellt). Darunter wählt man in der Tabelle "Ressources" den Typ der Ressource aus, die eine strategische oder Luxus-Ressource sein kann.
Danach wechselt man zum Spiel und klickt auf ein Feld. Dann sollte auf diesem Feld die jeweilige Ressource erscheinen (wenn nicht, dann siehe die Problembehandlungen weiter unten). Mit einem Rechtsklick kann man die Ressourcen wieder verschwinden lassen. Das klappt auch bei Einheiten oder Geländemodernisierungen. Man muss dazu nur das entsprechende Häkchen angwählt haben (bei den Einheiten sollte man beachten, dass man auch die gewünschte Zivlisation in eines der Tabellen anwällen sollte).
Wenn man die Maus im Spiel wieder für die normalen Funktionen nutzen will, muss das Häkchen bei jedem Plopper aus sein.

Eine zweite Möglichkeit für unser Beispiel wäre, wenn man die Koordinaten des gewünschten Feldes kennt, auf das die Ressource gesetzt werden soll. (Um die Koordinaten eines Felds zu bestimmen, kann man z.B. die Karte abspeichern, im Worldbuilder laden und das gewünschte Feld anklicken, damit man irgendwo auf der rechten Seite des Worldbulder-Fensters die x- und y-Koordinaten dieses Feldes ablesen kann. Das klingt zwar kompliziert, aber ich kenne keine bessere Möglichkeit ). Wir nehmen in unserem Beispiel mal an, dass die x-Koordinate 63 und die y-Koordinate gleich 13 an.
Jetzt erstellen wir eine Schaltfläche vom Typ "Action Control" (am besten tut man das in einem eigenen Tab für Testzwecke, wobei dieses Beispiel keinen speziellen Lua-Zustand benötigt und man daher jeden beliebigen Zustand verwenden kann) und fügt dann im aufploppenden Fenster im "Action"-Bereich den folgenden Lua-Code ein:

local pPlot = Map.GetPlot(63, 13);
pPlot:SetResourceType(41,1); 

Die Funktion Map.GetPlot gibt dabei das Hexfeld wieder, das durch die Koordinaten im Funktionsargument bestimmt ist.
Die Funktion pPlot:SetResourceType sorgt dafür, dass auf diesem Hexfeld, das in unserem Beispiel pPlot genannt wird, mit der gewünschten Ressource versehen wird. Im ersten Argument steht dabei der Zahlencode der Ressource, den man, wie im 2. Beispiel berschrieben, selber herausfinden kann. In diesem Fall steht die Zahl 41 für die Kakao-Ressource. Im zweiten Argument steht, wie oft die Ressource auf diesem Feld vorkommen soll.
Wenn man diesen Code jetzt abspeichert und auf die Schaltfläche einmal klickt, erscheint eine Kakao-Ressource auf dem entsprechenden Feld. Man kann im Code natürlich weitere Befehle eingeben, wenn man z.B. mehr als nur eine Ressource auf einmal einfügen möchte.

Beispiel 2: Um den Zahlencode einer Ressource herauszufinden, kann man eine "Action"-Schaltfläche mit dem folgende Lua-Code verwenden:

for i = 0, 41, 1 do
local pPlot = Map.GetPlot(i, 0); 
pPlot:SetResourceType(i,1)    
end 

Dieser Code setzt alle Ressourcen von 0 bis 41 der Reihe nach auf die Felder mit den Koordinaten (0,0) bis (41,0) (da die y-Koordinate hier immer 0 ist, sollte man die Ressourcen im Süden im ewigen Eis suchen ).
Um sich diese Ressourcen ansehen zu können, kann man im "Map"-Tab auf den Button "Reveal/Refresh Map" klicken, damit die gesamte Karte aufgedeckt wird. Um auch alle entstandenen strategischen Ressourcen und die archäologische Fundstätte sehen zu können, sollte man im Tab "Active Player" auf den Button "Future Era Techs" klicken, damit man alle benötigten Technologien für diese Ressourcen erhält.
Das Ergebnis sollte dann in etwa so aussehen:



D.h. also dass z.B. Eisen den Code 0 hat, Uran den Code 5, Wild den Code 9 usw.
In diesem Beispiel sollte man beachten, dass die Karte nicht zu klein sein sollte, da der Lua-Code sonst auf ein nicht existierendes Feld zurückgreifen könnte und dadurch ein Fehler entsteht. Außerdem sollte man beachten, dass man nur akzeptable Zahlencodes für die Ressourcen benutzt. Falls eine Zahl verwendet wird, die keiner Ressource zugeordnet werden kann, kann das nämlich ebenfalls einen Fehler erzeugen.


Problembehandlungen

Firetuner hat aber leider manchmal auch einige Macken. Wenn ein Plopper oder gar der ganze Firetuner nicht funktionieren will, könnt ihr die folgenden Punkte durchlaufen, bis euer Problem gelöst ist:

1. Firetuner einfach neustarten!
2. Bei Hotseat-Spielen kann es sein, dass man beim ersten Erstellen des Hotseats das Spiel erst abspeichern und dann neu laden muss, damit sich Firetuner überhaupt mit dem Spiel verbindet.
3. Falls eines der Schaltflächen rot angezeigt wird, wurde es wahrscheinlich falsch programmiert, sodass man den Fehler editieren sollte. Manchmal ist es aber richtig programmiert, sodass man im Menü auf "Connection->Force Connection" klicken sollte, damit Firetuner erneut connected und sich dadurch richtig updaten kann.
4. Überprüfen, ob alle Lua-Funktionen in dem Tab den geeigneten Lua-Zustand verwenden.
5. Wenn ein Plopper nicht funktionieren will, wechselt man zu einem anderen Tab und dann wieder zurück zum ursprünglichen Tab, denn sonst wird Firetuner manchmal nicht geupdatet und dadurch die neuen Ploppereinstellungen noch nicht angenommen.
6. Selber herumprobieren, bis der Fehler behoben ist.

Quelle(n):

• http://forums.civfanatics.com/showthread.php?t=399821

[derboe]

Krasser Scheiß
Damit lässt sich ja echt heftig was basteln (nur kostet es noch mehr Zeit )

Was mir noch aufgefallen ist, dass
Zeilenkoordinaten(Y-Koordinaten) von unten nach oben und
Spaltenkoordinaten(X-Koordinaten) von links nach rechts gezählt werden

Um die Koordinaten rauszubekommen kann man unter Umständen auch über den Reiter "Selected City" gehen
Da findet man zumindest die Koordinaten seiner Städte. Damit kann man evtl. anfangen.
Auf jedenfall wird man für weitreichende Änderungen ein wenig längere Skripte schreiben müssen

Ich hab mal die Ressourcenliste und ihre IDs hier zusammengehauen, kann man ja mal irgendwo sammeln, zusammen mit den noch offenen Listen

Achtung Spoiler:

ID;Ressource

0;Eisen

1;Pferde

2;Kohle

3;Öl

4;Aluminium

5;Uran

6;Weizen

7;Vieh

8;Schafe

9;Wild

10;Bananen

11;Fisch

12;Stein

13;Wale

14;Perlen

15;Gold

16;Silber

17;Diamanten

18;Marmor

19;Elfenbein

20;Pelze

21;Färbemittel

22;Gewürze

23;Seide

24;Zucker

25;Baumwolle

26;Wein

27;Räucherwerk

28;Schmuck

29;Porzellan

30;Kupfer

31;Salz

32;Krabben

33;Trüffel

34;Zitronen

35;Altertumsstätte

36;Muskat

37;Gewürznelken

38;Pfeffer

39;Verborgene Altertumsstätte

40;Bison

41;Kakao

[Tiramisu]

Bravo!

[AndreP]

Super, ich hab das Thema angepinnt.

[Tiramisu]

Danke fürs Anpinnen, aber eigentlich ist es bis jetzt noch ein sehr bescheidenes Tutorial.
Ich denke, ich werde hier erst mal ein paar Infos zusammentragen, bis ich genug Infos für ein weiteres Thema habe, das ich im Inhaltsverzeichnis verlinken kann.

Was ich dank dem C++ Code gerade herausgefunden habe (und was derboe bestimmt interessieren würde ), ist dass man mit der Funktion GetResourceType die Ressource (bzw. den Zahlencode der Ressource) eines Hexfeldes bestimmen kann und dadurch nicht jede Ressource manuell suchen muss. Das könnte nicht nur für Kartenersteller interessant sein, sondern auch für eine Mod, die es dem Spieler erlaubt, alle Vorkommen einer Ressource per Klick nacheinander auf der Karte durchzusuchen, damit man nicht ewig auf der Karte suchen muss.

Zunächst einmal braucht man dazu eine Plotvariable pPlot, die ein Hexfeld repräsentiert. Z.B.

local pPlot = Map.GetPlot(63, 13); 

Um den Code der Ressource auf dem Hexfeld pPlot zu erhalten, schreibt man dann

pPlot:GetResourceType(-1) 

GetResourceType ist also so eine Art Memberfunktion von pPlot, wobei im Argument dieser Funktion der Zahlencode des Spielerteams ist. Falls nämlich ein Team eine bestimmte Tech bzw. den Entdeckungs-Finisher zum Aufdecken der Ressource nicht hat, dann wird -1 ausgegeben, wobei -1 immer der Code für "Keine Ressource" ist. Falls man für den Teamcode -1 einsetzt (wie im obigen Lua-Code steht das dann für "Kein Team"), dann wird immer der wahre Ressourcencode angezeigt, weil das Team "Kein Team" immer alles sehen kann.

Hier ein vollständiger Beispielcode, der dafür sorgt, dass alle Kakao-Ressourcen (Ressi-Code 41) in Zitronen (Ressi-Code 34) umgewandelt werden:

for iPlotLoop = 0, Map.GetNumPlots()-1, 1 do
local pPlot = Map.GetPlotByIndex(iPlotLoop);

if pPlot:GetResourceType(-1) == 41 then
pPlot:SetResourceType(34,1) ;
end

end 

[derboe]

supi das erspart mir wieder etwas Zeit beim Suchen. Ich hab da schon 2-3 nette Ideen, die ich nachher mal austesten will.