Es gibt verschiedene Anwendungsfälle, in denen man bestimmte Gebäude oder Einheiten eines Spielers auf der Karte finden möchte. Beispielsweise könnte man ermitteln, wie viele Kanonentürme ein Spieler besitzt oder wie stark seine Militärpräsenz in einem gegebenen Gebiet ist. Auch im Zusammenhang mit SetupEstablish wird so eine Funktion oft gebraucht, um das vom Spieler gebaute Gebäude dem Spieler des Auftraggebers zu überreichen.

In diesem Artikel wollen wir deshalb einige Funktionen beleuchten, die Spieler-Einheiten und -Gebäude nach einstellbaren Kriterien finden. Konkret werden bei jeder dieser Funktionen die Entity-Ids jener Entities ermittelt, auf die die Kriterien (wie zum Beispiel Ort und Entity-Typ) zutreffen.

Auch handelt es sich bei den folgenden Funktionen um Logic.-Funktionen, sind also nicht mehr innerhalb des Comfort-Layers. Das bedeutet, dass wir Skriptnamen und Positions-Tables händisch verarbeiten müssen, da das nicht mehr automatisch im Hintergrund geschieht. Auch werden diese Funktionen mit mehreren Rückgabewerten und optionalen Parametern arbeiten. Die entsprechenden Stellen im verlinkten Artikel sollten also geläufig sein.

Logic.GetEntities(_EntityType, _Amount) gibt höchstens _Amount Entity-Ids zurück, deren Entities vom Typ _EntityType sind. Die Entity-Suche ist nicht weiter beschränkt, bezieht sich also auf die komplette Karte.

Die Funktion gibt mehrere Werte zurück, wovon der erste die Anzahl der gefundenen Entities ist und deshalb keine gültige Entity-Id ist!

Alle weiteren Rückgabewerte sind Entity-Ids der gefundenen Entities vom Typ _EntityType. Dabei entspricht die Anzahl der Rückgabewerte der Anzahl an gefundenen Entities und deshalb nicht notwendigerweise _Amount (wenn weniger als _Amount Entities vom Typ _EntityType auf der Karte existieren).
Das bedeutet, dass die Funktion genau 1 + #Entities Rückgabewerte hat.

Achtung: _Amount ist auf den Maximalwert 16 beschränkt! Mehr Entity-Ids kann die Funktion nicht zurückgeben. Wenn du beispielsweise bei _Amount 20 angibst, werden trotzdem maximal 16 Entity-Ids zurückgegeben.

Wie im Artikel zu mehreren Rückgabewerten beschrieben, können diese Rückgabewerte auf unterschiedliche Arten in Variablen geschrieben werden.

Diese Variante ist vor allem sinnvoll, wenn nicht mehr als 1 oder 2 Entities gesucht werden, da für jede potenziell gefundene Entity eine eigene Variable angelegt werden muss:

-- In diesem Beispiel suchen wir nach höchstens zwei Tempelaltären
local NumberOfEntities, EntityId1, EntityId2 = Logic.GetEntities(Entities.XD_TemplarAltar, 2)

Die Funktion kann maximal 2 Tempelaltäre finden, aber auch weniger. Davon abhängig resultieren unterschiedliche Rückgabewerte:

• Wenn NumberOfEntities== 0, dann sind sowohl EntityId1 als auch EntityId2 beide nil
• Wenn NumberFoundEntities == 1, dann ist EntityId1 die Entity-Id eines Tempelaltars und EntityId2 ist nil
• Wenn NumberFoundEntities == 2, dann sind sowohl EntityId1 als auch EntityId2 Entity-Ids eines Tempelaltars

Diese Variante eignet sich vor allem, um zu prüfen, ob ein Entity-Typ überhaupt auf der Karte existiert:

function IsEntityTypeOnMap(_EntityType)
    -- Es ist guter Stil, mit dem Unterstrich anzuzeigen, dass dieser Wert ignoriert wird. 
    -- Auf der Logikebene macht es keinen Unterschied, für den Leser wird aber schneller ersichtlich, 
    -- welche Variablen von Bedeutung sind
    local NumberOfEntities, _ = Logic.GetEntities(_EntityType, 1)
    return NumberOfEntities > 0
