Lua-Skripting: Erste Schritte

Diese Seite zeigt dir, wie du dein erstes Lua-Skript für ein FreeMinecraftModels-Prop oder ein benutzerdefiniertes Item schreibst, von einer leeren Datei bis hin zu einem funktionierenden interaktiven Skript. Am Ende wirst du Hooks, Context, die Prop- und Item-APIs und die allgemeine Struktur jeder Skriptdatei verstehen.

Sobald du dich mit den Grundlagen wohlfühlst, fahre mit den Begleitseiten fort:

Prop- & Item-API -- die context.prop-, context.item-, context.event-, context.world- und andere Context-APIs
Beispiele & Muster -- vollständige funktionierende Skripte für Props und Items, die du studieren und anpassen kannst
Fehlerbehebung -- häufige Fehler, Debugging-Tipps und die QC-Checkliste

Experimentelle Funktion

Lua-Prop- und -Item-Skripte sind derzeit experimentell. Hook-Namen, Hilfsmethoden und Verhalten können sich noch ändern, während sich FreeMinecraftModels weiterentwickelt. Teste daher sorgfältig, bevor du sie auf einem Produktionsserver einsetzt.

Beziehung zu EliteMobs Lua

FreeMinecraftModels verwendet die MagmaCore-Lua-Laufzeit. Wenn du bereits Lua-Powers für EliteMobs schreibst, werden dir die Kernkonzepte -- Skriptdateien, die eine Tabelle zurückgeben, api_version, Hooks, context, State, Cooldowns, Scheduling und die Sandbox -- vertraut vorkommen. Die genauen Hooks und Context-Methodennamen hängen weiterhin vom Plugin ab:

EliteMobs-Skripte laufen auf Bossen und haben Hooks wie on_boss_damaged_by_player, on_enter_combat usw.
FMM-Prop-Skripte laufen auf Props und haben Hooks wie on_right_click, on_left_click, on_zone_enter usw.
FMM-Item-Skripte laufen auf benutzerdefinierten Items und haben Hooks wie on_equip, on_attack_entity, on_consume, on_game_tick usw.

Die hier dokumentierten APIs context.world, context.zones, context.scheduler, context.state und context.log sind die FreeMinecraftModels-/MagmaCore-Varianten. EliteMobs-NPC-Skripte verwenden dieselben generischen MagmaCore-Tabellen plus context.npc; EliteMobs-Boss-Powers verwenden für mehrere Tabellen boss-spezifische Varianten. Diese Seite behandelt, was für FMM-Props und -Items spezifisch ist.

Was Prop-Skripte sind

Prop-Skripte sind eigenständige .lua-Dateien, die im Ordner plugins/FreeMinecraftModels/scripts/ liegen. Sie werden von einer YAML-Konfigurationsdatei referenziert, die neben der Modelldatei liegt, und sie laufen, sobald der Prop in die Welt gespawnt wird.

Wofür Prop-Skripte gut sind

Prop-Skripte eignen sich hervorragend, wenn du Folgendes benötigst:

Interaktive Props, die auf Spielerklicks reagieren (Türen, Hebel, Knöpfe)
Unverwundbare dekorative Props, die von Spielern nicht zerstört werden können
Näherungsauslöser, die erkennen, wenn Spieler einen Bereich betreten oder verlassen
Animierte Props, die Animationen bei Interaktion oder nach einem Timer abspielen
Sound-emittierende Props, die Sounds abspielen, wenn sie angeklickt oder angenähert werden
Jedes Prop-Verhalten, das Logik jenseits statischer Dekoration erfordert

Wenn dein Prop rein dekorativ ist und keine Interaktion benötigt, brauchst du kein Skript.

Was Item-Skripte sind

