Lua-скриптинг: Устранение неполадок

Эта страница описывает типичные проблемы, с которыми вы можете столкнуться при написании или отладке скриптов пропсов FreeMinecraftModels, а также советы по работе с системой ленивой генерации конфигурации. Рабочие примеры см. в Примерах и паттернах. Если вы только начинаете, см. Начало работы.

Типичные проблемы

1. Конфиг не загружается / Скрипт не привязан

Симптом: Пропс появляется, но не реагирует на клики и никакие хуки не срабатывают.

Причины и решения:

Файл .yml конфига ещё не существует. FMM генерирует конфиг лениво при первом спавне пропса. При первом спавне модели FMM создаёт файл .yml конфигурации асинхронно со значениями по умолчанию (включён, без скриптов). Вам нужно отредактировать сгенерированный конфиг, добавить имена файлов скриптов, а затем переспавнить пропс.
В конфиге isEnabled: false. Откройте файл .yml рядом с файлом модели и установите isEnabled: true.
Список scripts: пуст. Добавьте имена файлов ваших скриптов:
```
isEnabled: true
scripts:
  - my_script.lua
```
Имя файла .yml не совпадает с именем файла модели. Конфиг должен иметь то же базовое имя, что и файл модели. Например, для torch_01.fmmodel нужен torch_01.yml в той же директории.

2. Файл скрипта не найден

Симптом: Консоль показывает: [FMM Scripts] Script 'my_script.lua' not found in scripts/ folder

Причины и решения:

Неправильная директория. Файлы скриптов должны находиться в plugins/FreeMinecraftModels/scripts/, а не рядом с файлом модели.
Несовпадение имени файла. Имя в конфиге .yml должно точно совпадать с именем файла в папке scripts/, включая регистр и расширение .lua.
Файл отсутствует. Убедитесь, что файл .lua действительно существует в папке scripts/.

3. Скрипт вообще не загружается

Симптом: Нет ошибок в консоли, но хуки не срабатывают.

Проверьте консоль сервера на наличие синтаксических ошибок Lua при запуске. Наиболее частые причины:

Отсутствие end для закрытия функции или блока if
Непарные скобки
Отсутствие запятой между определениями хуков в возвращаемой таблице
Файл не заканчивается расширением .lua

Если есть ошибка Lua, консоль выведет блок ошибки [Lua] с именем файла, номером строки и описанием.

4. Хук никогда не срабатывает

Симптом: Скрипт загружается (вы видите сообщение [FMM Scripts] Bound script), но конкретный хук не срабатывает.

Убедитесь, что имя хука написано точно так, как указано в справочнике хуков. Типичные ошибки:

Неправильное имя	Правильное имя
`on_click`	`on_right_click` или `on_left_click`
`on_interact`	`on_right_click`
`on_hit`	`on_left_click`
`on_tick`	`on_game_tick`
`on_remove`	`on_destroy`
`on_arrow_hit`	`on_projectile_hit`

Также убедитесь, что у пропса действительно есть базовая сущность стойки для брони. Некоторые конфигурации пропсов могут не создавать кликабельную сущность.

5. Таймаут / превышен бюджет выполнения

Симптом: Консоль показывает сообщение вроде:

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

Скрипт выполнял слишком много работы за один вызов хука. Типичные причины:

Перебор слишком многих сущностей в on_game_tick
Создание слишком многих частиц за тик
Выполнение ресурсоёмких циклов без распределения работы по тикам

Решение: Перенесите тяжёлую работу за кулдаун на основе состояния или используйте scheduler:run_repeating() с разумным интервалом вместо on_game_tick.

6. `context.event` равен nil в хуке клика

В нормальных условиях это не должно происходить для on_left_click и on_right_click, но всегда проверяйте:

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

Внутри обратных вызовов планировщика context.event всегда nil — это ожидаемое поведение. Модификация событий возможна только внутри самого хука события.

7. Анимация не воспроизводится

Симптом: play_animation() возвращает false, или ничего видимого не происходит.

Причины и решения:

Неправильное имя анимации. Имя должно точно совпадать с определённым в файле модели. Проверьте ваш .bbmodel или .fmmodel на правильное имя анимации.
Модель не имеет анимаций. Не все модели имеют анимации. Убедитесь, что файл модели действительно содержит данные анимации.
Игроки не в зоне действия ресурспака. Анимация серверная, но игрокам нужен загруженный ресурспак FMM, чтобы вообще видеть модель.

