Zum Hauptinhalt springen

Lua-Scripting: Verhaltensprogramme

webapp_banner.jpg

Ein Verhaltensprogramm ersetzt die native KI eines Mobs durch Lua-Verhalten, die entscheiden, wohin er sich bewegt, wohin er schaut, welche Entität er anvisiert und wann er angreift. EliteMobs führt diese Programme über die Mind-Laufzeit von MagmaCore auf dem nativen Brain-System von Minecraft aus.

Verhaltensprogramme sind keine Lua-Powers. Eine Lua-Power reagiert auf Boss-Ereignisse wie on_boss_damaged_by_player; ein Verhaltensprogramm läuft jeden Tick und besitzt die Bewegungssteuerung des Mobs. Ein Boss kann beides verwenden: Ein Verhalten kann die Powers des Bosses über on_mind_action bitten, eine Aktion auszuführen.

FreeMinecraftModels-Haustierverhalten sind ai.module-Dateien im selben Format und folgen denselben Regeln. Die haustierspezifischen Teile, einschließlich der Kontextfelder c.pet und c.settings, stehen unter Haustier-Verhaltensmodule. FreeMinecraftModels-Mob-Verhalten, die einen Mob übernehmen, den das Plugin nicht gespawnt hat, sind wieder dieselbe Art Datei, mit c.overlay und c.settings.

Verfügbarkeit nach Version

FreeMinecraftModels-Mob-Verhalten erfordern die FreeMinecraftModels-Version nach 2.15.0.

Ein Programm auswählen

Setze behavior in einer Custom-Boss-Datei, wie unter Bosse erstellen beschrieben, oder in der Mob-Eigenschaftsdatei des Entitätstyps. behavior: native behält die Vanilla-KI bei. Unterstützt die Serverversion kein natives Mind, protokolliert EliteMobs beim Start Native Mind interface is unavailable on this Minecraft version.. Ein Custom Boss, der ein Programm auswählt, spawnt dann nicht und protokolliert Cannot spawn <boss file>: .... Ein Boss, dessen behavior ein fehlendes oder ungültiges Programm nennt, scheitert auf jeder Version auf dieselbe Weise.


Dateien​

Verhaltensdateien liegen in plugins/EliteMobs/behaviors/. EliteMobs schreibt diese mitgelieferten Dateien, wenn sie fehlen:

plugins/
EliteMobs/
behaviors/
basic_melee.lua
modules/
target.lua
pursuit.lua
melee.lua
wander.lua
  • Eine .lua-Datei in einem beliebigen Ordner namens modules ist ein Modul. Jede andere .lua-Datei ist ein Programm.
  • Ein Boss verweist auf ein Programm über dessen Pfad relativ zu behaviors/, zum Beispiel basic_melee.lua oder guards/patrol_guard.lua.
  • EliteMobs lädt Verhaltensdateien, wenn sein Mind-Dienst startet. Eine Datei, die die Prüfung nicht besteht, wird übersprungen, und die Konsole protokolliert Could not load behavior <file> oder Could not load behavior module <file> mit dem Grund.
  • Programm- und Modul-IDs verwenden den Namespace elitemobs, etwa elitemobs:behavior/basic_melee. IDs bestehen aus Kleinbuchstaben und dürfen a-z, 0-9, ., _ und - enthalten, nach dem Doppelpunkt außerdem /. Zwei Programme können sich keine ID teilen, und jede Modul-ID sollte von genau einer Datei deklariert werden.
  • Ein Namespace enthält höchstens 256 Module. Ein Modul kann höchstens 32 Abhängigkeiten auflisten, ein Programm kann höchstens 64 Module auflösen, und jede Quelldatei ist auf 1.000.000 Zeichen begrenzt.

Sandbox und Laden​