end

Wenn man deutlich mehr als zwei Entities sucht, bekommt man über Variante 1 eine unübersichtliche Schreibarbeit. Wir suchen den selben Entity-Typ diesmal deutlich öfter:

-- In diesem Beispiel suchen wir nach höchstens acht Tempelaltären
local FoundEntityIds = { Logic.GetEntities(Entities.XD_TemplarAltar, 8) }

Die größe des Tables ist dabei immer 1 + #Entities, wobei in FoundEntityIds[1] die Anzahl der gefundenen Entities steht. Wenn FoundEntityIds[1] == 0 ist, ist das Table an der Stelle zuende. Andernfalls ist genau die Anzahl an EntityIds ebenfalls mit im Table (bei FoundEntities[1] == 4 sind beispielsweise FoundEntities[2] bis FoundEntities[5] befüllt).

Um die Siedlungsplätze auf unserer Karte etwas heimeliger zu machen, wollen wir vor jedem eine kleine Sitzbank aufstellen. Mit Logic.GetEntities holen wir uns die Entity-Ids aller Siedlungsplätze, emitteln anhand der Ids deren Position und stellen versetzt zu diesen Positionen Bänke auf.

function PlaceBenches()
    -- es sollten nicht mehr als 16 Siedlungsplätze auf der Karte sein
    local VillageCenterIds = { Logic.GetEntities(Entities.XD_VillageCenter, 16) }
 
    -- Im ersten Eintrag vom Table VillageCenterIds steht die Anzahl der gefundenen Entities
    -- Die benutzen wir direkt für die Schleife
    -- Die Zählvariable beginnt bei 2, da der erste Eintrag keine Entity-Id ist
    for i = 2, VillageCenterIds[1] + 1 do
        local VCPosition = GetPosition(VillageCenterIds[i])
        -- Liebes BlueByte, die Sitzbank heißt auf Englisch "Bench", nicht "Bank"! :<
        -- Wir verwenden hier Logic.CreateEntity, um die Rotation der Bank einstellen zu können
        -- Die Parameter sind dafür etwas anders, siehe die Logic-Referenz
        Logic.CreateEntity(Entities.XD_MiscBank1, VCPosition.X + 300, VCPosition.Y - 600, 0, 0)
    end
end

Logic.GetEntitiesInArea(_EntityType, _PositionX, _PositionY, _Radius, _Amount) gibt höchstens _Amount Entity-Ids zurück, deren Entities vom Typ _EntityType sind und höchstens den Abstand _Radius von der Position (_PositionX, _PositionY) haben.

Die Funktion gibt mehrere Werte zurück, wovon der erste die Anzahl der gefundenen Entities ist und deshalb keine gültige Entity-Id ist!

Alle weiteren Rückgabewerte sind Entity-Ids der gefundenen Entities vom Typ _EntityType. Dabei entspricht die Anzahl der Rückgabewerte der Anzahl an gefundenen Entities und deshalb nicht notwendigerweise _Amount (wenn weniger als _Amount Entities vom Typ _EntityType auf der Karte existieren).
Das bedeutet, dass die Funktion genau 1 + #Entities Rückgabewerte hat.

Achtung: _Amount ist auf den Maximalwert 16 beschränkt! Mehr Entity-Ids kann die Funktion nicht zurückgeben. Wenn du beispielsweise bei _Amount 20 angibst, werden trotzdem maximal 16 Entity-Ids zurückgegeben.

Tipp: Du kannst deinen gewünschten Radius durch Platzieren eines XS_Ambient auf die Position ermitteln. Das 100-fache der angegebenen Größe der Ambient-Entity entspricht genau dem anzugebenden _Radius.

Wie im Artikel zu mehreren Rückgabewerten beschrieben, können diese Rückgabewerte auf unterschiedliche Arten in Variablen geschrieben werden.

