=====Belohnungen=====

FIXME dieser Artikel gehört zwischen SetupQuest und GetEntities

In vorigen Kapiteln wurde vorgestellt, wie man [[ scripting:tutorials:level2:npcs|NPCs erstellt]] und [[ scripting:tutorials:level2:setup_quest|Questbedingungen prüft]]. Verknüpft an die Erfüllung von Quests sind häufig Belohnungen - seien sie direkt greifbar, wie beispielsweise Ressourcen oder Progress-Belohnungen, wie ein sich öffnendes Tor.

Natürlich eignen sich die Funktionen, die [[ scripting:tutorials#die_spielvoraussetzungen_definieren|die Spielvoraussetzungen definieren]] bereits, den Spieler zu belohnen. In diesem Artikel beleuchten wir einige weitere Funktionen, die auf erfüllte Quests folgen können.

----

====CreateEntity====

Mit ''CreateEntity(_PlayerId, _EntityType, _Position, _Name)'' kann eine einzelne Entity erstellt werden. Die Parameter sind folgende:

  - **_PlayerId** - Die Spieler-Id der Entity, also eine ganze Zahl zwischen 0 und 8. Für Doodads, also Bäume, Steine, etc. sollte immer 0 verwendet werden, sonst eine Spieler-Id zwischen 1 und 8
  - **_EntityType** - Der Entity-Typ der Entity, also ein Eintrag im ''Entities''-Table. Technisch gesehen ist der Entity-Typ eine Zahl, der durch das interne ''Entities''-Table besser lesbar gemacht wird. Eine Übersicht findest du hier (FIXME link einfügen)
  - **_Position** - Die Position, an der das Entity erstellt werden soll, als Table im Format ''{X = x, Y = y}''. Die Funktion ''GetPosition'' (FIXME link einfügen) ermittelt die Position einer bestehenden Entity in diesem Format
  - **_Name** - Der Skriptname der zu erstellenden Entity als String. Dieser Parameter ist optional

Die Funktion gibt die Entity-Id der erstellten Entity zurück. Der Rotationswinkel der erstellten Entity ist zufällig.

**Hinweis**: ''CreateEntity'' eignet sich nicht, um komplette Truppen zu spawnen. Siehe dazu ''CreateMilitaryGroup'' weiter unten.

**Hinweis**: Wenn du mit ''CreateEntity'' beispielsweise neue Dorfzentren mit Spieler 0 auf die Karte setzen willst, wird das einen Fehler auslösen. Siehe Häufige Fehler (FIXME link einfügen), wie das verhindert werden kann.

===Beispiel===

Wenn der Spieler nach einer erfüllten Quest einen neuen Kundschafter erhalten soll, kann das so aussehen:

<code lua>
CreateEntity(1, Entities.PU_Scout, GetPosition("ScoutSpawn"))
</code>

Damit das funktioniert, muss auf der Karte eine ''ScriptEntity'' mit dem Namen ''"ScoutSpawn"'' existieren.

**Achtung**: Wenn du auf diese Weise neue Einheiten kreierst, stelle sicher, dass der Bereich um den Spawnpunkt nicht blockiert ist (zum Beispiel von vom Spieler errichteten Gebäuden). Es bietet sich an, solche Spawnpunkte in unbebaubare Gebiete zu setzen, bzw. in den vom Grid im Editor grün dargestellten Randbereich von bereits existieren Gebäuden.

----

====CreateMilitaryGroup====

Mit ''CreateMilitaryGroup(_PlayerId, _LeaderType, _Soldiers, _Position, _Name, _LookAt)'' kann eine komplette Soldatentruppe erstellt werden. Die Parameter sind folgende:

  - **_PlayerId** - Die Spieler-Id der Truppe, also eine ganze Zahl zwischen 1 und 8
  - **_LeaderType** - Der Entity-Typ des Hauptmanns, also ein Eintrag im ''Entities''-Table. Technisch gesehen ist der Entity-Typ eine Zahl, der durch das interne ''Entities''-Table besser lesbar gemacht wird. Eine Übersicht findest du hier (FIXME link einfügen). Der Name des Entity-Typs muss das Wort "Leader" enthalten
  - **_Soldiers** - Die Anzahl der Soldaten, die die Truppe erhalten soll (durch den Leader-Typ nach oben begrenzt)
  - **_Position** - Die Position, an der die Truppe erstellt werden soll, als Table im Format ''{X = x, Y = y}''. Die Funktion ''GetPosition'' (FIXME link einfügen) ermittelt die Position einer bestehenden Entity in diesem Format
  - **_Name** - Der Skriptname des zu erstellenden Hauptmanns als String. Dieser Parameter ist optional
  - **_LookAt** - Skriptname der Entity, auf die die neu erstellte Truppe ausgerichtet sein soll. Dieser Parameter ist optional

Die Funktion gibt **nicht** die Entity-Id des erstellten Hauptmanns zurück. Wenn du der Truppe also beispielsweise einen Laufbefehl (Move bzw. AttackMove FIXME link einfügen) geben willst, musst du einen Skriptnamen angeben.

===Beispiel===

Eine Arena hat zwei Spawnpunkte ''"ArenaSpawnLeft"'' und ''"ArenaSpawnRight"'', wo ein Schaukampf zwischen Spieler 1 und 2 stattfinden soll (Spieler 1 und 2 müssen untereinander verfeindet sein):

<code lua>
CreateMilitaryGroup(1, Entities.LeaderSword2, 4, GetPosition("ArenaSpawnLeft"), nil, "ArenaSpawnRight")
CreateMilitaryGroup(2, Entities.LeaderSword2, 4, GetPosition("ArenaSpawnRight"), nil, "ArenaSpawnLeft")
</code>

**Achtung**: Wenn du auf diese Weise neue Einheiten kreierst, stelle sicher, dass der Bereich um den Spawnpunkt nicht blockiert ist (zum Beispiel von vom Spieler errichteten Gebäuden). Es bietet sich an, solche Spawnpunkte in unbebaubare Gebiete zu setzen, bzw. in den vom Grid im Editor grün dargestellten Randbereich von bereits existieren Gebäuden.

----

====ChangePlayer====

Mit ''ChangePlayer(_Entity, _PlayerId)'' kann der Spieler, dem eine Entity ''_Entity'' gehört, verändert werden. Die Parameter sind folgende:

  - **_Entity** - Skriptname oder Entity-Id der Entity, deren Spieler geändert werden soll
  - **_PlayerId** - Neue Spieler-Id der Entity, also eine ganze Zahl zwischen 1 und 8

**Wichtig**: Beim Spielerwechsel ändert sich die Entity-Id der angegebenen Entity, aber nicht der Skriptname! Die Funktion gibt die neue Entity-Id zurück.

===Beispiel===

Nach Erfüllung einer Quest oder Bezahlung eines Tributs soll der Spieler ein bereits bestehendes Dorfzentrum eines anderen Spielers erhalten. Das Dorfzentrum hat den Skriptnamen ''"VillageCenter"''.

<code lua>
ChangePlayer("VillageCenter", 1)
</code>

----

====DestroyEntity====

Mit ''Destroy(_Entity)'' kann eine Entity zerstört werden (also von der Map entfernt).Der Parameter ist folgender:

  - **_Entity** - Skriptname oder Entity-Id der Entity, die zerstört werden soll

===Beispiel===

Nach der Erfüllung einer Quest räumt ein Arbeiter für den Spieler den Weg frei, der von einigen Steinen blockiert wird. Sind auf der Karte vier Steine mit durchnummerierten Skriptnamen ''"Rock1"''..''"Rock4"'' platziert, lassen sie sich so in einer Schleife entfernen:

<code lua>
for i = 1, 4 do
    -- da die Steine alle nach dem gleichen Schema benannt sind, können wir eine Schleife zu
    -- deren Zerstörung benutzen
    DestroyEntity("Rock"..i)
end
</code>

----

====ReplaceEntity====

Mit ''ReplaceEntity(_Entity, _EntityType)'' kann der Typ einer Entity ''_Entity'' verändert werden. Die Parameter sind folgende:

  - **_Entity** - Skriptname oder Entity-Id der Entity, deren Spieler geändert werden soll
  - **_EntityType** - Der neue Entity-Typ der Entity, also ein Eintrag im ''Entities''-Table. Technisch gesehen ist der Entity-Typ eine Zahl, der durch das interne ''Entities''-Table besser lesbar gemacht wird. Eine Übersicht findest du hier (FIXME link einfügen)

**Wichtig**: Beim Ersetzen des Entity-Typs ändert sich die Entity-Id der angegebenen Entity, aber nicht der Skriptname! Die Funktion gibt die neue Entity-Id zurück.

===Beispiel===

Die wohl häufigste Anwendung findet diese Funktion beim Öffnen und Schließen von Toren. Auch das Heben und Senken von Zugbrücken lässt sich damit realisieren.

Wir gehen in den folgenden Beispielen davon aus, dass auf der Karte ein ''XD_WallStraightGate'' mit dem Namen ''"StoneGate"'', ein ''XD_PalisadeGate1'' mit dem Namen ''"PalisadeGate"'' und eine ''XD_DrawBridgeOpen1'' mit dem Namen ''"DrawBridge"'' existieren.

Die Kommentare im Codebeispiel beschreiben, was der jeweilige ''ReplaceEntity''-Aufruf bewirkt.

<code lua>
-- Schließe das Steintor
ReplaceEntity("StoneGate", Entities.XD_WallStraightGate_Closed)

-- Öffne das Steintor
ReplaceEntity("StoneGate", Entities.XD_WallStraightGate)

-- Öffne das Palisadentor
ReplaceEntity("PalisadeGate", Entities.XD_PalisadeGate2)

-- Schließe das Palisadentor
ReplaceEntity("PalisadeGate", Entities.XD_PalisadeGate1)

-- Schließe die Zugbrücke
ReplaceEntity("DrawBridge", Entities.PB_DrawBridgeClosed1)

-- Öffne die Zugbrücke
ReplaceEntity("DrawBridge", Entities.XD_DrawBridgeOpen1)
</code>

**Hinweis**: Wenn du mit ''ReplaceEntity'' beispielsweise die Zugrücke schließt, wird das einen Fehler auslösen. Der Grund ist der gleiche wie beim Erstellen von Gebäuden mit Spieler 0 mittels ''CreateEntity''. Siehe Häufige Fehler (FIXME link einfügen), wie das verhindert werden kann.

----

====SetHealth====

Mit ''SetHealth(_Entity, _Health)'' kann die Menge der Lebenspunkte (in Prozent) für die Entity ''_Entity'' gesetzt werden. Die Parameter sind folgende:

  - **_Entity** - Skriptname oder Entity-Id der Entity, deren Lebenspunkt geändert werden sollen
  - **_Health** - Menge der Lebenspunkte in Prozent. 100 bedeutet vollständig gesund, 0 bedeutet tot

===Beispiel===

Nach der Erfüllung einer Quest bietet ein Heiler an, Dario (Skriptname ''"Dario"'') vollständig zu heilen:
<code lua>
SetHealth("Dario", 100)
</code>

Ein Saboteur kann gegen einen Gefallen das feindliche Haupthaus (Skriptname ''"Player2"'') empfindlich schwächen:
<code lua>
SetHealth("Player2", 40)
</code>

----

Im nächsten Kapitel verlassen wir kurzzeitig den Comfort-Layer und betrachten einige ''Logic.''-Funktionen, um die Karte nach bestimmten Entities absuchen zu können.

[[ scripting:tutorials:level2:setup_quest| Voriges Kapitel: Orte erreichen, Gebäude bauen, Gegner besiegen ]] \\
[[ scripting:tutorials:level2:find_entities | Nächstes Kapitel: Spieler-Einheiten und -Gebäude finden ]] \\
[[ scripting:tutorials:level2:rewards | Zurück nach oben ]]