Es gelten dieselben Sandbox-Regeln wie für andere Lua-Skripte. Siehe die Lua-Sandbox. Verhaltensdateien unterscheiden sich in zwei Punkten:

  • coroutine ist nicht verfügbar.
  • xpcall ruft seinen Message-Handler nie auf. Es gibt false und die reine Fehlermeldung zurück, verwende also pcall.

Jede Datei wird beim Laden einmal kompiliert, nicht für jeden Mob, und ihr Top-Level-Code läuft dabei einmal zur Prüfung. Jeder Mob, der ein Programm ausführt, erhält seine eigene Lua-Umgebung und führt den Top-Level-Code des Programms und seiner Module erneut aus, sodass dateilokale Variablen nicht zwischen Mobs geteilt werden. Eine globale Variable, die eine Datei setzt, ist nur für diese Datei sichtbar. Jeder Durchlauf muss dieselbe id, dieselbe revision und dieselben modules bzw. dependencies zurückgeben.

Der Top-Level-Code eines Programms und aller seiner Module teilt sich ein Kontingent von 250.000 Lua-Anweisungen und 50 Millisekunden CPU-Zeit. Läuft beim Start des Programms bereits ein anderer Lua-Aufruf, zum Beispiel ein Skript, das den Mob spawnt, nutzt der Top-Level-Code stattdessen das verbleibende Kontingent dieses Aufrufs. Beschränke den Top-Level-Code auf Definitionen und Konstanten.


Programmdatei​

Eine Programmdatei gibt ai.program { ... } zurück:

return ai.program {
id = 'elitemobs:behavior/basic_melee', revision = 1,
modules = {
'elitemobs:behavior/target', 'elitemobs:behavior/pursuit',
'elitemobs:behavior/melee', 'elitemobs:behavior/wander'
},
budget = {
callback_micros = 2000, entity_micros = 4000, server_micros = 5000,
max_callbacks = 20, max_instructions = 12000, max_action_requests = 2
}
}
FeldTypHinweise
idstringErforderlich. ID mit Namespace, elitemobs:... für Dateien in behaviors/. Sie darf nicht die ID eines der Module des Programms sein.
revisionpositive GanzzahlErforderlich.
modulesArray aus StringsOptional. Modul-IDs, deren Speicherwerte, Sensoren und Verhalten in das Programm aufgenommen werden. Abhängigkeiten werden vor den Modulen geladen, die sie benötigen. Duplikate und zyklische Abhängigkeiten werden abgelehnt.
memories, sensors, behaviorsTabellenOptional. Ein Programm kann eigene deklarieren, im selben Format wie ein Modul.
budgetTabelleOptionale weiche Planungsgrenzen. Siehe Budgets.
runawayTabelleOptionale harte Grenzen pro Callback. Siehe Budgets.

Moduldatei​

Eine Moduldatei gibt ai.module { ... } zurück und bündelt wiederverwendbare Speicherwerte, Sensoren und Verhalten:

FeldTypHinweise
idstringErforderlich. Modul-ID mit Namespace.
revisionpositive GanzzahlErforderlich.
dependenciesArray aus StringsOptional. Andere Modul-IDs, die dieses Modul benötigt.
memoriesTabelleOptional. Siehe Speicherwerte.
sensorsArrayOptional. Einträge vom Typ ai.sensor { ... }.
behaviorsArrayOptional. Einträge vom Typ ai.behavior { ... }.
settingsTabelleOptional. Benannte Standardwerte, die ein Host-Plugin pro Kreatur überschreiben kann. Siehe Moduleinstellungen.

sensors, behaviors, modules und dependencies müssen einfache Arrays ohne Lücken oder benannte Schlüssel sein. Namen von Sensoren, Verhalten und Speicherwerten müssen über alle Module eines Programms hinweg eindeutig sein.

Moduleinstellungen​

settings deklariert die einstellbaren Werte eines Moduls und ihre Standardwerte:

settings = {
radius = 8,
glow = true,
mode = 'circle',
foods = { 'minecraft:apple', 'minecraft:carrot' }
}
WertBeispiel
endliche Zahlradius = 8
true oder falseglow = true
Textmode = 'circle'
Liste aus Textfoods = { 'minecraft:apple' }

Jeder Schlüssel muss ein Name sein. Eine Liste muss ein einfaches Array aus Text ohne Lücken oder benannte Schlüssel sein. Jeder andere Wert, etwa eine Funktion oder eine Tabelle mit benannten Werten, führt dazu, dass das Modul abgelehnt wird. Die Tabelle wird so gelesen, wie sie geschrieben ist; eine Metatable darauf wird ignoriert.

MagmaCore prüft nur die Standardwerte und übergibt sie an das Host-Plugin, das entscheidet, wie Skripte sie sehen. EliteMobs liest Moduleinstellungen nicht, daher haben sie in Dateien unter behaviors/ keine Wirkung. FreeMinecraftModels-Haustiere legen die Werte jeder Kreatur über die Standardwerte und geben den Callbacks eines Moduls dessen eigene Einstellungen als c.settings. Siehe Haustier-Verhaltensmodule. FreeMinecraftModels-Mob-Verhalten, die die FreeMinecraftModels-Version nach 2.15.0 erfordern, tun dasselbe mit den Werten, die eine Überschreibung gibt; siehe Mob-Verhalten.


Speicherwerte​

Speicherwerte (Memories) sind typisierte Werte, die Sensoren und Verhalten für einen Mob gemeinsam nutzen. Deklariere jeden mit seinem Namen:

memories = {
candidate = { type = 'uuid', persistent = false },
next_attack = 'integer'
}
TypLua-Wert
stringString
booleanBoolean
integerGanzzahl
numberZahl
uuidUUID-String
position{ world = 'world', x = 0, y = 64, z = 0 }

Ein Name ohne Doppelpunkt wird in den Namespace des Programms gelegt. persistent ist standardmäßig false; true markiert den Speicherwert für die Serialisierung mit dem gespeicherten Zustand des Minds. Lies und schreibe Speicherwerte über c.memory:get(name), c.memory:set(name, value, ttl_ticks), c.memory:forget(name) und c.memory:contains(name). Das dritte Argument von set ist optional; wird es angegeben, läuft der Wert nach so vielen Ticks ab. Ein nicht deklarierter Name löst einen Fehler aus.


Sensoren​

Ein Sensor sammelt Informationen, meist in Speicherwerte. Sensoren laufen vor den Verhalten.

ai.sensor {
id = 'elitemobs:behavior/find_target', interval = 20,
sense = function(c)
local target = c.perception:nearest_player(35)
if target then c.memory:set('candidate', target.uuid, 21)
else c.memory:forget('candidate') end
end
}
FeldTypStandardHinweise
idstringErforderlich.
intervalpositive Ganzzahl1Ticks zwischen den Durchläufen.
sensefunctionErforderlich. Erhält den Mind-Kontext.

Sensoren können c.actuator nicht verwenden; der Aufruf einer Aktuator-Methode aus einem Sensor löst einen Fehler aus.

Sensor-Timing​

Ein Sensor läuft in dem ersten Tick, in dem der Körper seines Mobs getickt wird: nach einem Spawn, dem Laden eines Chunks oder einem Programmwechsel. Danach läuft er alle interval Ticks, mit einer eigenen Phase für jeden Mob, damit nicht alle gemeinsam erzeugten Mobs im selben Tick sensieren. Der zweite Durchlauf folgt bis zu einem interval nach dem ersten. Ein Durchlauf, der übersprungen wurde, weil der Mob ein Budget erreicht hat, wird im nächsten Tick wiederholt und kehrt danach zu seiner Phase zurück.


Verhalten​

Ein Verhalten wirkt auf den Mob, solange es die von ihm deklarierten Steuerungen hält.

