Zum Hauptinhalt springen

Lua-Scripting: Fehlerbehebung

Diese Seite behandelt häufige Probleme, die beim Schreiben oder Debuggen von FreeMinecraftModels-Prop-Skripten auftreten können, sowie Tipps zur Arbeit mit dem System der verzögerten Konfigurationsgenerierung. Funktionierende Beispiele finden Sie unter Beispiele & Muster. Wenn Sie gerade erst anfangen, lesen Sie Erste Schritte.

Häufige Probleme​

1. Konfigurationsdatei wird nicht geladen / Skript nicht zugewiesen​

Symptom: Das Prop erscheint, reagiert aber nicht auf Klicks oder irgendwelche Hooks.

Ursachen und Lösungen:

  • Es existiert noch keine .yml-Konfigurationsdatei. FMM generiert die Konfiguration verzögert beim ersten Spawn des Props. Beim ersten Spawn eines Modells erstellt FMM die .yml-Konfiguration asynchron mit Standardwerten (aktiviert, keine Skripte). Sie müssen die generierte Konfiguration bearbeiten, um Ihre Skript-Dateinamen hinzuzufügen, und dann das Prop erneut spawnen.

  • Die Konfiguration enthält isEnabled: false. Öffnen Sie die .yml-Datei neben der Modelldatei und setzen Sie isEnabled: true.

  • Die scripts:-Liste ist leer. Fügen Sie Ihre Skript-Dateinamen hinzu:

    isEnabled: true
    scripts:
      - my_script.lua

  • Der .yml-Dateiname stimmt nicht mit dem Modelldateinamen überein. Die Konfiguration muss denselben Basisnamen wie die Modelldatei haben. Zum Beispiel benötigt torch_01.fmmodel eine torch_01.yml im selben Verzeichnis.

2. Skriptdatei nicht gefunden​

Symptom: Die Konsole zeigt: [FMM Scripts] Script 'my_script.lua' not found in scripts/ folder

Ursachen und Lösungen:

  • Falsches Verzeichnis. Skriptdateien müssen sich in plugins/FreeMinecraftModels/scripts/ befinden, nicht neben der Modelldatei.

  • Dateiname stimmt nicht überein. Der Name in der .yml-Konfiguration muss exakt mit dem Dateinamen im scripts/-Ordner übereinstimmen, einschließlich Groß-/Kleinschreibung und der .lua-Erweiterung.

  • Datei nicht vorhanden. Überprüfen Sie, ob die .lua-Datei tatsächlich im scripts/-Ordner existiert.

3. Skript wird überhaupt nicht geladen​

Symptom: Kein Konsolenfehler, aber keine Hooks werden ausgelöst.

Überprüfen Sie die Serverkonsole auf Lua-Syntaxfehler beim Start. Die häufigsten Ursachen sind:

  • Fehlendes end zum Schließen einer Funktion oder eines if-Blocks
  • Nicht übereinstimmende Klammern
  • Fehlende Kommas zwischen Hook-Definitionen in der zurückgegebenen Tabelle
  • Datei endet nicht mit .lua

Wenn ein Lua-Fehler vorliegt, gibt die Konsole einen [Lua]-Fehlerblock mit Dateiname, Zeilennummer und einer Beschreibung aus.

4. Hook wird nie ausgelöst​

Symptom: Das Skript wird geladen (Sie sehen die Meldung [FMM Scripts] Bound script), aber ein bestimmter Hook wird nie ausgelöst.

Überprüfen Sie, ob der Hook-Name genau so geschrieben ist, wie in der Hook-Referenz aufgeführt. Häufige Fehler:

Falscher NameKorrekter Name
on_clickon_right_click oder on_left_click
on_interacton_right_click
on_hiton_left_click
on_tickon_game_tick
on_removeon_destroy
on_arrow_hiton_projectile_hit

Überprüfen Sie außerdem, ob das Prop tatsächlich eine Armor-Stand-Entity besitzt. Manche Prop-Konfigurationen erzeugen möglicherweise keine klickbare Entity.