Item-Skripte verwenden dasselbe .lua-Dateiformat und denselben scripts/-Ordner wie Prop-Skripte. Der Unterschied ist, dass sie an benutzerdefinierte Items gebunden sind -- Modelle, bei denen in der YML-Konfigurationsdatei das Feld material: gesetzt ist. Während Prop-Skripte laufen, sobald eine Prop-Entität in der Welt gespawnt wird, laufen Item-Skripte, sobald ein Spieler das benutzerdefinierte Item ausrüstet (Haupthand, Nebenhand oder Rüstungsslot), und enden, wenn das Item abgelegt wird.

Wie Item-Skripte funktionieren

Aktivierung: Eine Skriptinstanz wird erzeugt, wenn ein Spieler ein benutzerdefiniertes FMM-Item ausrüstet. Skripte gelten pro Spieler und pro Item-Typ -- eine ScriptInstance je Paar (Spieler, itemId).
Deaktivierung: Die Skriptinstanz wird zerstört, wenn das Item abgelegt wird (aus dem aktiven Slot verschoben, fallengelassen, oder der Spieler trennt die Verbindung).
Item-Identifikation: Benutzerdefinierte Items werden über den PDC-Schlüssel (PersistentDataContainer) fmm_item_id identifiziert, der sich vom model_id des Props unterscheidet. Um ein korrekt getaggtes Item zu erhalten, verwende /fmm giveitem <id> oder das Admin-Menü.
Context: Item-Hooks erhalten context mit context.player, context.item, context.world, context.state, context.scheduler, context.log und (wo zutreffend) context.event.

Wofür Item-Skripte gut sind

Item-Skripte eignen sich hervorragend, wenn du Folgendes benötigst:

Benutzerdefinierte Waffen mit besonderen Fähigkeiten (Frostschwerter, Zauberstäbe)
Werkzeuge mit einzigartigen Rechtsklick- oder Shift-Klick-Aktionen
Verbrauchsgegenstände mit eigenen Effekten
Rüstung mit passiven Effekten beim Tragen
Items, die ihre Verwendung verfolgen oder begrenzte Haltbarkeit haben
Jedes Verhalten gehaltener Items jenseits der Vanilla-Mechanik

Für wen diese Seite ist

Diese Seite ist für drei Arten von Lesern geschrieben:

Jemand, der bereits EliteMobs-Lua-Skripting kennt und die FMM-spezifischen Hooks und APIs lernen möchte
Jemand, der neu im Lua-Skripting ist und eine vollständige, exakte Namensreferenz für Props benötigt
Jemand, der KI zum Erstellen von Prop-Skripten verwendet und genügend Details braucht, um zu erkennen, wenn die KI etwas Falsches erfunden hat

Du musst kein vollständiger Lua-Entwickler werden, bevor du nützliche Prop-Skripte schreiben kannst. Für die meisten praktischen Prop-Skripte brauchst du nur:

Wie man einen gültigen Hook in der zurückgegebenen Tabelle platziert
Wie man Werte aus context liest
Wie man frühzeitig mit if ... then return end abbricht
Wie man ein paar Hilfsmethoden exakt aufruft

Kleiner Lua-Einstieg