ai.behavior {
id = 'elitemobs:behavior/attack', priority = 10,
controls = { ai.controls.attack },
can_start = function(c) return c.perception:current_target() ~= nil end,
can_continue = function(c) return c.perception:current_target() ~= nil end,
tick = function(c)
local target = c.perception:current_target()
if target then c.actuator:attack(target) end
end
}
FeldTypStandardHinweise
idstringErforderlich.
priorityGanzzahl0Niedrigere Zahlen haben Vorrang.
controlsArraykeineSteuerungen, die dieses Verhalten belegt, solange es läuft.
probe_intervalganze Zahl1Ticks zwischen can_start-Prüfungen, solange das Verhalten gestoppt ist. Mindestens 1; Werte über 200 zählen als 200. Siehe Probe-Intervall.
can_startfunctionimmer trueMuss true oder false zurückgeben.
can_continuefunctionwie can_startMuss true oder false zurückgeben.
startfunctionkeineLäuft einmal, wenn das Verhalten startet.
tick_intervalganze Zahl1Ticks zwischen den Läufen von can_continue und tick, solange das Verhalten läuft. Mindestens 1; Werte über 200 zählen als 200. Braucht die EliteMobs-Version nach 10.9.14 oder die FreeMinecraftModels-Version nach 2.15.0.
tickfunctionErforderlich. Läuft jeden Tick, solange das Verhalten läuft, oder alle tick_interval Ticks.
stopfunctionkeinefunction(c, reason); läuft, wenn das Verhalten stoppt.

Lebenszyklus​

  1. Solange das Verhalten gestoppt ist, prüft es can_start in jedem Tick oder alle probe_interval Ticks. Gibt die Funktion true zurück und kann das Verhalten jede deklarierte Steuerung belegen, läuft start.
  2. In jedem Tick, in dem es läuft, oder alle tick_interval Ticks, und immer in dem Tick, in dem es gestartet ist, läuft zuerst can_continue. Gibt die Funktion false zurück, stoppt das Verhalten mit dem Grund completed; andernfalls läuft tick.
  3. stop(c, reason) erhält einen der Werte completed, preempted, program_replaced, entity_removed, callback_failed oder handle_closed. Das Stoppen gibt die Steuerungen des Verhaltens frei und beendet die Bewegung, das Ziel oder den Angriff, den es hielt.

Ein Lua-Fehler in can_continue, start oder tick stoppt das Verhalten mit callback_failed. Gibt can_start oder can_continue etwas anderes als einen Boolean zurück, ist das ein Fehler. Die Konsole protokolliert für jeden Fehler Mind <program> callback <callback> failed with ....

Probe-Intervall​

Standardmäßig prüft ein gestopptes Verhalten can_start in jedem Tick. Mit probe_interval = N prüft es stattdessen alle N Ticks, mit einer eigenen Phase für jeden Mob, damit eine Menge von Mobs mit demselben Verhalten oder mehrere Verhalten eines Mobs nicht alle im selben Tick prüfen. Verwende es, wenn die Startbedingung aufwendig ist oder nicht auf den Tick genau beantwortet werden muss.

  • Die erste Prüfung, nachdem der Körper zu ticken beginnt, wartet auf die Phase des Verhaltens, bis zu N - 1 Ticks.
  • Ein Verhalten startet und übernimmt Steuerungen von einem anderen Verhalten bis zu N - 1 Ticks später, als es gekonnt hätte.
  • Ein Verhalten, das stoppt, wird in seinem nächsten Phasen-Tick erneut geprüft, bis zu N Ticks später.
  • Eine Prüfung, die übersprungen wurde, weil der Mob ein Budget erreicht hat, oder ein dadurch aufgeschobener Start wird im nächsten Tick wiederholt und kehrt danach zur Phase zurück.
  • Solange das Verhalten läuft, ändert sich nichts: can_continue und tick laufen weiterhin in jedem Tick oder alle tick_interval Ticks, und stop wird nicht verzögert. Ein Verhalten ohne can_continue ruft can_start auch während des Laufs in jedem Tick auf, weil can_continue standardmäßig can_start ist.