Diese Variante ist vor allem sinnvoll, wenn nicht mehr als 1 oder 2 Entities gesucht werden, da für jede potenziell gefundene Entity eine eigene Variable angelegt werden muss:

-- In diesem Beispiel suchen wir nach höchstens zwei Mauertoren im Gebiet
local NumberOfEntities, EntityId1, EntityId2 = Logic.GetEntitiesInArea(Entities.XD_WallStraightGate, 4900, 13100, 3000, 2)

Die Funktion kann maximal 2 Mauertore finden, aber auch weniger. Davon abhängig resultieren unterschiedliche Rückgabewerte:

• Wenn NumberOfEntities== 0, dann sind sowohl EntityId1 als auch EntityId2 beide nil
• Wenn NumberFoundEntities == 1, dann ist EntityId1 die Entity-Id eines Mauertors und EntityId2 ist nil
• Wenn NumberFoundEntities == 2, dann sind sowohl EntityId1 als auch EntityId2 Entity-Ids eines Mauertors

Diese Variante eignet sich vor allem, um zu prüfen, ob ein Entity-Typ überhaupt im gegebenen Gebiet vorhanden ist:

function IsEntityTypeInArea(_EntityType, _Position, _Radius)
    -- Es ist guter Stil, mit dem Unterstrich anzuzeigen, dass dieser Wert ignoriert wird. 
    -- Auf der Logikebene macht es keinen Unterschied, für den Leser wird aber schneller ersichtlich, 
    -- welche Variablen von Bedeutung sind
    local NumberOfEntities, _ = Logic.GetEntitiesInArea(_EntityType, _Position.X, _Position.Y, _Radius, 1)
    return NumberOfEntities > 0
end

Wenn man deutlich mehr als zwei Entities sucht, bekommt man über Variante 1 eine unübersichtliche Schreibarbeit. Wir suchen den selben Entity-Typ diesmal deutlich öfter:

-- In diesem Beispiel suchen wir nach höchstens acht Mauertoren in einem größeren Gebiet
local FoundEntityIds = { Logic.GetEntitiesInArea(Entities.XD_WallStraightGate, 4900, 13100, 8000, 8)) }

Die größe des Tables ist dabei immer 1 + #Entities, wobei in FoundEntityIds[1] die Anzahl der gefundenen Entities steht. Wenn FoundEntityIds[1] == 0 ist, ist das Table an der Stelle zuende. Andernfalls ist genau die Anzahl an EntityIds ebenfalls mit im Table (bei FoundEntities[1] == 4 sind beispielsweise FoundEntities[2] bis FoundEntities[5] befüllt).

Im Winter sollen Laubbäume ihre Blätter verlieren. Das macht Siedler nicht automatisch und meistens fehlen dafür auch die passenden Entity-Typen. Für TreeNorth und DeadTreeNorth funktioniert das allerdings sehr gut.

Wir ersetzen also in einem bestimmten Gebiet alle Entities vom Typ XD_TreeNorth1 durch XD_DeadTreeNorth1 (für TreeNorth2 und 3 entsprechend auch).

-- Wir formulieren das oben Beschriebene als wiederverwendbare Funktion
-- Das hat den Grund, dass Logic.GetEntitiesInArea maximal 16 Entities zurückgeben kann. Da meistens
-- deutlich mehr als 16 Bäume eines Typs auf der Karte stehen, muss die Funktion an verschiedenen Stellen
-- auf der Karte (möglicherweise wiederholt) aufgerufen werden
function TreeNorthLoseLeaves(_Position, _Radius)
    -- Wir definieren ein Table, das angibt, welche Baumtypen durch die blattlosen zu ersetzen sind
    local ReplaceTypes = {
        [Entities.XD_TreeNorth1] = Entities.XD_DeadTreeNorth1,
        [Entities.XD_TreeNorth2] = Entities.XD_DeadTreeNorth2,
        [Entities.XD_TreeNorth3] = Entities.XD_DeadTreeNorth3
    }
    for SummerTreeType, WinterTreeType in pairs(ReplaceTypes) do
        local TreeIds = { Logic.GetEntitiesInArea(SummerTreeType, _Position.X, _Position.Y, _Radius, 16) }
        -- Im ersten Eintrag vom Table TreeIds steht die Anzahl der gefundenen Entities
        -- Die benutzen wir direkt für die Schleife
        -- Die Zählvariable beginnt bei 2, da der erste Eintrag keine Entity-Id ist
        for i = 2, TreeIds[1] + 1 do
            -- ReplaceEntity ersetzt eine Entity durch den angegebenen Entity-Typ
            -- Mehr zu dieser Funktion findest du in der Comfort-Referenz und im Artikel
            -- zu "Belohnungen" auf Ebene 2
            ReplaceEntity(TreeIds[i], WinterTreeType)
        end
    end