Du musst kein Lua-Experte sein, um FMM-Skripte zu schreiben. Die meisten Skripte verwenden nur eine Handvoll Konzepte: Variablen (local x = 5), Funktionen (function foo() end), if-Abfragen (if x then ... end), Tabellen ({key = value}) und nil (Luas Wert für „nichts"). Die Syntax ist schlank — keine Semikolons, keine geschweiften Klammern, nur end, um Blöcke zu schließen.

Für eine vollständige Einführung mit Beispielen siehe die MagmaCore Lua-Skript-Engine — Kleiner Lua-Einstieg. Dieser Einstieg wird von allen Nightbreak-Plugins geteilt, du lernst ihn also einmal und kannst ihn überall anwenden.

Wo die Dateien liegen

Skriptdateien

Platziere .lua-Dateien im zentralen Skript-Ordner:

plugins/
  FreeMinecraftModels/
    scripts/
      invulnerable.lua
      interactive_door.lua
      proximity_sound.lua

FMM erkennt alle .lua-Dateien in plugins/FreeMinecraftModels/scripts/ beim Start.

Gib in der scripts:-Liste eines Modells die Endung .lua der Klarheit halber an. FMM akzeptiert auch Einträge ohne Endung und hängt intern .lua an. Die Datei auf der Festplatte muss trotzdem auf .lua enden, und Namen bleiben groß-/kleinschreibungsabhängig.

Modelldateien und Konfigurationsdateien

Jede Modelldatei kann eine begleitende .yml-Konfigurationsdatei im selben Verzeichnis haben:

plugins/
  FreeMinecraftModels/
    models/
      torch_01.fmmodel
      torch_01.yml          <-- Skript-Konfiguration für torch_01
    scripts/
      invulnerable.lua      <-- referenziert von torch_01.yml

Die .yml-Konfiguration ist das, was ein Modell mit seinen Skripten verbindet.

Konfigurationsdatei-Format

Die YAML-Konfigurationsdatei, die neben einer Modelldatei liegt, hat folgende Felder:

isEnabled: true
voxelize: false
solidify: false
scripts:
  - invulnerable.lua

Für benutzerdefinierte Items (Modelle, die Spieler halten oder ausrüsten können) setzt du zusätzlich das Feld material und optional name, lore und enchantments:

isEnabled: true
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in eternal ice"
  - "&7Slows enemies on hit"
enchantments:
  - "SHARPNESS,5"
  - "UNBREAKING,3"
scripts:
  - frost_sword.lua

Feld	Typ	Standard	Hinweise
`isEnabled`	boolean	`true`	Ob Skripte für diesen Prop/dieses Item aktiv sind
`scripts`	Liste von Strings	`[]`	Dateinamen von `.lua`-Skripten im `scripts/`-Ordner
`voxelize`	boolean	`false`	Platzierung an 90-Grad-Drehung und Blockraster-Ausrichtung einrasten
`solidify`	boolean	`false`	Paket-basierte Barrier-Blöcke im Grundriss des Props platzieren (erfordert `voxelize`)
`material`	string	`""`	Ein gültiger Bukkit Material-Name (z.B. `DIAMOND_SWORD`). Wenn gesetzt, wird das Modell zu einem benutzerdefinierten Item, das Spieler halten oder ausrüsten können, wodurch das Item-Scripting-System aktiviert wird
`name`	string	`""`	Anzeigename für das benutzerdefinierte Item. Unterstützt `&`-Farbcodes
`lore`	Liste von Strings	`[]`	Lore-Zeilen, die im Item-Tooltip angezeigt werden. Unterstützt `&`-Farbcodes
`enchantments`	Liste von Strings	`[]`	Verzauberungen, die auf das Item angewendet werden. Format: `"VERZAUBERUNGSNAME,STUFE"` (z.B. `"SHARPNESS,5"`)

Du kannst mehrere Skripte an denselben Prop anhängen. Jedes Skript ist seine eigene unabhängige Instanz.

Item-ID und Skript-Limit

Die Item-ID wird vom YML-Dateinamen ohne Endung abgeleitet. Zum Beispiel ergibt frost_sword.yml die Item-ID frost_sword. Dies ist die ID, die von /fmm giveitem und dem fmm_item_id PDC-Schlüssel verwendet wird.
Items binden nur ein Skript aus der scripts:-Liste. FMM prüft die Einträge der Reihe nach, verwendet das erste auflösbare Skript und ignoriert dann spätere Einträge. Anders als Items führen Props jedes auflösbare aufgelistete Skript als unabhängige Instanz aus.
Die .lua-Endung wird automatisch an Skriptdateinamen angehängt, wenn du sie weglässt, sodass frost_sword und frost_sword.lua in der scripts:-Liste gleichwertig sind.

Verzögerte Konfigurationserzeugung

Wenn ein Prop gespawnt wird und keine begleitende .yml-Datei existiert, erstellt FMM automatisch eine Standardkonfigurationsdatei mit isEnabled: true und einer leeren scripts:-Liste. Dies geschieht asynchron, sodass der Prop bei seinem ersten Spawn keine Skripte haben wird -- erst nachdem die Konfiguration erstellt wurde und du sie bearbeitest, um Skriptdateinamen hinzuzufügen.

Das bedeutet:

Platziere deine Modelldatei in models/
Spawne den Prop einmal (FMM erstellt die .yml automatisch)
Bearbeite die generierte .yml, um deine Skriptdateinamen hinzuzufügen
Spawne den Prop erneut oder lade neu (Skripte sind jetzt aktiv)

Hook-Referenz

Jede Lua-Prop-Skriptdatei gibt eine Tabelle zurück. Jeder Schlüssel in dieser Tabelle (außer api_version und priority) muss einer der unten aufgeführten Hooks sein. Die Laufzeit ruft die passende Funktion auf, wenn das entsprechende Spielereignis ausgelöst wird.

Hook	Wird ausgelöst wenn	Hinweise
`on_spawn`	Der Prop in die Welt gespawnt wird	Läuft einmal, wenn das Skript gebunden wird
`on_game_tick`	Einmal pro Server-Tick (50 ms)	Nur aktiv, wenn das Skript diesen Hook definiert
`on_destroy`	Der Prop aus der Welt entfernt wird	Aufräum-Hook
`on_left_click`	Ein Spieler den Prop links anklickt (schlägt)	`context.event` ist das Schadens-Event
`on_right_click`	Ein Spieler den Prop rechts anklickt	`context.event` ist das Interaktions-Event
`on_zone_enter`	Ein Spieler eine überwachte Zone betritt	Erfordert eine eingerichtete Zonenüberwachung
`on_zone_leave`	Ein Spieler eine überwachte Zone verlässt	Erfordert eine eingerichtete Zonenüberwachung

Reservierter Prop-Hook

Der aktuelle Skript-Validator akzeptiert on_projectile_hit für Prop-Skripte, aber die aktuelle Laufzeit leitet Projektiltreffer noch nicht an Prop-Skripte weiter. Verwende den Item-Hook on_projectile_hit für Projektilverhalten an einem geskripteten Item, oder die Bukkit-API ModeledEntityHitByProjectileEvent für plugin-seitige Projektilbehandlung an modellierten Entitäten.

Item-Hook-Referenz

Item-Skripte geben genau wie Prop-Skripte eine Tabelle zurück, mit api_version = 1 und Hook-Funktionen. Die folgenden Hooks sind für Item-Skripte verfügbar. Alle Item-Hooks erhalten context mit context.player, context.item und (wo zutreffend) context.event.

Die Hinweise-Spalte nennt die zugrunde liegende Bukkit-Event-Familie. Der Lua-Wrapper stellt keine rohen Bukkit-spezifischen Felder wie target, block, projectile oder item bereit; verwende context.player, context.event.player und Entity-/Welt-Hilfsabfragen, wenn du zusätzlichen Context benötigst.

Combat-Hooks

Hook	Wird ausgelöst wenn	Hinweise
`on_attack_entity`	Der Spieler eine Entity angreift, während er das Item hält	`context.event` ist das Schadens-Event
`on_kill_entity`	Der Spieler eine Entity tötet, während er das Item hält	`context.event` ist das Todes-Event
`on_take_damage`	Der Spieler Schaden erleidet, während das Item ausgerüstet ist	`context.event` ist das Schadens-Event
`on_shield_block`	Der Spieler Schaden mit einem Schild blockt	`context.event` ist das Schadens-Event
`on_shoot_bow`	Der Spieler einen Bogen abschießt	`context.event` ist das Bogenschuss-Event
`on_projectile_hit`	Ein vom Spieler abgeschossenes Projektil etwas trifft	`context.event` ist das Projektiltreffer-Event
`on_projectile_launch`	Der Spieler ein Projektil abfeuert	`context.event` ist das Projektilabschuss-Event

Interaction-Hooks

Hook	Wird ausgelöst wenn	Hinweise
`on_right_click`	Der Spieler rechtsklickt, während er das Item hält	`context.event` ist das Interaktions-Event
`on_left_click`	Der Spieler linksklickt, während er das Item hält	`context.event` ist das Interaktions-Event
`on_shift_right_click`	Der Spieler Umschalt+Rechtsklick ausführt, während er das Item hält	`context.event` ist das Interaktions-Event
`on_shift_left_click`	Der Spieler Umschalt+Linksklick ausführt, während er das Item hält	`context.event` ist das Interaktions-Event
`on_interact_entity`	Der Spieler eine Entity rechtsklickt, während er das Item hält	`context.event` ist das Entity-Interaktions-Event

Equipment-Hooks

Hook	Wird ausgelöst wenn	Hinweise
`on_equip`	Das Item ausgerüstet wird (in einen aktiven Slot verschoben)	Guter Ort, um State zu initialisieren
`on_unequip`	Das Item abgelegt wird (aus einem aktiven Slot verschoben)	Guter Ort zum Aufräumen
`on_swap_hands`	Der Spieler das Item zwischen Haupt- und Nebenhand tauscht	`context.event` ist das Tausch-Event
`on_drop`	Der Spieler das Item fallen lässt	`context.event` ist das Drop-Event

Utility-Hooks

Hook	Wird ausgelöst wenn	Hinweise
`on_break_block`	Der Spieler einen Block abbaut, während er das Item hält	`context.event` ist das Blockabbau-Event
`on_consume`	Der Spieler das Item konsumiert (Nahrung/Trank)	`context.event` ist das Konsum-Event
`on_item_damage`	Das Item Haltbarkeitsschaden nimmt	`context.event` ist das Item-Schadens-Event
`on_fish`	Der Spieler eine Angel verwendet	`context.event` ist das Angel-Event
`on_death`	Der Spieler stirbt, während das Item ausgerüstet ist	`context.event` ist das Todes-Event

Lifecycle-Hook

Hook	Wird ausgelöst wenn	Hinweise
`on_game_tick`	Jeden Server-Tick, während das Item ausgerüstet ist	Sparsam verwenden -- läuft 20-mal pro Sekunde

Minimaler Dateivertrag

Jedes Lua-Prop-Skript muss eine Tabelle returnen.

Erforderliche und optionale Top-Level-Felder

Feld	Erforderlich	Typ	Hinweise
`api_version`	Ja	Zahl	Muss derzeit `1` sein
`priority`	Nein	Zahl	Wird validiert, sofern vorhanden, aber FMM sortiert Skripte derzeit nicht danach. Props laufen in der Reihenfolge der `scripts:`-Liste; Items binden nur das erste gültige Skript
Unterstützte Hook-Schlüssel	Nein	Funktion	Muss einen der exakten Hook-Namen aus der Hook-Referenz verwenden

Validierungsregeln

Die Datei muss eine Tabelle zurückgeben.
api_version ist erforderlich und muss derzeit 1 sein.
priority muss numerisch sein, wenn vorhanden.
Jeder zusätzliche Top-Level-Schlüssel muss ein unterstützter Hook-Name sein.
Jeder Hook-Schlüssel muss auf eine Funktion zeigen.
Unbekannte Top-Level-Schlüssel werden abgelehnt.

Hinweis

priority ist nützlich, um Skripte über MagmaCore-basierte Laufzeiten hinweg portabel zu halten, aber die aktuelle Ausführungsreihenfolge von FreeMinecraftModels ist konfigurationsgesteuert. Setze Prop-Skripte in der scripts:-Liste des Modells in die Reihenfolge, in der sie laufen sollen.

Hilfsfunktionen und lokale Konstanten sollten oberhalb des abschließenden return leben, nicht innerhalb der zurückgegebenen Tabelle.

Dein erstes funktionierendes Prop-Skript, Schritt für Schritt

Vor Schritt 1: Konfiguration einrichten

Platziere deine Modelldatei (z.B. my_prop.fmmodel) in plugins/FreeMinecraftModels/models/
Spawne den Prop einmal, um die .yml-Konfiguration zu generieren
Erstelle deine Skriptdatei in plugins/FreeMinecraftModels/scripts/first_test.lua
Bearbeite plugins/FreeMinecraftModels/models/my_prop.yml:

isEnabled: true
scripts:
  - first_test.lua

Spawne den Prop erneut oder lade den Server neu

Schritt 1: Die Datei zum Laden bringen

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Wenn dies ohne Fehler in der Konsole geladen wird, hast du bewiesen:

Die Datei ist gültiges Lua
FMM hat sie im scripts/-Ordner gefunden
Die Konfiguration referenziert sie korrekt
Die Form der zurückgegebenen Tabelle ist korrekt

Schritt 2: Den Prop eine sichtbare Sache tun lassen

return {
  api_version = 1,

  on_spawn = function(context)
    context.log:info("Prop-Skript geladen fuer: " .. (context.prop.model_id or "unbekannt"))
  end
}

Überprüfe die Serverkonsole. Wenn du die Log-Nachricht siehst, feuert dein Hook.

Schritt 3: Auf einen Spielerklick reagieren

return {
  api_version = 1,

  on_right_click = function(context)
    context.log:info("Prop wurde rechts angeklickt!")
  end
}

Rechtsklicke den Prop im Spiel. Wenn die Konsole die Nachricht zeigt, funktioniert der Klick-Hook.

Schritt 4: Schaden abbrechen, um den Prop unverwundbar zu machen

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

Dies ist das Muster, das das mitgelieferte invulnerable.lua-Skript verwendet. Es bricht das Schadens-Event ab, damit der darunterliegende Armor Stand des Props nicht zerstört werden kann.

Schritt 5: Eine Animation bei Klick abspielen

return {
  api_version = 1,

  on_right_click = function(context)
    context.prop:play_animation("open", true, false)
  end
}

Dies spielt die "open"-Animation auf dem Prop-Modell ab, geblendet und nicht-wiederholend.

Was ist `context`?

Jede Hook-Funktion erhält ein Argument namens context. Stelle es dir wie einen Werkzeugkasten vor, den FMM dir jedes Mal übergibt, wenn etwas passiert -- er enthält alles, was du brauchst, um mit dem Prop, der Welt, Zonen und mehr zu interagieren.

Du erstellst context nicht selbst -- FMM erstellt es und übergibt es an deinen Hook. Für alle Details zu den gemeinsamen Context-APIs (context.state, context.log, context.cooldowns, context.scheduler, context.world, context.zones) siehe die Seite MagmaCore Lua-Skript-Engine.

Wichtige `context`-APIs

Hier ist eine Zusammenfassung des Verfügbaren. Für vollständige Details siehe Prop-API.

context.prop -- (Nur Prop-Skripte) Die Prop-Entität. Bietet model_id, current_location, play_animation() und stop_animation().
context.item -- (Nur Item-Skripte) Das benutzerdefinierte Item. Bietet id, material(), get_amount(), set_amount(), consume(), get_uses(), set_uses(), get_name(), set_name(), get_lore(), set_lore(), get_durability(), get_durability_percentage(), use_durability() und use_durability_percentage(). Siehe Prop- & Item-API für alle Details.
context.player -- Der Spieler bei spielergetriebenen Hooks. Item-Skripte lösen ihn über den Item-Besitzer auf; Prop-Klick-Hooks und generische Zonen-Hooks über den auslösenden Spieler. In Prop-Lebenszyklus-Hooks, geplanten Prop-Callbacks und Hooks ohne Spielerbezug ist er nil.
context.event -- Ein kleiner Wrapper um das Bukkit-Event bzw. den Spieler-Akteur, der diesen Hook ausgelöst hat. Verfügbar in Klick-, Kampf-, Interaktions- und generischen Zonen-Hooks. Bietet event.player, is_cancelled und, wenn das zugrunde liegende Bukkit-Event abbrechbar ist, cancel() / uncancel(); er stellt keine Bukkit-spezifischen Felder wie target, block, projectile oder item bereit. Ist nil in Hooks ohne Event oder Spieler-Akteur (wie on_spawn, on_game_tick und on_equip).
context.state -- Eine einfache Lua-Tabelle, die für die Lebensdauer der Skriptinstanz bestehen bleibt. Siehe context.state.
context.cooldowns -- Lokale und globale Cooldown-Helfer. Verwende context.cooldowns:check_local("key", ticks) für normale Cooldowns pro Skript. Siehe context.cooldowns.
context.log -- Konsolen-Logging. Siehe context.log.
context.scheduler -- Verzögerte und wiederholende Aufgaben. Siehe context.scheduler.
context.world -- Weltinteraktion: Partikel, Sounds, Block-Abfragen, Blitze, nahegelegene Entitäten. Siehe context.world.
context.zones -- Erstelle und überwache räumliche Zonen (Kugeln, Zylinder, Quader). Siehe context.zones.

Methodensyntax: `:` vs `.`

Eine Erklärung der Methodensyntax : vs . in Lua findest du auf der Seite MagmaCore Lua-Skript-Engine. Beide Formen werden von der FMM-API akzeptiert.

Kopier-Vorlagen

Kleinstes gültiges Prop-Skript

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Unverwundbares Prop-Template

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

Interaktives Prop-Template

return {
  api_version = 1,

  on_spawn = function(context)
    context.state.is_active = false
  end,

  on_right_click = function(context)
    context.state.is_active = not context.state.is_active

    if context.state.is_active then
      context.prop:play_animation("activate", true, true)
    else
      context.prop:stop_animation()
    end
  end
}

Kleinstes gültiges Item-Skript

return {
  api_version = 1,

  on_equip = function(context)
  end
}

Vorlage: Item mit Rechtsklick-Aktion

return {
  api_version = 1,

  on_right_click = function(context)
    if not context.cooldowns:check_local("activate", 40) then return end

    -- Your action here
    context.player:send_message("&aItem activated!")
  end
}

Größeres Datei-Layout

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("Tue etwas!")
end

return {
  api_version = 1,
  priority = 0,

  on_spawn = function(context)
    context.state.task_id = nil
  end,

  on_right_click = function(context)
    do_something(context)
  end,

  on_destroy = function(context)
    if context.state.task_id ~= nil then
      context.scheduler:cancel(context.state.task_id)
    end
  end
}

Erster echter Workflow

Wenn du ein brandneues Prop-Skript erstellst, verwende diese Reihenfolge:

Erstelle die .lua-Datei und bringe on_spawn zum Laufen.
Füge den Skriptdateinamen zur .yml-Konfiguration des Props hinzu.
Wechsle zum tatsächlichen Hook, den du verwenden möchtest (z.B. on_right_click).
Füge zuerst eine Log-Nachricht hinzu, bevor du Animationen oder Effekte hinzufügst.
Füge einen echten Effekt hinzu (Animation, Sound, Partikel).
Erst danach füge Helfer, State, Scheduler-Logik oder Zonen hinzu.

Diese Reihenfolge macht das Debugging dramatisch einfacher, weil sich immer nur eine Sache gleichzeitig ändert.

Mitgelieferte Skripte

FMM wird mit vier mitgelieferten Lua-Skripten ausgeliefert:

invulnerable.lua -- Bricht Linksklick-Schadens-Events ab und macht den Prop unzerstörbar. Dies ist das einfachste nützliche Prop-Skript.
pickupable.lua -- Ermöglicht es Spielern, einen Prop aufzuheben, indem sie ihn dreimal schlagen. Jeder Treffer spielt eine Verletzungsanimation auf dem Prop ab, und beim dritten Treffer wird der Prop entfernt und droppt sein Platzierungs-Item, damit der Spieler es aufsammeln kann.
storage_double.lua -- Verwandelt einen Prop in eine Doppeltruhe (54 Slots). Ein Rechtsklick öffnet eine dauerhafte Inventar-GUI. Spielt Öffnen-/Schließen-Animationen und -Sounds ab. Der Inhalt wird am Prop gespeichert und übersteht Server-Neustarts. Beim Zerstören wird der gesamte Inhalt fallengelassen.
storage_single.lua -- Wie storage_double, aber mit 3 Reihen (27 Slots) statt 6.

Weitere Beispiele findest du auf der Seite Beispiele & Muster.

Lua-Sandbox

Prop- und Item-Skripte laufen in derselben sandboxed LuaJ-Umgebung wie EliteMobs. Die Sandbox-Einschränkungen sind identisch. Für die vollständige Liste der entfernten Globals und verfügbaren Standardbibliotheksfunktionen siehe die Seite MagmaCore Lua-Skript-Engine.

Nächste Schritte

Prop- & Item-API -- vollständige context.prop-, context.item-, context.event-, context.world-, context.zones- und context.scheduler-Referenz
Beispiele & Muster -- vollständige funktionierende Skripte für Props und Items mit Erklärungen
Fehlerbehebung -- häufige Probleme, Debugging-Tipps und eine QC-Checkliste

Wenn du auch EliteMobs-Boss-Lua-Powers schreibst, sind dir die Sandbox, api_version, die State-Tabelle, die Cooldown-Konzepte und die hook-getriebene Struktur vertraut, aber der Boss-Context verwendet EliteMobs-spezifische Methodennamen. Siehe die EliteMobs-Lua-Dokumentation für die genauen Boss-APIs.

Was Prop-Skripte sind​

Wofür Prop-Skripte gut sind​

Was Item-Skripte sind​

Wie Item-Skripte funktionieren​

Wofür Item-Skripte gut sind​

Für wen diese Seite ist​

Kleiner Lua-Einstieg​

Wo die Dateien liegen​

Skriptdateien​

Modelldateien und Konfigurationsdateien​

Konfigurationsdatei-Format​

Verzögerte Konfigurationserzeugung​

Hook-Referenz​

Item-Hook-Referenz​

Combat-Hooks​

Interaction-Hooks​

Equipment-Hooks​

Utility-Hooks​

Lifecycle-Hook​

Minimaler Dateivertrag​

Erforderliche und optionale Top-Level-Felder​

Validierungsregeln​

Dein erstes funktionierendes Prop-Skript, Schritt für Schritt​

Vor Schritt 1: Konfiguration einrichten​

Schritt 1: Die Datei zum Laden bringen​

Schritt 2: Den Prop eine sichtbare Sache tun lassen​

Schritt 3: Auf einen Spielerklick reagieren​

Schritt 4: Schaden abbrechen, um den Prop unverwundbar zu machen​

Schritt 5: Eine Animation bei Klick abspielen​

Was ist context?​

Wichtige context-APIs​

Methodensyntax: : vs .​

Kopier-Vorlagen​

Kleinstes gültiges Prop-Skript​

Unverwundbares Prop-Template​

Interaktives Prop-Template​

Kleinstes gültiges Item-Skript​

Vorlage: Item mit Rechtsklick-Aktion​

Größeres Datei-Layout​

Erster echter Workflow​

Mitgelieferte Skripte​

Lua-Sandbox​

Nächste Schritte​