Der Wert muss eine Zahl ohne Nachkommaanteil sein, 1 oder größer; bei jedem anderen Wert wird die Datei abgelehnt. Werte über 200 (10 Sekunden) zählen als 200.

Steuerungen​

SteuerungErlaubt
ai.controls.movec.actuator:move_to(...), c.actuator:flee(...), c.actuator:stop_moving()
ai.controls.lookc.actuator:look_at(...)
ai.controls.move und ai.controls.look zusammenc.actuator:steer_flight(...)
ai.controls.jumpc.actuator:jump()
ai.controls.targetc.actuator:set_target(...), c.actuator:clear_target()
ai.controls.attackc.actuator:attack(...), c.actuator:shoot(...)
ai.controls.actionc.actions:request(...)
ai.controls.use_itemReserviert; der Lua-Aktuator hat keine Item-Methode.

Jede Steuerung gehört jeweils genau einem laufenden Verhalten. Ein Verhalten mit einer niedrigeren priority-Zahl nimmt einem Verhalten mit einer höheren Zahl die Steuerung ab; dieses stoppt dann mit dem Grund preempted. Eine Steuerung, die ein Verhalten mit einer niedrigeren Zahl hält, kann es nicht übernehmen. Bei gleicher Priorität erhält das Verhalten die Steuerung, dessen id alphabetisch zuerst kommt. Der Aufruf einer Aktuator-Methode ohne die zugehörige Steuerung löst einen Fehler aus. c.actuator:stop_all() stoppt nur, was das Verhalten hält.

In den mitgelieferten Modulen verwendet die Zielauswahl die Priorität 5, Nahkampfangriffe 10, die Verfolgung 20 und das ziellose Umherwandern 50. Die Verfolgung übernimmt die Bewegung vom Umherwandern also, sobald ein Ziel existiert.

Fliehen, schießen und den Schaden festlegen​

Verfügbarkeit nach Version

Diese drei Aufrufe brauchen die EliteMobs-Version nach 10.9.14.

  • c.actuator:flee(location, speed) plant einen Pfad von etwa zehn Blöcken, der von der Location wegführt, und folgt ihm. Er gibt false zurück, wenn der Körper keine Pfade planen kann, keinen so langen Ausweg findet oder ein anderes System seine Bewegung steuert. Die Planung probiert mehrere Auswege, rufe ihn also alle paar Ticks auf; dazwischen wird dem Pfad gefolgt.
  • c.actuator:shoot(target) führt den Fernangriff der eigenen Art des Körpers aus: den Pfeil eines Skeletts, den Trank einer Hexe oder die Armbrust eines Plünderers, die zuerst geladen wird, wenn sie leer ist. Er gibt false für eine Art zurück, die keinen hat.
  • c.actuator:attack(target, damage) schlägt zu und richtet so viel Schaden an, dem Körper zugerechnet, statt des eigenen Angriffsschadens des Körpers.

Flug steuern​

c.actuator:steer_flight(x, y, z) bewegt einen fliegenden Körper nur für den aktuellen Tick mit dieser Geschwindigkeit in Blöcken pro Tick. Rufe es in jedem Tick auf, in dem der Mob weiterfliegen soll; in einem Tick ohne Aufruf bewegt sich der Körper wieder über seine normale Navigation. Der Aufruf bricht jeden mit move_to gestarteten Pfad ab, kollidiert mit Blöcken und dreht den Körper um höchstens 8 Grad pro Tick in seine horizontale Bewegungsrichtung. Eine Geschwindigkeit von mehr als 4 Blöcken pro Tick (80 Blöcke pro Sekunde) wird in derselben Richtung auf 4 herunterskaliert.