5. Zeitüberschreitung / Ausführungsbudget überschritten​

Symptom: Die Konsole zeigt eine Meldung wie:

[Lua] my_script.lua took 73ms in 'on_game_tick' (limit: 50ms) -- script disabled to prevent lag.

Das Skript hat in einem einzelnen Hook-Aufruf zu viel Arbeit verrichtet. Häufige Ursachen:

  • Iteration über zu viele Entities in on_game_tick
  • Erzeugung zu vieler Partikel pro Tick
  • Ausführung aufwendiger Schleifen ohne Verteilung der Arbeit über mehrere Ticks

Lösung: Verschieben Sie aufwendige Arbeit hinter einen zustandsbasierten Cooldown oder verwenden Sie scheduler:run_repeating() mit einem angemessenen Intervall anstelle von on_game_tick.

6. context.event ist nil in einem Click-Hook​

Dies sollte normalerweise bei on_left_click und on_right_click nicht vorkommen, aber schützen Sie sich immer mit:

if context.event then
  context.event.cancel()
end

Innerhalb von Scheduler-Callbacks ist context.event immer nil -- dies ist erwartetes Verhalten. Event-Modifikation ist nur innerhalb des Event-Hooks selbst möglich.

7. Animation wird nicht abgespielt​

Symptom: play_animation() gibt false zurück, oder es passiert nichts Sichtbares.

Ursachen und Lösungen:

  • Falscher Animationsname. Der Name muss exakt mit dem übereinstimmen, was in der Modelldatei definiert ist. Überprüfen Sie Ihre .bbmodel- oder .fmmodel-Datei auf den korrekten Animationsnamen.

  • Modell hat keine Animationen. Nicht alle Modelle haben Animationen. Überprüfen Sie, ob die Modelldatei tatsächlich Animationsdaten enthält.

  • Spieler sind nicht in Ressourcenpaket-Reichweite. Die Animation ist serverseitig, aber Spieler müssen das FMM-Ressourcenpaket geladen haben, um das Modell überhaupt sehen zu können.

8. Partikel erscheinen nicht​

  • Überprüfen Sie, ob der Partikelname ein gültiger Bukkit-Particle-Enum-Wert in GROSSBUCHSTABEN ist: "FLAME", nicht "flame".
  • Überprüfen Sie, ob sich die Position in einem geladenen Chunk befindet. Wenn keine Spieler in der Nähe sind, ist der Chunk möglicherweise nicht geladen.
  • Überprüfen Sie, ob count mindestens 1 beträgt.
  • Einige Partikel (wie DUST) benötigen spezifische Zusatzdaten, die das grundlegende spawn_particle() möglicherweise nicht unterstützt. Verwenden Sie Standard-Partikel wie FLAME, HEART, HAPPY_VILLAGER, NOTE, ENCHANT usw.

9. Sound wird nicht abgespielt​

  • Überprüfen Sie, ob der Soundname eine gültige Bukkit-Sound-Enum-Konstante in GROSSBUCHSTABEN ist. Beispiel: "BLOCK_NOTE_BLOCK_HARP", nicht "block.note_block.harp".
  • Überprüfen Sie, ob die Positionskoordinaten korrekt sind (nicht alle Null oder NaN).
  • Überprüfen Sie, ob die Lautstärke größer als 0 ist.

10. Zustand wird unerwartet zurückgesetzt​

context.state ist pro Prop-Instanz und bleibt während der Lebensdauer des Props bestehen. Wenn der Zustand zurückgesetzt zu werden scheint:

  • Das Prop wurde möglicherweise entfernt und erneut gespawnt (jeder Spawn erstellt eine neue Instanz).
  • Sie lesen möglicherweise den Zustand in einem Scheduler-Callback mit der falschen Context-Variable. Verwenden Sie immer den eigenen Context-Parameter des Callbacks.

Funktionsweise der verzögerten Konfigurationsgenerierung​