end

Logic.GetPlayerEntities(_PlayerId, _EntityType, _Amount) gibt höchstens _Amount Entity-Ids zurück, deren Entities vom Typ _EntityType sind und Spieler _PlayerId gehören. Die Entity-Suche ist nicht weiter beschränkt, bezieht sich also auf die komplette Karte.

Die Funktion gibt mehrere Werte zurück, wovon der erste die Anzahl der gefundenen Entities ist und deshalb keine gültige Entity-Id ist!

Alle weiteren Rückgabewerte sind Entity-Ids der gefundenen Entities vom Typ _EntityType. Dabei entspricht die Anzahl der Rückgabewerte der Anzahl an gefundenen Entities und deshalb nicht notwendigerweise _Amount (wenn weniger als _Amount Entities vom Typ _EntityType auf der Karte existieren).
Das bedeutet, dass die Funktion genau 1 + #Entities Rückgabewerte hat.

Achtung: _Amount ist auf den Maximalwert 16 beschränkt! Mehr Entity-Ids kann die Funktion nicht zurückgeben. Wenn du beispielsweise bei _Amount 20 angibst, werden trotzdem maximal 16 Entity-Ids zurückgegeben.

Wie im Artikel zu mehreren Rückgabewerten beschrieben, können diese Rückgabewerte auf unterschiedliche Arten in Variablen geschrieben werden.

Diese Variante ist vor allem sinnvoll, wenn nicht mehr als 1 oder 2 Entities gesucht werden, da für jede potenziell gefundene Entity eine eigene Variable angelegt werden muss:

-- In diesem Beispiel suchen wir nach höchstens zwei Kathedralen von Spieler 1
local NumberOfEntities, EntityId1, EntityId2 = Logic.GetPlayerEntities(1, Entities.PB_Monastery3, 2)

Die Funktion kann maximal 2 Kathedralen finden, aber auch weniger. Davon abhängig resultieren unterschiedliche Rückgabewerte:

• Wenn NumberOfEntities== 0, dann sind sowohl EntityId1 als auch EntityId2 beide nil
• Wenn NumberFoundEntities == 1, dann ist EntityId1 die Entity-Id einer Kathedrale und EntityId2 ist nil
• Wenn NumberFoundEntities == 2, dann sind sowohl EntityId1 als auch EntityId2 Entity-Ids einer Kathedrale

Diese Variante eignet sich vor allem, um zu prüfen, ob ein Entity-Typ überhaupt auf der Karte existiert:

function IsPlayerEntityOfTypeOnMap(_PlayerId, _EntityType)
    -- Es ist guter Stil, mit dem Unterstrich anzuzeigen, dass dieser Wert ignoriert wird. 
    -- Auf der Logikebene macht es keinen Unterschied, für den Leser wird aber schneller ersichtlich, 
    -- welche Variablen von Bedeutung sind
    local NumberOfEntities, _ = Logic.GetPlayerEntities(_PlayerId, _EntityType, 1)
    return NumberOfEntities > 0
end

Wenn man deutlich mehr als zwei Entities sucht, bekommt man über Variante 1 eine unübersichtliche Schreibarbeit. Wir suchen den selben Entity-Typ diesmal deutlich öfter:

-- In diesem Beispiel suchen wir nach höchstens acht Kathedralen
local FoundEntityIds = { Logic.GetPlayerEntities(1, Entities.PB_Monastery3, 8) }

Die größe des Tables ist dabei immer 1 + #Entities, wobei in FoundEntityIds[1] die Anzahl der gefundenen Entities steht. Wenn FoundEntityIds[1] == 0 ist, ist das Table an der Stelle zuende. Andernfalls ist genau die Anzahl an EntityIds ebenfalls mit im Table (bei FoundEntities[1] == 4 sind beispielsweise FoundEntities[2] bis FoundEntities[5] befüllt).

Ein großzügiger Architekt kommt in die Stadt und bietet an, alle kleinen Wohnhäuser für den Spieler zu mittleren Wohnhäusern auszubauen. Wir ermitteln die Entity-Ids aller Wohnhäuser von Spieler 1 mit Logic.GetPlayerEntities und bauen diese per Skript aus:

-- Wir hoffen in diesem Fall, dass der Spieler nicht mehr als 16 kleine Wohnhäuser hat
local ResidenceIds = { Logic.GetPlayerEntities(1, Entities.PB_Residence1, 16) }
-- Im ersten Eintrag vom Table ResidenceIds steht die Anzahl der gefundenen Entities
-- Die benutzen wir direkt für die Schleife
-- Die Zählvariable beginnt bei 2, da der erste Eintrag keine Entity-Id ist
for i = 2, ResidenceIds[1] + 1 do
    -- ReplaceEntity ersetzt eine Entity durch den angegebenen Entity-Typ
    -- Mehr zu dieser Funktion findest du in der Comfort-Referenz und im Artikel
    -- zu "Belohnungen" auf Ebene 2
    ReplaceEntity(ResidenceIds[i], Entities.PB_Residence2)
end

Logic.GetPlayerEntitiesInArea(_PlayerId, _EntityType, _PositionX, _PositionY, _Radius, _Amount, _AccessCategory) gibt höchstens _Amount Entity-Ids zurück, deren Entities vom Typ _EntityType sind, höchstens den Abstand _Radius von der Position (_PositionX, _PositionY) haben und Spieler _PlayerId gehören. Der Parameter _AccessCategory ist optional und greift auch nur in einem Sonderfall, den wir weiter unten behandeln.

Die Funktion gibt mehrere Werte zurück, wovon der erste die Anzahl der gefundenen Entities ist und deshalb keine gültige Entity-Id ist!

Alle weiteren Rückgabewerte sind Entity-Ids der gefundenen Entities vom Typ _EntityType. Dabei entspricht die Anzahl der Rückgabewerte der Anzahl an gefundenen Entities und deshalb nicht notwendigerweise _Amount (wenn weniger als _Amount Entities vom Typ _EntityType auf der Karte existieren).
Das bedeutet, dass die Funktion genau 1 + #Entities Rückgabewerte hat.

Achtung: _Amount ist auf den Maximalwert 16 beschränkt! Mehr Entity-Ids kann die Funktion nicht zurückgeben. Wenn du beispielsweise bei _Amount 20 angibst, werden trotzdem maximal 16 Entity-Ids zurückgegeben.

Tipp: Du kannst deinen gewünschten Radius durch Platzieren eines XS_Ambient auf die Position ermitteln. Das 100-fache der angegebenen Größe der Ambient-Entity entspricht genau dem anzugebenden _Radius.

Wie im Artikel zu mehreren Rückgabewerten beschrieben, können diese Rückgabewerte auf unterschiedliche Arten in Variablen geschrieben werden.

Diese Variante ist vor allem sinnvoll, wenn nicht mehr als 1 oder 2 Entities gesucht werden, da für jede potenziell gefundene Entity eine eigene Variable angelegt werden muss:

-- In diesem Beispiel suchen wir nach höchstens zwei Leibeigene von Spieler 1 im Gebiet
local NumberOfEntities, EntityId1, EntityId2 = Logic.GetPlayerEntitiesInArea(1, Entities.PU_Serf, 4900, 13100, 3000, 2)

Die Funktion kann maximal 2 Leibeigene finden, aber auch weniger. Davon abhängig resultieren unterschiedliche Rückgabewerte:

• Wenn NumberOfEntities== 0, dann sind sowohl EntityId1 als auch EntityId2 beide nil
• Wenn NumberFoundEntities == 1, dann ist EntityId1 die Entity-Id eines Leibeigenen und EntityId2 ist nil
• Wenn NumberFoundEntities == 2, dann sind sowohl EntityId1 als auch EntityId2 Entity-Ids eines Leibeigenen

Diese Variante eignet sich vor allem, um zu prüfen, ob ein Entity-Typ überhaupt im gegebenen Gebiet vorhanden ist:

function IsPlayerEntityOfTypeInArea(_PlayerId, _EntityType, _Position, _Radius)
    -- Es ist guter Stil, mit dem Unterstrich anzuzeigen, dass dieser Wert ignoriert wird. 
    -- Auf der Logikebene macht es keinen Unterschied, für den Leser wird aber schneller ersichtlich, 
    -- welche Variablen von Bedeutung sind
    local NumberOfEntities, _ = Logic.GetPlayerEntitiesInArea(_PlayerId, _EntityType, _Position.X, _Position.Y, _Radius, 1)
    return NumberOfEntities > 0
end

Wenn man deutlich mehr als zwei Entities sucht, bekommt man über Variante 1 eine unübersichtliche Schreibarbeit. Wir suchen den selben Entity-Typ diesmal deutlich öfter:

-- In diesem Beispiel suchen wir nach höchstens acht Mauertoren in einem größeren Gebiet
local FoundEntityIds = { Logic.GetPlayerEntitiesInArea(Entities.PU_Serf, 4900, 13100, 8000, 8)) }

Die größe des Tables ist dabei immer 1 + #Entities, wobei in FoundEntityIds[1] die Anzahl der gefundenen Entities steht. Wenn FoundEntityIds[1] == 0 ist, ist das Table an der Stelle zuende. Andernfalls ist genau die Anzahl an EntityIds ebenfalls mit im Table (bei FoundEntities[1] == 4 sind beispielsweise FoundEntities[2] bis FoundEntities[5] befüllt).

-- Eigentlich sollte man nicht auf deutsch programmieren. Versuche, auf englische Namen umzusteigen
-- Kommentare kannst du dann dafür nutzen, zu erklären, was die Funktion macht, also z.B:
-- Diese Funktion wird nach dem Bau der Garnision bei Position "kaserne" im Zusammenhang mit der Quest ??? aufgerufen 
-- Sie übergibt die errichtete Garnision an Spieler 2 
-- (usw. was auch immer noch folgt)
-- Falls mal etwas nicht funktioniert, kannst du anhand solcher Notizen schneller prüfen, ob die Funktion
-- das tut, was sie soll
function Kasernefertig()
    -- Du lässt die Kaserne an Position "kaserne" mit Umkreis 3000 Siedler-cm bauen. Die Position muss man erst
    -- holen:
    local QuestPosition = GetPosition("kaserne")
    -- Wir brauchen die Variablen hier nur lokal. Kein Grund, sie global zu definieren
    -- Die Position ist jetzt in QuestPosition, der Umkreis ist 3000, Spieler hat Id 1 und wir suchen genau die eine Kaserne,
    -- die gebaut werden sollte
    local NumberFoundEntities, EntityId1 = Logic.GetPlayerEntitiesInArea(1, Entities.PB_Barracks2, QuestPosition.X, QuestPosition.Y, 3000, 1)
    -- Wenn die Quest korrekt funktioniert, sollte diese Bedingung immer zutreffen
    if NumberFoundEntities > 0 then
        -- Wechsle die Spieler-Id der gefundenen Kaserne zu Spieler 2
        ChangePlayer(EntityId1, 2)
    end
end