8. Частицы не появляются

Убедитесь, что имя частицы — валидное значение перечисления Bukkit Particle в ВЕРХНЕМ_РЕГИСТРЕ: "FLAME", а не "flame".
Убедитесь, что местоположение находится в загруженном чанке. Если поблизости нет игроков, чанк может быть выгружен.
Убедитесь, что count не менее 1.
Некоторые частицы (например, DUST) требуют специальных дополнительных данных, которые базовый spawn_particle() может не поддерживать. Используйте стандартные частицы, такие как FLAME, HEART, HAPPY_VILLAGER, NOTE, ENCHANT и др.

9. Звук не воспроизводится

Убедитесь, что имя звука — валидная константа перечисления Bukkit Sound в ВЕРХНЕМ_РЕГИСТРЕ. Пример: "BLOCK_NOTE_BLOCK_HARP", а не "block.note_block.harp".
Убедитесь, что координаты местоположения корректны (не все нули и не NaN).
Убедитесь, что громкость больше 0.

10. Состояние неожиданно сбрасывается

context.state уникален для каждого экземпляра пропса и сохраняется на протяжении его жизни. Если состояние кажется сброшенным:

Пропс мог быть удалён и переспавнен (каждый спавн создаёт новый экземпляр).
Вы можете читать состояние в обратном вызове планировщика, используя неправильную переменную context. Всегда используйте собственный параметр context обратного вызова.

Как работает ленивая генерация конфигурации

Понимание системы ленивой генерации конфигурации помогает избежать путаницы при настройке новых пропсов:

Первый спавн: Когда пропс появляется и не существует соседнего файла .yml, FMM создаёт конфиг асинхронно. Это означает, что файл записывается в фоновом потоке и не доступен немедленно.
Значения по умолчанию: Сгенерированный конфиг имеет isEnabled: true и пустой список scripts: [].
Нет скриптов при первом спавне: Поскольку конфиг создаётся после того, как пропс уже заспавнился (и не имеет перечисленных скриптов), при первом спавне у пропса не будет привязанных скриптов.
Редактирование и переспавн: После того как FMM создаст конфиг, вы редактируете его, добавляя имена файлов скриптов. При следующем спавне пропса скрипты будут загружены.
Расположение конфига: Файл .yml создаётся в той же директории, что и файл модели, с тем же базовым именем. Например:
- Модель: plugins/FreeMinecraftModels/models/fountain.fmmodel
- Конфиг: plugins/FreeMinecraftModels/models/fountain.yml

Быстрый рабочий процесс настройки

Поместите модель в models/
Поместите скрипт в scripts/
Заспавните пропс один раз (генерирует .yml)
Отредактируйте .yml, добавив scripts: [my_script.lua]
Переспавните пропс — скрипт теперь активен

Чтение сообщений об ошибках

Когда что-то идёт не так в Lua-скрипте пропса, консоль выводит блок ошибки [Lua]. Эти сообщения точно указывают какой файл, какая строка, какой хук и что пошло не так на понятном языке.

Типичная ошибка выглядит так:

[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.

Система переводит типичные ошибки Lua в понятные сообщения:

Сырая ошибка Lua	Что сообщает консоль
`attempt to call nil`	Вы попытались вызвать метод или функцию, которая не существует. Проверьте опечатки и использование `:` vs `.`.
`index expected, got nil`	Вы попытались обратиться к полю чего-то, что является nil. Проверьте, что предыдущий код его инициализировал.
`attempt to index`	Вы попытались обратиться к свойству nil или невалидного значения.
`bad argument`	Функция получила аргумент неправильного типа. Сообщение показывает ожидаемый и фактический тип.
Таймаут	Ваш скрипт занял Xмс в 'hook_name' (лимит: 50мс) — скрипт отключён для предотвращения лагов.

подсказка

Всегда читайте полное сообщение об ошибке [Lua] перед тем, как погружаться в код. Обычно оно указывает прямо на исправление.

Не предполагайте существование недокументированных методов

API Lua FMM предоставляет определённый набор методов. Не предполагайте, что существуют сокращённые или альтернативные имена. Типичные ошибки:

context.prop:get_location() — не существует. Используйте context.prop.current_location (поле, а не метод).
context.prop:set_animation("open") — не существует. Используйте context.prop:play_animation("open", true, true).
context.event:setCancelled(true) — не существует. Используйте context.event.cancel().
context.cooldowns:check_local(...) — не существует в FMM. Используйте context.state с scheduler:run_later() для кулдаунов.
context.player — не существует в скриптах пропсов FMM. Используйте context.world:get_nearby_players() для поиска игроков рядом с пропсом.
context.boss — не существует. Это из EliteMobs. Используйте context.prop в FMM.

Если сомневаетесь, проверьте страницу Prop API. Если чего-то нет в документации — этого не существует.

Советы по отладке

1. Используйте `context.log:info()` активно

Добавляйте сообщения лога на каждом шаге при отладке:

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. Проверяйте консоль при запуске

FMM логирует [FMM Scripts] Bound script 'X' to prop 'Y' для каждой успешной привязки. Если вы не видите это сообщение, конфиг или скрипт не загрузился.

3. Проверяйте путь к файлу модели

Конфиг .yml должен быть соседом файла модели (та же директория, то же базовое имя). Проверьте это:

Путь к файлу модели: plugins/FreeMinecraftModels/models/my_model.fmmodel
Путь к файлу конфига: plugins/FreeMinecraftModels/models/my_model.yml

4. Тестируйте хуки по отдельности

При создании сложного скрипта начинайте с тестирования каждого хука в отдельности. Добавляйте по одному хуку за раз и проверяйте, что он срабатывает, прежде чем переходить к следующему.

5. Проверяйте опечатки в именах хуков

Самая частая причина, по которой хук не срабатывает — это неправильно написанное имя хука. Скрипт загрузится без ошибок, но неправильно написанная функция хука будет отклонена при валидации.

Путь прогрессии для начинающих

Если вы хотите изучить эту систему с нуля, такая прогрессия работает хорошо:

Напишите файл только с api_version = 1 и on_spawn, который логирует сообщение.
Добавьте скрипт в конфиг пропса и убедитесь, что сообщение лога появляется.
Добавьте on_right_click и логируйте, когда по пропсу кликают.
Добавьте on_left_click с context.event.cancel() для неуязвимости.
Воспроизведите анимацию по правому клику.
Добавьте звук по правому клику.
Добавьте состояние и поведение переключения.
Добавьте наблюдение за зоной для обнаружения приближения.
Только после этого переходите к сложным скриптам с множеством хуков и планировщиками.

Каждый шаг строится на предыдущем, и вы можете тестировать на каждом этапе.

Следующие шаги

Начало работы — структура файлов, хуки, первый скрипт, шаблоны для копирования
Prop API — полный справочник API
Примеры и паттерны — полные рабочие скрипты для изучения и адаптации

Типичные проблемы​

1. Конфиг не загружается / Скрипт не привязан​

2. Файл скрипта не найден​

3. Скрипт вообще не загружается​

4. Хук никогда не срабатывает​

5. Таймаут / превышен бюджет выполнения​

6. context.event равен nil в хуке клика​

7. Анимация не воспроизводится​

8. Частицы не появляются​

9. Звук не воспроизводится​

10. Состояние неожиданно сбрасывается​

Как работает ленивая генерация конфигурации​

Чтение сообщений об ошибках​

Не предполагайте существование недокументированных методов​

Советы по отладке​

1. Используйте context.log:info() активно​

2. Проверяйте консоль при запуске​

3. Проверяйте путь к файлу модели​

4. Тестируйте хуки по отдельности​

5. Проверяйте опечатки в именах хуков​

Путь прогрессии для начинающих​

Следующие шаги​

Типичные проблемы

1. Конфиг не загружается / Скрипт не привязан

2. Файл скрипта не найден

3. Скрипт вообще не загружается

4. Хук никогда не срабатывает

5. Таймаут / превышен бюджет выполнения

6. `context.event` равен nil в хуке клика

7. Анимация не воспроизводится

8. Частицы не появляются

9. Звук не воспроизводится

10. Состояние неожиданно сбрасывается

Как работает ленивая генерация конфигурации

Чтение сообщений об ошибках

Не предполагайте существование недокументированных методов

Советы по отладке

1. Используйте `context.log:info()` активно

2. Проверяйте консоль при запуске

3. Проверяйте путь к файлу модели

4. Тестируйте хуки по отдельности

5. Проверяйте опечатки в именах хуков

Путь прогрессии для начинающих

Следующие шаги