====== SetupCaravan ======

===== Questbeschreibung =====

Eine Karavane, bestehend aus einer oder mehreren beweglichen Entities, muss über vorgegebene Wegpunkte ein Ziel erreichen. Der Quest gilt als erfüllt, wenn alle noch lebende Entities das Ziel erreicht haben. \\
Der Quest wird vorzeitig beendet, falls keine Entity das Ziel erreicht, da sie zerstört/getötet wurde. \\
An jedem Wegpunkt wartet die Karavane eine bestimmte Zeit, bis sie zum nächsten Wegpunkt läuft. Erreicht eine Einheit das Zielgebiet, kann eine extra Callback Funktion aufgerufen werden, um den Spieler über aktuelle Ereignisse zu informieren.

===== Quest-Parameter =====

(Mit Parameter sind hier die Einträge in das Quest-Table gemeint.)

^Indexname^Beschreibung^
|**Unit**|1) Ein Table mit Entity-Namen aller an der Karavane beteiligten Einheiten oder \\ 2) Name ohne Index. __Beispiel:__ "Trader_" für "Trader_1", "Trader_2", "Trader_3", ..., "Trader_n"|
|**Waypoint**|Table mit allen Wegpunkten in folgendem Format: {\\ **Name** = Entity-Name des Wegpunktes (muss begehbar sein) \\ **WaitTime** = Zeit in Sekunden, in der sich die Karawane erholt \\ }|
|**Remove** (optional)|Wenn ungleich //nil// gesetzt, werden die Entities nach erreichen des Ziels von der Karte entfernt|
|**Callback**|Die "Standard"-Callback Funktion. Wird aufgerufen sobald der Quest erfüllt wurde oder nachdem alle Einheiten der Karavane tot sind|
|**ArrivedCallback** (optional)|Extra-Callback Funktion, die aufgerufen wird, sobald __eine__ Einheit das Ziel erreicht|

===== Callback-Parameter =====

Sowohl die Standard- als auch die Extra-Callback Funktion bekommen das komplette Quest-Table als Funktionsparameter übergeben. Zusätzlich enthält das Table den Wert **ArrivedCount**, der die Anzahl der bisher am Ziel angekommenen Entities enthält. Damit lässt sich z.B. überprüfen, ob genug Enheiten angekommen sind, oder ob alle unterwegs gestorben sind. (Siehe auch Beispiel)

===== Beispiel =====

<code=lua>local quest = {
	-- Zur Karavane gehören fünf Händler, die nach einem feucht-fröhlichen Abend nicht mehr in der Lage sind allein nach Haus zu laufen.
	-- "Trader" für "Trader1" bis "Trader5"
	Unit = "Trader",

	-- Der Weg zum heimischen Marktplatz führt über 3 Wegpunkte durch einen dunklen Wald. Die Händler brauchen eine halbe Minute um sich etwas zu erholen.
	Waypoint = {
		{Name = "WPForrest1", WaitTime = 30},
		{Name = "WPForrest2", WaitTime = 30},
		{Name = "WPForrest3", WaitTime = 30},
		{Name = "Market",     WaitTime = 30},
	},

	-- Wenn die Händler da sind, gehen sie natürlich gleich ins Bett und stehen nicht vor der Tür rum
	Remove = true,

	-- Wenn ein Händler ankommt, eine Message ausgeben, sofern es nicht der letzte war
	ArrivedCallback = function(_quest)
		-- Man kann hier table.getn() auf "Unit" anwenden, weil Unit auf jeden Fall in ein Table konvertiert wird, wenn der Quest startet
		if _quest.ArrivedCount < table.getn(_quest.Unit) then
			Message("Händler Nummer " .. _quest.ArrivedCount .. " ist angekommen!")
		end
	end,

	-- Noch eine eigene Variable speichern. Sie enthält die minimale Anzahl an Händlern die ankommen müssen, damit der Quest erfüllt ist
	Necessary = 3, -- 3 von 5 Händlern müssen ankommen

	-- In der abschließenden Callback-Funktion muss jetzt noch geprüft werden, ob genug Händler angekommen sind. Dafür benutzen wir die gerade definierte Variable
	Callback = function(_quest)
		-- Nicht genug Händler haben überlebt:(
		-- Der Spieler soll jetzt verlieren, weil er ohne die Händler nicht weiterkommen würde
		if _quest.ArrivedCount < _quest.Necessary then
			Defeat()

		-- Ansonsten geht es munter weiter - mit was auch immer...
		else
			Message("Super! Die Händler sind sicher zu Hause angekommen.")
			MacheEtwas()
		end
	end,
}

SetupCaravan(quest)</code>

===== Beispielmap =====

{{utilmaps:setupcaravan.rar|Download}} (Nebelreich-Map)

===== Benötigter Code =====

Nix:)

===== Siehe auch =====

[[utilfunctions:index#questfunktionen|Quest-Funktionen Übersicht]] \\
[[tutorials:questhandling_vereinfachen_selbstgebaut|Eigene Quest-Funktionen schreiben]]