Das Verständnis des Systems der verzögerten Konfiguration hilft, Verwirrung bei der Einrichtung neuer Props zu vermeiden:

  1. Erster Spawn: Wenn ein Prop gespawnt wird und keine zugehörige .yml-Datei existiert, erstellt FMM die Konfiguration asynchron. Das bedeutet, die Datei wird in einem Hintergrund-Thread geschrieben und ist nicht sofort verfügbar.

  2. Standardwerte: Die generierte Konfiguration hat isEnabled: true und eine leere scripts: []-Liste.

  3. Keine Skripte beim ersten Spawn: Da die Konfiguration erstellt wird, nachdem das Prop bereits gespawnt wurde (und keine Skripte aufgelistet sind), hat das Prop beim ersten Spawn keine Skripte zugewiesen.

  4. Bearbeiten und erneut spawnen: Nachdem FMM die Konfiguration erstellt hat, bearbeiten Sie sie, um Ihre Skript-Dateinamen hinzuzufügen. Beim nächsten Spawn des Props werden die Skripte geladen.

  5. Speicherort der Konfiguration: Die .yml-Datei wird im selben Verzeichnis wie die Modelldatei erstellt, mit demselben Basisnamen. Zum Beispiel:

    • Modell: plugins/FreeMinecraftModels/models/fountain.fmmodel
    • Konfiguration: plugins/FreeMinecraftModels/models/fountain.yml
Schneller Einrichtungsablauf
  1. Modell in models/ ablegen
  2. Skript in scripts/ ablegen
  3. Das Prop einmal spawnen (generiert die .yml)
  4. Die .yml bearbeiten und scripts: [my_script.lua] hinzufügen
  5. Das Prop erneut spawnen -- Skript ist jetzt aktiv

Fehlermeldungen lesen​

Wenn etwas in einem Lua-Prop-Skript schiefgeht, gibt die Konsole einen [Lua]-Fehlerblock aus. Diese Meldungen sagen Ihnen genau, welche Datei, welche Zeile, welcher Hook und was in verständlicher Sprache schiefgelaufen ist.

Ein typischer Fehler sieht so aus:

[Lua] Error in 'my_door.lua' at line 12 during 'on_right_click':
[Lua]   -> You tried to call a method or function that doesn't exist.
[Lua]   -> Check the method name for typos, or make sure you're using ':' (colon) for method calls, not '.' (dot).
[Lua]   -> Script has been disabled for this entity to prevent further errors.

Das System übersetzt häufige Lua-Fehler in verständliche Sprache:

Roher Lua-FehlerWas die Konsole Ihnen mitteilt
attempt to call nilSie haben versucht, eine Methode oder Funktion aufzurufen, die nicht existiert. Prüfen Sie auf Tippfehler und die Verwendung von : vs. ..
index expected, got nilSie haben versucht, auf ein Feld von etwas zuzugreifen, das nil ist. Prüfen Sie, ob es durch vorherigen Code initialisiert wurde.
attempt to indexSie haben versucht, auf eine Eigenschaft eines nil- oder ungültigen Werts zuzugreifen.
bad argumentEine Funktion hat den falschen Argumenttyp erhalten. Die Meldung zeigt den erwarteten und den tatsächlichen Typ.
TimeoutIhr Skript hat Xms in 'hook_name' benötigt (Limit: 50ms) -- Skript wurde deaktiviert, um Lag zu verhindern.
tipp

Lesen Sie immer die vollständige [Lua]-Fehlermeldung, bevor Sie in den Code eintauchen. Sie weist Sie in der Regel direkt auf die Lösung hin.

Gehen Sie nicht von undokumentierten Methoden aus​

