# SU.Settlers.AddSettlersIfNeeded

## SU.Settlers.AddSettlersIfNeeded(x, y, playerID, settlerType, amount\[, radius=20\[, checkLandOwnedRadius=1\[, withBeds=0]]])

Erzeugt Siedler an den angegebenen Koordinaten, wenn im Radius nicht genügend vorhanden sind.\
Zusätzlich können gleich entsprechende Betten hinzugefügt werden, damit diese neuen Siedler nicht zu Streikenden führen können.

Der hauptsächliche Nutzen dieser Funktion ist es, (KI-)Spielern "unendlich" Träger geben zu können, ohne dass tausende herumstehen, sich gegenseitig blockieren und dadurch zu Leistungseinfällen zu führen.

Z.B. kann diese Funktion jede Minute aufgerufen werden und im angegebenen Bereich auf 50 Träger "auffüllen". Wählt man einen Ort, wo sich normalerweise keine Träger aufhalten, kann die KI dadurch unendlich lange Soldaten produzieren.

#### Notiz

* der Spieler darf noch nicht verloren haben
* wie die anderen Funktionen auch, sollte gerade diese Funktion nicht zu häufig aufgerufen werden (nicht alle paar Ticks), sondern lieber seltener (z.B. jede Minute), das reicht in den allermeisten Fällen aus
* der Radius muss mit Bedacht gewählt werden. Ist er zu klein, sodass `amount` viele gar keinen Platz darin hätten, werden unendlich lange Siedler hinzugefügt und das Spiel wird früher oder später daran abstürzen!
* wird die Funktion dauerhaft ausgeführt, sollte `withBeds` **nicht** aktiviert sein, da dies endlos Betten hinzufügt. Besser wäre es, die Bettenanzahl einmalig zu einem hohen Wert zu setzen\
  ⇒ [SU.Game.SetBeds](/s4-lua-api-de/su-library-functions/su.game/su.game.setbeds.md) bzw. [SU.Game.AddBeds](/s4-lua-api-de/su-library-functions/su.game/su.game.addbeds.md)

#### Parameter

* `x, y`: Koordinaten
* `playerID [1-8]`: Spieler-ID, **Index 0 ist ungültig!**
* `settlerType`: [Settlers](/s4-lua-api-de/api-enums/settlers.md)
* `amount`: Anzahl der hinzuzufügenden Siedler (inkl. Betten)
* `radius` (optional): Radius, in dem nach vorhandenen Siedlern gesucht wird. Um nicht endlos Siedler hinzuzufügen, muss der Radius **der Siedlermenge entsprechend groß genug** gesetzt werden!
* `checkLandOwnedRadius` (optional): Radius, in dem das Land dem Spieler gehören muss, um Siedler hinzuzufügen
* `withBeds` (optional): 1: Betten werden hinzugefügt, 0: ohne Betten

#### Rückgabewert

* Anzahl an hinzugefügten Siedlern
* -1: Fehler: das Land gehört dem Spieler nicht mehr oder er ist nicht mehr am Leben\
  ⇒ folglich sollte diese Funktion nicht mehr aufgerufen werden

#### Beispiel

```lua
local numAdded = SU.Settlers.AddSettlersIfNeeded(x, y, 3, Settlers.CARRIER, 50)	-- ensure radius is big enough!
```

```lua
-- to check for new minute
lastMinute = -1

function spawnCarriersPlayer1()
    currentMinute = Game.Time()
    if lastMinute ~= currentMinute then
        lastMinute = currentMinute
        local numAdded = SU.Settlers.AddSettlersIfNeeded(592, 510, 1, Settlers.CARRIER, 50)
        if numAdded == -1 then
            -- player dead or doesn't own this spot anymore -> stop spawning
            unrequest_event(ticking, Events.FIVE_TICKS)
        end
    end
end


function new_game()
    SU.Game.AddBeds(1, 2000)    -- add beds just once, not with every function call!
    request_event(spawnCarriersPlayer1, Events.FIVE_TICKS)
end

function register_functions()
    reg_func(spawnCarriersPlayer1)
end
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.settlers-united.com/s4-lua-api-de/su-library-functions/su.settlers/su.settlers.addsettlersifneeded.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.