Das Verhalten muss sowohl ai.controls.move als auch ai.controls.look halten. Eine fehlende Steuerung oder ein Wert, der keine endliche Zahl ist, löst einen Fehler aus. Der Aufruf gibt false zurück und tut nichts, wenn der Körper nicht fliegen kann oder ein anderes System seine Bewegung steuert, andernfalls gibt er true zurück. EliteMobs gibt fliegenden Mob-Typen wie Fledermäusen, Lohen, Ghasts, Phantomen und Plagegeistern einen fliegenden Körper.

Boss-Aktionen anfordern​

Ein Verhalten, das ai.controls.action hält, kann c.actions:request(identifier, payload) aufrufen. EliteMobs sendet die Anfrage über on_mind_action an die Lua-Powers des Bosses. Die Kennung muss ein kleingeschriebener Schlüssel mit Namespace und höchstens 128 Zeichen sein, etwa 'elitemobs:slam'. Die Nutzdaten enthalten höchstens 16 Einträge mit kleingeschriebenen Schlüsseln von höchstens 64 Zeichen, und String-Werte sind auf 256 Zeichen begrenzt; eine ungültige Kennung oder ungültige Nutzdaten lösen einen Fehler aus. Der Aufruf gibt accepted, deferred oder rejected zurück; Anfragen, die in einem Tick über max_action_requests des Programms hinausgehen, geben deferred zurück. Das Format der Nutzdaten steht unter Mind-Aktionskontext.


Budgets​

budget legt weiche Planungsgrenzen fest. Erreicht ein Mob in einem Tick eine davon, überspringt die Mind-Laufzeit die restlichen Callbacks dieses Mobs bis zum nächsten Tick. Ein bereits laufender Callback wird immer zu Ende ausgeführt. Ein übersprungener Sensor-Durchlauf oder eine übersprungene can_start-Prüfung wird im nächsten Tick wiederholt.

SchlüsselStandardHinweise
callback_micros2000Ein Callback, der länger läuft, beendet die Callbacks des Mobs für diesen Tick.
entity_micros4000Gesamte Callback-Zeit pro Mob und Tick.
server_micros20000Die Callbacks des Mobs stoppen für diesen Tick, sobald alle Mind-Programme zusammen so viel Zeit verbraucht haben.
max_callbacks128Callbacks pro Mob und Tick.
max_action_requests8Aktionsanfragen pro Mob und Tick; höchstens 64.

Alle Werte müssen positiv sein, und callback_micros darf entity_micros nicht überschreiten, das wiederum server_micros nicht überschreiten darf.

runaway legt harte Grenzen fest, die einen einzelnen Callback unterbrechen:

SchlüsselStandardMaximumHinweise
cpu_micros5000050000CPU-Zeit des Threads pro Callback.
max_instructions50000250000Lua-Anweisungen pro Callback.

budget akzeptiert auch max_instructions, wie im mitgelieferten basic_melee.lua. Deklariere den Wert in budget oder in runaway, nicht in beiden. Beide Grenzen müssen positiv sein. Ein größerer Wert wird trotzdem geladen, aber ohne Warnung auf das Maximum gesenkt.

Die Grenzen stoppen einen Callback, während er läuft, sodass eine Endlosschleife fehlschlägt, statt den Server zu blockieren. Anweisungen werden beim Ausführen gezählt; die CPU-Zeit wird alle 1.024 Anweisungen und bei der Rückkehr des Callbacks geprüft. Kann der Server die CPU-Zeit des Threads nicht messen, begrenzt cpu_micros die verstrichene Zeit auf das Fünffache seines Wertes. Ein Callback, der eine Runaway-Grenze überschreitet, schlägt wie jeder andere fehlerhafte Callback fehl, und die Konsolenzeile lautet failed with RUNAWAY_LIMIT_EXCEEDED.


Nächste Schritte​