Die FMM-Lua-API stellt einen bestimmten Satz von Methoden bereit. Gehen Sie nicht davon aus, dass Kurznamen oder alternative Bezeichnungen existieren. Häufige Fehler:

  • context.prop:get_location() -- existiert nicht. Verwenden Sie context.prop.current_location (ein Feld, keine Methode).
  • context.prop:set_animation("open") -- existiert nicht. Verwenden Sie context.prop:play_animation("open", true, true).
  • context.event:setCancelled(true) -- existiert nicht. Verwenden Sie context.event.cancel().
  • context.cooldowns:check_local(...) -- existiert nicht in FMM. Verwenden Sie context.state mit scheduler:run_later() für Cooldowns.
  • context.player -- existiert nicht in FMM-Prop-Skripten. Verwenden Sie context.world:get_nearby_players(), um Spieler in der Nähe des Props zu finden.
  • context.boss -- existiert nicht. Das gehört zu EliteMobs. Verwenden Sie context.prop in FMM.

Im Zweifelsfall konsultieren Sie die Prop-API-Seite. Wenn es dort nicht dokumentiert ist, existiert es nicht.

Debug-Tipps​

1. Verwenden Sie context.log:info() großzügig​

Fügen Sie beim Debuggen an jeder Stelle Log-Meldungen hinzu:

on_right_click = function(context)
  context.log:info("Right click received!")
  context.log:info("Event present: " .. tostring(context.event ~= nil))
  context.log:info("State is_open: " .. tostring(context.state.is_open))
end

2. Überprüfen Sie die Konsole beim Start​

FMM protokolliert [FMM Scripts] Bound script 'X' to prop 'Y' für jede erfolgreiche Bindung. Wenn Sie diese Meldung nicht sehen, wurde die Konfiguration oder das Skript nicht geladen.

3. Überprüfen Sie den Modelldateipfad​

Die .yml-Konfiguration muss eine Nachbardatei der Modelldatei sein (gleiches Verzeichnis, gleicher Basisname). Überprüfen Sie dies anhand von:

  • Modelldateipfad: plugins/FreeMinecraftModels/models/my_model.fmmodel
  • Konfigurationsdateipfad: plugins/FreeMinecraftModels/models/my_model.yml

4. Testen Sie Hooks einzeln​

Wenn Sie ein komplexes Skript erstellen, testen Sie zunächst jeden Hook einzeln. Fügen Sie jeweils einen Hook hinzu und überprüfen Sie, ob er ausgelöst wird, bevor Sie zum nächsten übergehen.

5. Prüfen Sie auf Tippfehler in Hook-Namen​

Der häufigste Grund, warum ein Hook nicht ausgelöst wird, ist ein falsch geschriebener Hook-Name. Das Skript wird ohne Fehler geladen, aber die falsch geschriebene Hook-Funktion wird bei der Validierung abgelehnt.

Lernpfad für Einsteiger​

Wenn Sie dieses System von Grund auf lernen möchten, funktioniert dieser Lernpfad gut:

  1. Schreiben Sie eine Datei mit nur api_version = 1 und on_spawn, das eine Nachricht protokolliert.
  2. Fügen Sie das Skript einer Prop-Konfiguration hinzu und überprüfen Sie, ob die Log-Nachricht erscheint.
  3. Fügen Sie on_right_click hinzu und protokollieren Sie, wenn das Prop angeklickt wird.
  4. Fügen Sie on_left_click mit context.event.cancel() für Unverwundbarkeit hinzu.
  5. Spielen Sie eine Animation bei Rechtsklick ab.
  6. Fügen Sie einen Sound bei Rechtsklick hinzu.
  7. Fügen Sie Zustand und Umschaltverhalten hinzu.
  8. Fügen Sie eine Zonenüberwachung zur Näherungserkennung hinzu.
  9. Gehen Sie erst dann zu komplexen Multi-Hook-Skripten mit Schedulern über.

Jeder Schritt baut auf dem vorherigen auf, und Sie können in jedem Stadium testen.

Nächste Schritte​

  • Erste Schritte -- Dateistruktur, Hooks, Walkthrough zum ersten Skript, Kopiervorlagen
  • Prop-API -- vollständige API-Referenz
  • Beispiele & Muster -- vollständige funktionierende Skripte zum Studieren und Anpassen