Скриптовый движок Lua в MagmaCore

MagmaCore предоставляет песочницу Lua и среду ScriptInstance для сил боссов и скриптов NPC EliteMobs, пропсов FreeMinecraftModels и авторских эффектов зачарований. Проверка файлов и управление экземплярами общие, но доступные хуки, таблицы контекста, области кулдаунов и сроки жизни зависят от плагина. Запросы зачарований также имеют ограниченный контекст и собственные лимиты; используйте их справочник ниже.

Пропсы FMM и NPC EliteMobs напрямую наследуют общие таблицы (context.world, context.zones, context.scheduler, context.cooldowns, context.log, context.event, context.player, context.state) и добавляют context.prop или context.npc. Силы боссов используют ту же среду, но предоставляют расширенные варианты нескольких таблиц (context.world, context.zones, context.cooldowns, context.scheduler, context.log, context.event), а также context.players, context.entities, context.vectors, context.settings и context.script.

На данный момент этот движок используют следующие плагины:

EliteMobs — силы боссов (on_boss_damaged_by_player, on_enter_combat и другие) и Lua-скрипты NPC для взаимодействия и приближения (on_npc_interact, on_npc_proximity_enter и другие).
FreeMinecraftModels — скрипты пропсов (on_right_click, on_left_click и другие) и авторские эффекты зачарований для предметов.

Здесь описаны общие возможности MagmaCore, используемые FMM, и отличия вариантов EliteMobs для боссов и NPC. Точный контекст боссов приведён на страницах Lua EliteMobs, а NPC — в руководстве по NPC.

Краткое введение в Lua

Если вы совсем не знакомы с Lua, вот минимум синтаксиса, необходимый для написания скриптов для любого плагина Nightbreak.

Переменные

Используйте local для хранения значения:

local cooldown_key = "fire_burst"
local damage_multiplier = 1.5

local означает, что переменная принадлежит только этому файлу или блоку.

Функции

Функции — это переиспользуемые блоки логики:

local function warn_player(player)
  player:send_message("&cMove!")
end

Позже её можно вызвать:

warn_player(some_player)

Проверки `if`

Используйте if, когда что-то должно происходить только иногда:

if context.player == nil then
  return
end

Это означает «если для этого хука нет игрока — остановись здесь».

`nil`

nil означает «нет значения». Это вариант «ничего здесь нет» в Lua.

Вы часто будете проверять nil так:

if context.event ~= nil then
  -- do something with the event
end

~= означает «не равно».

Таблицы

Lua использует таблицы для нескольких задач:

Списки
Объекты с именованными ключами
Итоговое возвращаемое определение скрипта

Пример таблицы с именованными ключами:

local particle = {
  particle = "FLAME",
  amount = 1,
  speed = 0.05
}

Возврат определения скрипта

В конце каждого файла скрипта вы возвращаете одну таблицу:

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Возвращённая таблица является определением скрипта. Загрузчик выполняет файл для проверки, затем повторно выполняет сохранённый исходный текст для каждого экземпляра. Локальные переменные файла принадлежат этому экземпляру, а не всем сущностям с тем же файлом. Редактирование файла не меняет загруженное определение или работающий экземпляр: перезагрузите его средствами плагина-владельца.

Lua-песочница

Все Lua-скрипты выполняются в песочнице среды LuaJ. Несколько глобальных переменных, которые могли бы получить доступ к файловой системе или Java-рантайму, удалены. Правила песочницы одинаковы во всех плагинах, использующих MagmaCore.

Удалённые глобальные переменные

Следующие стандартные глобальные переменные Lua установлены в nil и не могут быть использованы:

Удалено	Почему
`debug`	Раскрывает внутреннее состояние VM
`dofile`	Доступ к файловой системе
`io`	Доступ к файловой системе
`load`	Загрузка произвольного кода
`loadfile`	Доступ к файловой системе
`luajava`	Прямой доступ к классам Java
`module`	Модульная система (не требуется)
`os`	Доступ к операционной системе
`package`	Модульная система (не требуется)
`require`	Модульная система / доступ к файловой системе

Доступная стандартная библиотека

Стандартная среда LuaJ предоставляет следующие обычные средства Lua:

Категория	Функции
Math	`math.abs`, `math.ceil`, `math.floor`, `math.max`, `math.min`, `math.random`, `math.sin`, `math.cos`, `math.sqrt`, `math.pi` и все остальные функции `math.*`
String	`string.byte`, `string.char`, `string.find`, `string.format`, `string.gsub`, `string.len`, `string.lower`, `string.match`, `string.rep`, `string.sub`, `string.upper` и все остальные функции `string.*`
Table	`table.insert`, `table.remove`, `table.sort`, `table.concat` и все остальные функции `table.*`
Итераторы	`pairs`, `ipairs`, `next`
Тип	`type`, `tostring`, `tonumber`, `select`, `unpack`
Обработка ошибок	`pcall`, `xpcall`, `error`, `assert`
Прочее	`print`, `rawget`, `rawset`, `rawequal`, `rawlen`, `setmetatable`, `getmetatable`

Библиотека os недоступна

os полностью удалена. Общие интерфейсы предоставляют время мира через context.world:get_time(); силы боссов получают его из общей основы таблицы мира. Для измерения интервалов храните счётчики тиков в context.state, обновляя их через on_game_tick.

подсказка

print пишет в консоль, но предпочтительнее context.log:info(msg). Все виды скриптов имеют context.log: FMM и NPC предоставляют info, warn, error, а боссы — info, warn, debug.

Контракт файла

Каждый Lua-скрипт обязан return возвращать таблицу. Эта таблица намеренно строгая.

Обязательные и необязательные поля верхнего уровня

Поле	Обязательно	Тип	Примечания
`api_version`	Да	Number	Сейчас должно быть `1`
`priority`	Нет	Number	По умолчанию `0`, преобразуется в целое. Боссы и NPC EliteMobs выполняют меньшие значения раньше. FMM проверяет поле, но запускает пропсы в порядке списка `scripts:`
ключи поддерживаемых хуков	Нет	Function	Должны использовать одно из точных имён хуков, поддерживаемых плагином

Правила валидации

Файл обязан вернуть таблицу.
api_version обязательно и сейчас должно быть 1.
priority должен быть числом, если присутствует.
Каждый дополнительный ключ верхнего уровня должен быть именем поддерживаемого хука.
Каждый ключ хука должен указывать на функцию.
Неизвестные ключи верхнего уровня отклоняются.

Приоритет зависит от поставщика

Проверка MagmaCore принимает priority для всех скриптов. EliteMobs использует его для боссов и NPC, а пропсы FMM следуют списку scripts:. Авторские зачарования используют каталог поставщика и жизненный цикл действий и запросов.

Где лежат файлы скриптов

Поставщик выбирает каталог. Общий движок рекурсивно ищет .lua, исключая архивные пути конфигурации. Нормализованные абсолютные пути сортируются без учёта регистра, затем по точному пути. Для каждого имени, приведённого к нижнему регистру, выбирается первый файл, а пропущенные дубликаты, содержимое которых отличается от выбранного файла, записываются в журнал. Ошибка проверки выбранного файла не переключает загрузку на дубликат. Зарегистрированные ссылки сохраняют фактическое написание имени; используйте его в настройках. Силы боссов и каталоги зачарований имеют свои правила поиска: общий валидатор не делает каталоги взаимозаменяемыми.

Имена файлов должны быть уникальными

Ключом служит имя файла, а не путь. Два door.lua в разных подпапках имеют один ключ, поэтому регистрируется только один. Задавайте уникальные имена.

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

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("Doing something!")
end

return {
  api_version = 1,
  priority = 0,

  on_spawn = function(context)
    do_something(context)
  end
}

Распространённые имена хуков

Эти имена встречаются в нескольких средах, но каждый тип включает только подходящие хуки. Пропсы FMM используют все перечисленные ниже, боссы — свой список. NPC используют on_spawn, on_remove, on_game_tick, on_npc_interact, on_npc_proximity_enter, on_npc_proximity_leave, on_zone_enter и on_zone_leave.

Хук	Когда срабатывает
`on_spawn`	Вызывается жизненным циклом спавна пропса FMM, босса или NPC EliteMobs; создание `ScriptInstance` само по себе его не вызывает
`on_game_tick`	Каждый тик, пока инициализированный экземпляр активен и не приостановлен
`on_zone_enter`	Вход в поддерживаемую зону. FMM и NPC отслеживают игроков; верхнеуровневые хуки боссов приходят от зон EliteScript
`on_zone_leave`	Выход из поддерживаемой зоны. FMM и NPC отслеживают игроков; верхнеуровневые хуки боссов приходят от зон EliteScript

Синтаксис методов: `:` против `.`

В Lua object:method(arg) — это сокращение для object.method(object, arg). Методы таблиц контекста MagmaCore удаляют этот неявный первый аргумент, поэтому для методов вроде context.log.info работают обе формы:

context.log:info("hello")
context.log.info("hello")  -- same thing

Глобальные функции em вызываются через .: em.create_location(...), em.zone.create_sphere_zone(...) и em.location.is_protected(...). Функции изменения событий EliteMobs context.event.set_damage_amount(...) и context.event.multiply_damage_amount(...) также требуют .. Документация использует : для методов таблиц контекста и . для обычных функций.

Бюджет выполнения

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

Обычная среда применяет следующие ограничения:

Ограничение	Значение
Процессорное время текущего потока	50 миллисекунд
Выполненных инструкций Lua	250,000

Превышение вызывает ошибку Lua. Счётчик проверяется на каждой инструкции, часы — каждые 1 024 инструкции и после возврата вызова. Это не прерывает выполняющийся метод Java/Bukkit, а 50 мс процессорного времени не означают предел 50 мс реального времени. Неперехваченная ошибка хука или колбэка закрывает экземпляр; ошибка начальной проверки отклоняет определение. Если измерение CPU недоступно, используется 250 мс прошедшего времени с тем же лимитом инструкций. Пакеты запросов зачарований могут иметь меньшие квоты.

Бесконечные циклы ловятся, но всё равно стоят вам тика

VM проверяет бюджет при выполнении инструкций Lua, поэтому while true do end прерывается. Цикл всё же может израсходовать всю квоту процессорного времени серверного потока и отключает скрипт; эта защита не оправдывает неограниченные циклы.

Вложенные вызовы разделяют один бюджет: вся цепочка получает 50 мс процессорного времени и 250 000 инструкций, без отдельной квоты на каждый вызов.

Чтобы оставаться в рамках бюджета:

Избегайте неограниченных циклов внутри хуков.
Делайте обработчики on_game_tick лёгкими — они выполняются каждый тик.
Используйте context.scheduler:run_repeating(...), чтобы распределить работу по тикам.
Ограничивайте дорогую работу через context.cooldowns или разумный интервал.

Ошибки выполнения скрипта

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

`context.state`

Обычная Lua-таблица, живущая всё время существования экземпляра скрипта. Используйте её для хранения флагов, счётчиков, ID задач, состояний переключателей и любых данных, которые нужно разделять между хуками.

return {
  api_version = 1,

  on_spawn = function(context)
    context.state.is_open = false
    context.state.click_count = 0
    context.state.task_id = nil
  end,

  on_right_click = function(context)
    context.state.click_count = (context.state.click_count or 0) + 1
  end
}

к сведению

context.state хранит общие данные хуков экземпляра в памяти и не переживает перезагрузку. Другие таблицы создаются лениво и могут содержать снимки значений. FMM кэширует context.prop, но поля вроде current_location читает по запросу. Для обновления прочитайте динамическое поле снова: сохранённая в переменной таблица сама не обновляется. Присваивание динамическому полю скрывает его getter.

`context.log`

Журнал консоли доступен всем видам скриптов. Общий log.info добавляет [Lua]; для определения источника включайте метку скрипта в текст. Диагностика ошибок указывает файл, обычный журнал не добавляет его имя автоматически. FMM и NPC предоставляют info, warn, error; боссы — info, warn, debug.

Метод	Примечания
`log:info(message)`	Информационное сообщение
`log:warn(message)`	Предупреждающее сообщение
`log:error(message)`	Сообщение уровня предупреждения (логируется на уровне WARN, так же как `log:warn`)

Вариант EliteMobs

context.log в EliteMobs регистрирует debug вместо error. Используйте log:debug(message) для отладочного вывода (появляется на уровне info с префиксом debug).

context.log:info("Script loaded!")
context.log:warn("Something unexpected happened")
-- Generic/FMM/NPC logger:
context.log:error("Critical failure in zone setup")
-- EliteMobs boss logger:
context.log:debug("Boss debug detail")

`context.cooldowns`

Таблица кулдаунов управляет кулдаунами по времени. Локальные и общие глобальные кулдауны переводят каждый настроенный тик в 50 мс монотонного прошедшего времени, включая паузы и низкий TPS. Глобальные кулдауны боссов вместо этого считают серверные тики. Есть две области:

Локальные кулдауны используют точные строковые ключи в хранилище владельца; его область описана ниже. nil выбирает ключ по умолчанию: __lua: и имя файла скрипта.
Глобальные кулдауны общие для всех скриптов на одной сущности-владельце (например, всех скриптов на одном пропсе или всех Lua-сил на одном боссе).

`cooldowns:check_local(key?, duration)`

Проверяет локальный ключ: если готов, запускает кулдаун и возвращает true, иначе false. Это один синхронный вызов Lua. Он не проверяет и не запускает глобальный кулдаун. Хранилище не является отдельным API межпоточной блокировки.

Параметр	Тип	Примечания
`key`	string (опционально)	Идентификатор. `nil` выбирает ключ по умолчанию
`duration`	int	Длительность кулдауна в тиках (20 = 1 секунда)

on_right_click = function(context)
  -- Only allow this action once every 3 seconds
  if not context.cooldowns:check_local("interact", 60) then
    return
  end
  -- ... do the action
end

Общий порядок аргументов

Боссы, NPC и FMM используют check_local(key?, duration). Для ключа по умолчанию передавайте check_local(nil, 60); check_local(60) не означает кулдаун 60 тиков с таким ключом. Старые экспериментальные NPC использовали check_local(duration, key?); обновите эти скрипты.

`cooldowns:local_ready(key?)`

Возвращает true, если локальный кулдаун истёк (или никогда не устанавливался), false, если ещё активен.

`cooldowns:local_remaining(key?)`

Возвращает количество оставшихся тиков локального кулдауна, или 0, если он готов.

`cooldowns:set_local(duration, key?)`

Устанавливает локальный кулдаун без проверки, активен ли он уже. Используйте это для безусловного сброса кулдауна.

Параметр	Тип	Примечания
`duration`	int	Длительность в тиках. Передайте 0 или отрицательное значение для очистки.
`key`	string (опционально)	Идентификатор. `nil` выбирает ключ по умолчанию

`cooldowns:global_ready()`

Возвращает true, если глобальный кулдаун (общий для всех скриптов на одной сущности) истёк.

`cooldowns:set_global(duration)`

Устанавливает глобальный кулдаун. В общих таблицах ноль или отрицательное значение очищают его. Глобальные кулдауны боссов сохраняют более позднее время окончания: более короткая длительность никогда не сокращает активный глобальный кулдаун, а ноль или отрицательное значение ничего не делают. Установка локального не устанавливает глобальный, и наоборот.

Параметр	Тип	Примечания
`duration`	int	Длительность в тиках

Области глобальных кулдаунов

«Владелец» глобального кулдауна зависит от типа скрипта:

Lua-силы EliteMobs — общий на EliteEntity (один блок на босса). global_ready() / set_global() используют встроенную систему кулдаунов сил босса; локальные кулдауны также общие для всех сил на одном боссе.
NPC EliteMobs — глобальные кулдауны и явные локальные ключи общие через один адаптер NPC. Скрипты с одинаковым локальным ключом влияют друг на друга; пропущенные ключи остаются привязаны к файлам.
Пропсы FMM — глобальный кулдаун общий для размещённого пропса; каждый скрипт имеет собственный адаптер и локальное хранилище.
Действия зачарований — глобальный общий для игрока внутри поставщика; локальный принадлежит игроку и ID зачарования и сохраняется при смене экипировки и завершении действий. См. авторские зачарования.

`context.scheduler`

Планировщик запускает отложенные и повторяющиеся задачи. Созданные через него задачи принадлежат экземпляру и отменяются при закрытии. Это не удаляет созданные сущности, не отменяет изменения мира и таймеры отдельных помощников UI или эффектов. На паузе наступившая разовая задача ждёт возобновления, а повторяющаяся пропускает вызовы.

Здесь используются имена MagmaCore (run_later, run_repeating, cancel). Имена EliteMobs (run_after(ticks, callback), run_every(interval, callback), cancel_task(taskId)) также принимаются как псевдонимы во всех видах скриптов.

`scheduler:run_later(ticks, callback)`

Запускает колбэк один раз после задержки. Возвращает числовой ID задачи.

Параметр	Тип	Примечания
`ticks`	int	Задержка в серверных тиках (20 тиков = 1 секунда)
`callback`	function	Вызывается со свежим `context`, когда задержка истекает

context.scheduler:run_later(40, function(delayed_context)
  delayed_context.log:info("2 seconds have passed!")
end)

`scheduler:run_repeating(delay, interval, callback)`

Запускает колбэк повторно с фиксированным интервалом. Возвращает числовой ID задачи.

Параметр	Тип	Примечания
`delay`	int	Начальная задержка в тиках перед первым запуском
`interval`	int	Тики между каждым последующим запуском
`callback`	function	Вызывается со свежим `context` каждый интервал

context.state.particle_task = context.scheduler:run_repeating(0, 20, function(tick_context)
  tick_context.log:info("Another second passed!")
end)

`scheduler:cancel(taskId)`

Отменяет по ID задачу этого экземпляра. Неизвестный ID или ID другого экземпляра ничего не делает.

Параметр	Тип	Примечания
`taskId`	int	ID задачи, возвращённый из `run_later` или `run_repeating`

Останавливайте повторение, когда его назначение выполнено

Закрытие автоматически отменяет принадлежащие экземпляру задачи. Отменяйте раньше, если взаимодействие или фаза боя закончились, а экземпляр остаётся жив, например в on_exit_combat босса. Подходят обе группы имён. Используйте хуки жизненного цикла плагина; закрытие из-за ошибки не гарантирует вызов собственного хука очистки.

Колбэки получают свежий контекст

Колбэк получает новый контекст без исходного события и участника. Используйте его, а не внешний контекст. Если позже нужен исходный игрок, сохраните UUID в хуке, затем найдите игрока заново и проверьте доступность. Сохранённый внешний контекст может разрешить ленивое поле события уже после завершения исходного события.

`context.world`

Таблица позволяет запрашивать и изменять мир. При первом построении она сохраняет текущий мир владельца; сохранённая таблица не следует за последующими переходами между мирами.

Общая таблица мира

Здесь описана общая таблица пропсов FMM и NPC EliteMobs, включая наносящий урон strike_lightning(...). FMM добавляет необязательные средства транспорта и лута EliteMobs; см. дополнения FMM. EliteMobs добавляет в общие таблицы визуальную молнию и создание NPC и боссов с проверкой загруженных чанков. Силы боссов затем добавляют или заменяют собственные методы; см. мир и окружение EliteMobs.

Координаты и таблицы локаций

Общие интерфейсы принимают вызовы по координатам (strike_lightning(x, y, z), spawn_particle(name, x, y, z, ...)) и по таблицам (strike_lightning_at_location(loc), spawn_particle_at_location(loc, ...)). Боссы также поддерживают оба стиля, но некоторые методы имеют особое поведение.

Общие аргументы локации требуют x, y, z. Пропущенный или неразрешимый мир заменяется миром таблицы. Общие частицы по локации всё равно используют сохранённый мир, поэтому передавайте локацию в нём. Преобразователи боссов и запросы em.location.* имеют другие правила.

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

`world.name`

Строковое поле, содержащее имя мира.

`world:get_block_at(x, y, z)`

Возвращает материал в нижнем регистре, например "stone" или "air". Если чанк не загружен, возвращает "air" без принудительной загрузки.

Параметр	Тип	Примечания
`x`	int	Координата блока X
`y`	int	Координата блока Y
`z`	int	Координата блока Z

`world:set_block_at(x, y, z, material)`

Устанавливает блок в главном потоке, избегая принудительной загрузки чанков.

Параметр	Тип	Примечания
`x`	int	Координата блока X
`y`	int	Координата блока Y
`z`	int	Координата блока Z
`material`	string	Имя Bukkit Material в нижнем регистре (например, `"stone"`, `"air"`, `"oak_planks"`)

Возвращает true, если материал допустим и изменение поставлено в очередь, иначе false. Если при выполнении задачи чанк не загружен, изменение пропускается.

Защита региона автоматически не проверяется. Используйте материал блока и соответствующий запрос защиты перед установкой. Приём задачи не доказывает изменение блока.

`world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)`

Создаёт частицы в локации.

Параметр	Тип	По умолчанию	Примечания
`particle`	string	обязательно	Имя Bukkit Particle, приводится к верхнему регистру при поиске (например, `"FLAME"`, `"HAPPY_VILLAGER"`)
`x`	number	обязательно	Координата X
`y`	number	обязательно	Координата Y
`z`	number	обязательно	Координата Z
`count`	int	`1`	Количество частиц
`dx`	number	`0`	Разброс/смещение по X
`dy`	number	`0`	Разброс/смещение по Y
`dz`	number	`0`	Разброс/смещение по Z
`speed`	number	`0`	Скорость частиц

Частицы, требующие данных

Некоторые частицы, например DUST и FALLING_DUST, требуют дополнительных данных, которых этот простой API не предоставляет. Используйте CLOUD, SMOKE, CAMPFIRE_COSY_SMOKE, SNOWFLAKE, FLAME, HAPPY_VILLAGER, HEART, NOTE, ENCHANT. Для цветной пыли есть world:spawn_dust(...) в справочнике мира.

Частицы с обязательными данными могут вызвать исключение Bukkit и отключить экземпляр. Для FMM/MagmaCore предпочтительны перечисленные частицы без данных.

`world:play_sound(sound, x, y, z, volume, pitch)`

Воспроизводит звук в локации.

Параметр	Тип	По умолчанию	Примечания
`sound`	string	обязательно	Имя перечисления Bukkit Sound (например, `"ENTITY_EXPERIENCE_ORB_PICKUP"`) или кастомный ключ звука из ресурс-пака (например, `"mypack:boss.roar"`)
`x`	number	обязательно	Координата X
`y`	number	обязательно	Координата Y
`z`	number	обязательно	Координата Z
`volume`	number	`1.0`	Громкость
`pitch`	number	`1.0`	Высота тона

Кастомные звуки из ресурс-пака

Имя сначала сопоставляется с зарегистрированными звуками Bukkit (без учёта регистра, поэтому "ENTITY_ARROW_SHOOT" и "entity_arrow_shoot" — одно и то же). Если ничего не совпало, оно нормализуется в ключ с пространством имён в нижнем регистре и проигрывается как кастомный звук из ресурс-пака. Значение, которое не является ни известным звуком, ни корректным ключом с пространством имён, просто ничего не проигрывает, а не вызывает ошибку, поэтому опечатка молча ничего не делает вместо отключения вашего скрипта.

То же относится к world:play_sound_at_location(loc, sound, volume, pitch).

`world:strike_lightning(x, y, z)`

Бьёт молнией в локации (визуальная и наносящая урон).

Параметр	Тип	Примечания
`x`	number	Координата X
`y`	number	Координата Y
`z`	number	Координата Z

`world:get_time()`

Возвращает текущее время мира в тиках.

`world:set_time(ticks)`

Устанавливает время мира.

Параметр	Тип	Примечания
`ticks`	int	Время мира (0 = рассвет, 6000 = полдень, 13000 = ночь, 18000 = полночь)

`world:get_nearby_entities(x, y, z, radius)`

Возвращает массив с индексами от 1 для сущностей внутри параллельного осям бокса с заданным центром. Владелец скрипта не исключается.

Параметр	Тип	Примечания
`x`	number	Центр X
`y`	number	Центр Y
`z`	number	Центр Z
`radius`	number	Радиус поиска (используется как полуразмер по всем трём осям)

предупреждение

Возвращает все сущности в области, включая неживые: выпавшие предметы, снаряды и другие. Перед методами живых сущностей проверяйте if entity.damage then.

`world:get_nearby_players(x, y, z, radius)`

Возвращает массив игроков с индексами от 1 внутри бокса с полуразмером radius по каждой оси. Игровые режимы не фильтруются.

Параметр	Тип	Примечания
`x`	number	Центр X
`y`	number	Центр Y
`z`	number	Центр Z
`radius`	number	Радиус поиска

`world:spawn_entity(entity_type, x, y, z)`

Спавнит ванильную сущность Minecraft в указанной локации.

Параметр	Тип	Примечания
`entity_type`	string	Имя типа сущности Bukkit в нижнем регистре (например, `"zombie"`, `"skeleton"`, `"pig"`)
`x`	number	Координата X
`y`	number	Координата Y
`z`	number	Координата Z

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

`world:get_highest_block_y(x, z)`

Возвращает Y верхнего блока по запросу Bukkit для X/Z. В отличие от get_block_at, не проверяет загруженность чанка.

Параметр	Тип	Примечания
`x`	int	Координата блока X
`z`	int	Координата блока Z

`world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance], [fluid_mode], [blocks_only], [loaded_only])`

Бросает луч из точки в направлении и возвращает информацию о том, что он попал.

Параметр	Тип	По умолчанию	Примечания
`from_x`	number	обязательно	Начало X
`from_y`	number	обязательно	Начало Y
`from_z`	number	обязательно	Начало Z
`dir_x`	number	обязательно	Компонент направления X
`dir_y`	number	обязательно	Компонент направления Y
`dir_z`	number	обязательно	Компонент направления Z
`max_distance`	number	`50`	Максимальная дистанция луча
`fluid_mode`	string	`"NEVER"`	`NEVER`, `SOURCE_ONLY` или `ALWAYS`
`blocks_only`	boolean	`false`	Игнорировать сущности, проверять только блоки
`loaded_only`	boolean	`false`	Вернуть nil без трассировки, если в ограничивающем прямоугольнике луча есть незагруженный чанк

При loaded_only=true также проверяйте результат на nil. Иначе промах возвращает таблицу с пустыми полями попадания:

Поле	Тип	Примечания
`hit_entity`	entity table или nil	Первая сущность, в которую попал луч, или `nil`, если ни одной
`hit_location`	location table или nil	Точка, где луч во что-то попал
`hit_block`	table или nil	`{x, y, z, material}` блока, в который попал луч, или `nil`, если ни один блок не задет

Материалы блоков записаны в нижнем регистре. Совмещённая трассировка использует размер луча для сущностей 0.5 без фильтра сущностей. Проверяется весь ограничивающий прямоугольник, поэтому незагруженный чанк в стороне от самого луча тоже может отклонить запрос. Неверное имя режима жидкости вызывает ошибку.

`world:spawn_firework(x, y, z, colors, [type], [power])`

Запускает фейерверочную ракету в указанной локации.

Параметр	Тип	По умолчанию	Примечания
`x`	number	обязательно	Координата X
`y`	number	обязательно	Координата Y
`z`	number	обязательно	Координата Z
`colors`	table	обязательно	Массив строк цветов, например, `{"RED", "BLUE", "WHITE"}`
`type`	string	`"BALL"`	Форма фейерверка: `"BALL"`, `"BALL_LARGE"`, `"STAR"`, `"BURST"`, `"CREEPER"`
`power`	int	`1`	Сила полёта, 0-127

-- Example: red and yellow firework burst
context.world:spawn_firework(loc.x, loc.y, loc.z, {"RED", "YELLOW"}, "BURST", 2)

`world:place_temporary_block(x, y, z, material, [ticks], [require_air])`

Ставит временный блок и восстанавливает сохранённый BlockData через положительный интервал. Полное состояние блока и инвентарь не сохраняются.

Параметр	Тип	По умолчанию	Примечания
`x`	int	обязательно	Координата блока X
`y`	int	обязательно	Координата блока Y
`z`	int	обязательно	Координата блока Z
`material`	string	обязательно	Имя Bukkit Material (например, `"stone"`, `"ice"`)
`ticks`	int	`0`	Тики до восстановления. Ноль или отрицательное значение ставят блок навсегда без учёта
`require_air`	boolean	`false`	Если `true`, ставит блок только при условии, что цель — воздух

Возвращает false, если материал недопустим или чанк не загружен. Иначе возвращает true после приёма запроса. При require_air=true и блоке не из воздуха менеджер пропускает замену, хотя сам запрос был принят.

При положительном числе тиков менеджер сохраняет исходные данные блока и восстанавливает их по окончании таймера, при выгрузке чанка или мира либо при выключении плагина. Восстановление происходит, только если на месте всё ещё стоит временный блок, поэтому более поздняя правка не перезаписывается. Повторная установка на блок, где всё ещё стоит временный блок, перезапускает его таймер и сохраняет первый сохранённый оригинал. Блоки с блочными сущностями, например сундуки и таблички, и блоки, уже удерживаемые другим владельцем временных блоков, например арендой зачарования, пропускаются. Разрушение временного блока ничего не выбрасывает и прекращает учёт без восстановления; установка блока на это место также прекращает учёт.

Таймеры не отменяются вместе с Lua-скриптом, а защита региона автоматически не проверяется.

`world:drop_item(x, y, z, material, [amount])`

Бросает сущность-предмет в указанной локации с естественным разбросом.

Параметр	Тип	По умолчанию	Примечания
`x`	number	обязательно	Координата X
`y`	number	обязательно	Координата Y
`z`	number	обязательно	Координата Z
`material`	string	обязательно	Имя Bukkit Material
`amount`	int	`1`	Размер стака

Возвращает таблицу сущности выроненного предмета, или nil, если материал был недопустим.

`context.zones`

Таблица создаёт зоны и отслеживает вход и выход игроков. Пропсы FMM и NPC используют описанные здесь create_sphere(...), create_cylinder(...), create_cuboid(...), watch(...), unwatch(...), вызывающие on_zone_enter и on_zone_leave. Зоны принадлежат экземпляру и удаляются при закрытии. Боссы используют отдельную таблицу с get_entities_in_zone(...), get_locations_in_zone(...), watch_zone(...); см. зоны и выбор целей EliteMobs.

`zones:create_sphere(x, y, z, radius)`

Создаёт сферу с заданным центром. Возвращает числовой дескриптор или nil, если у владельца нет мира.

Параметр	Тип	Примечания
`x`	number	Центр X
`y`	number	Центр Y
`z`	number	Центр Z
`radius`	number	Радиус сферы

`zones:create_cylinder(x, y, z, radius, height)`

Создаёт цилиндр. Возвращает числовой дескриптор или nil, если у владельца нет мира.

Параметр	Тип	Примечания
`x`	number	Центр X
`y`	number	Центр Y (основание)
`z`	number	Центр Z
`radius`	number	Радиус цилиндра
`height`	number	Высота цилиндра

`zones:create_cuboid(x, y, z, xSize, ySize, zSize)`

Создаёт кубоид и возвращает числовой дескриптор, либо nil без мира владельца. Общие наблюдатели проверяют точку позиции игрока, поэтому размеры являются полуразмерами вокруг центра. Это отличается от пересечения сущностей и выборки точек в зонах боссов. Если zSize равен нулю, а xSize нет, общая форма подставляет xSize для Z.

Параметр	Тип	Примечания
`x`	number	Центр X
`y`	number	Центр Y
`z`	number	Центр Z
`xSize`	number	Полуразмер по X
`ySize`	number	Полуразмер по Y
`zSize`	number	Полуразмер по Z

`zones:watch(handle, onEnterCallback, onLeaveCallback)`

Включает уведомления о входе и выходе для созданной зоны. Аргументы должны быть функциями Lua, но их тела не вызываются: логика выполняется через on_zone_enter и on_zone_leave. Состав зоны отслеживается с создания, поэтому поздний watch не сообщает о входе уже учтённых внутри игроков. Передача nil в следующем watch не очищает ранее включённое уведомление.

Параметр	Тип	Примечания
`handle`	int	Дескриптор зоны из вызова `create_*`
`onEnterCallback`	function или nil	Функция включает `on_zone_enter`; её тело игнорируется
`onLeaveCallback`	function или nil	Функция включает `on_zone_leave`; её тело игнорируется

Возвращает true, если отслеживание было настроено успешно, nil, если дескриптор зоны недопустим.

к сведению

Проверка идёт перед on_game_tick по точкам позиции игроков в текущем мире владельца, а не по полным хитбоксам. Для сферы точка должна быть строго внутри радиуса; цилиндр включает основание, но исключает верхнюю грань. Зона сохраняет координаты и мир создания. Отключение игрока или удаление наблюдателя не гарантирует хук выхода. Сохраняйте разумное число зон.

`zones:unwatch(handle)`

Прекращает отслеживание зоны и очищает её ресурсы.

Параметр	Тип	Примечания
`handle`	int	Дескриптор зоны, отслеживание которой нужно прекратить

Пример: триггерная зона по близости

return {
  api_version = 1,

  on_spawn = function(context)
    local loc = context.prop.current_location
    if loc == nil then return end

    local handle = context.zones:create_sphere(loc.x, loc.y, loc.z, 5)

    -- Pass placeholder functions to enable on_zone_enter and on_zone_leave hooks.
    -- The placeholder bodies are ignored; the actual logic goes in the hooks below.
    context.zones:watch(handle, function() end, function() end)

    context.state.zone_handle = handle
  end,

  on_zone_enter = function(context)
    context.log:info("Player entered zone!")
  end,

  on_zone_leave = function(context)
    context.log:info("Player left zone!")
  end,

  on_destroy = function(context)
    if context.state.zone_handle then
      context.zones:unwatch(context.state.zone_handle)
    end
  end
}

`context.event`

Таблица есть, когда у хука имеется событие или участник. Клики по пропсам FMM используют флаг отмены плагина; взаимодействия NPC и общие зоны могут передавать участника без события Bukkit. Таблицы нет в on_game_tick, запланированных колбэках и хуках жизненного цикла без исходного игрока.

Хуки on_projectile_hit пропсов FMM получают отменяемое событие попадания снаряда FreeMinecraftModels, поэтому cancel() и uncancel() доступны. Хук выполняется после того, как FMM обработал попадание, поэтому отмена не мешает израсходовать непробивающий снаряд. Хук не срабатывает, если другой плагин уже отменил попадание. context.event.player — это стрелок, если он является живой сущностью (это может быть моб), иначе поле отсутствует; context.player задаётся только тогда, когда снаряд выпустил игрок. Хук также предоставляет context.projectile в виде таблицы сущности для снаряда.

В общих on_zone_enter и on_zone_leave поля context.player и context.event.player указывают вошедшего или вышедшего игрока. Эти хуки не основаны на отменяемом событии Bukkit, поэтому cancel() и uncancel() отсутствуют.

Поле / Метод	Тип	Примечания
`is_cancelled`	boolean	Состояние при первом разрешении подтаблицы события. `cancel()` и `uncancel()` не обновляют его
`cancel()`	method	Отменяет событие; есть только у отменяемых событий
`uncancel()`	method	Снимает отмену; есть только у отменяемых событий
`player`	entity table	Игрок, участвующий в событии, если есть

on_right_click = function(context)
  if context.event and context.event.cancel then
    context.event:cancel()  -- prevent the default right-click interaction
  end
end

Таблица событий EliteMobs

Силы EliteMobs имеют расширенную таблицу с уроном, причиной, источником и методами изменения урона. Поля описаны в справочнике API Lua.

Вспомогательное пространство имён `em`

em доступна при загрузке файла. Конструкторы создают данные без загрузки миров, регистрации наблюдения или проверки полной формы. Возвращённые сеттеры изменяют свою таблицу и сохраняют переданные таблицы локаций по ссылке.

Функция	Назначение
`em.create_location(x, y, z [, world, yaw, pitch])`	Создать таблицу локации с опциональными именем мира, yaw и pitch. У возвращённой таблицы также есть метод `.add(dx, dy, dz)`, смещающий локацию на месте и возвращающий саму себя для построения цепочки.
`em.create_vector(x, y, z)`	Создать таблицу вектора
`em.zone.create_sphere_zone(radius)`	Создать определение сферической зоны
`em.zone.create_dome_zone(radius)`	Создать определение купольной зоны
`em.zone.create_cylinder_zone(radius, height)`	Создать определение цилиндрической зоны
`em.zone.create_cuboid_zone(x, y, z)`	Создать определение кубоидной зоны
`em.zone.create_cone_zone(length, radius)`	Создать определение конусной зоны
`em.zone.create_static_ray_zone(length, thickness)`	Создать определение статической лучевой зоны
`em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)`	Создать определение вращающейся лучевой зоны
`em.zone.create_translating_ray_zone(length, point_radius, animation_duration)`	Создать определение перемещающейся лучевой зоны
`em.location.is_in_dungeon(loc)`	Проверить, находится ли локация внутри любого зарегистрированного региона данжа (любой владелец, сообщающий вид `"dungeon"`)
`em.location.is_protected(loc)`	Проверить, находится ли локация в любом защищённом регионе (WorldGuard, GriefPrevention, регионы EM и т.д.)
`em.location.owned_by(loc, namespace)`	Проверить, владеет ли конкретный namespace плагина локацией (например, `"EliteMobs"`)
`em.location.owners(loc)`	Массив строк-неймспейсов, владеющих локацией
`em.location.kinds_at(loc)`	Массив тегов вида в локации (`"elitemobs"`, `"dungeon"`, `"world_package"`, `"open_world_dungeon"`, категория размера данжа)
`em.location.has_kind(loc, kind)`	Проверить, помечена ли локация указанным видом

Плагины регионов определяются автоматически

MagmaCore содержит адаптеры WorldGuard и GriefPrevention. Потребители инициализируют их при включении; запрос защиты также может сделать это лениво. Запросы охватывают зарегистрированных поставщиков, а не любой возможный плагин защиты. Сбой зарегистрированного адаптера региона трактуется как наличие защиты. Без поставщика или владения защитой возвращается false; предупреждения указывают отсутствующих поставщиков.

В em.location.* поле world должно содержать имя загруженного мира или {name=...}. Подстановки мира владельца нет. Отсутствующий или неразрешимый мир и вход nil дают false либо пустой массив. Пропущенные координаты равны нулю, но неверный формат числовых полей может вызвать ошибку. Пространства имён владельцев чувствительны к регистру, теги видов — нет. Владение само по себе не означает принадлежность данжу или защиту. Порядок массивов не гарантируется.

Конструкторы зон возвращают цепочечные таблицы с :set_center(loc) (или :set_origin(loc) / :set_destination(loc) в зависимости от типа зоны):

-- At file scope: create a reusable zone shape
local blast_zone = em.zone.create_sphere_zone(5)

return {
  api_version = 1,

  on_spawn = function(context)
    -- Anchor the zone at call time
    blast_zone:set_center(context.boss:get_location())
    local entities = context.zones:get_entities_in_zone(blast_zone)
    -- ...
  end
}

к сведению

Пространство имён em особенно полезно в EliteMobs, где определения зон используются с context.zones:get_entities_in_zone() и context.script. В FreeMinecraftModels чаще применяются методы context.zones:create_sphere(...) / create_cylinder(...) / create_cuboid(...) для простых отслеживаемых зон.

Таблицы сущностей

Ниже приведены общие методы. Полный справочник Lua API также описывает снаряды, проверки пути, владение и защиту для общих таблиц сущностей. Обёртки сил боссов имеют собственный раздел.

Запросы мира и данные событий возвращают таблицы сущностей с полями и методами, зависящими от типа сущности.

Базовые поля сущности

Поле	Тип	Примечания
`uuid`	string	UUID сущности
`entity_type`	string	Тип сущности (например, `"player"`, `"zombie"`, `"skeleton"`, `"villager"`)
`is_valid`	boolean	Действительна ли ещё ссылка на сущность
`is_dead`	boolean	Мертва ли сущность
`is_player`	boolean	Является ли сущность игроком
`is_hostile`	boolean	Реализует ли Bukkit `Monster`, а не текущая агрессивность
`is_passive`	boolean	Реализует ли Bukkit `Animals`; пассивное поведение не гарантируется
`current_location`	location table	Текущая позиция сущности (`x`, `y`, `z`, `world`, `yaw`, `pitch`)
`world`	string	Имя мира, в котором находится сущность

Базовые методы сущности

Метод	Возвращает	Примечания
`teleport(location_table)`	void	Требует `x`, `y`, `z`; пропущенный или неразрешимый мир заменяется миром сущности. `yaw` и `pitch` по умолчанию нулевые. Путь и защита автоматически не проверяются
`remove()`	void	Удаляет сущность из мира. Действует только если сущность ещё валидна.
`set_silent(flag)`	void	Заглушает или включает звуки сущности.
`set_invulnerable(flag)`	void	Делает сущность неуязвимой или уязвимой к урону.
`set_gravity(flag)`	void	Включает или отключает гравитацию для сущности.
`set_glowing(flag)`	void	Переключает эффект светящегося контура у сущности.

Поля живой сущности

Живые сущности (игроки, мобы и т.д.) имеют все базовые поля сущности плюс:

Поле	Тип	Примечания
`health`	number	Текущее здоровье
`maximum_health`	number	Максимальное здоровье
`name`	string	Отображаемое имя
`is_alive`	boolean	Жива ли сущность

Методы живой сущности

Метод	Возвращает	Примечания
`damage(amount)`	void	Наносит сущности указанный урон
`push(x, y, z)`	void	Немедленно прибавляет вектор к текущей скорости
`set_facing(x, y, z)`	void	Телепортирует на месте с новым направлением взгляда
`add_potion_effect(effect, duration, amplifier)`	void	Добавляет эффект зелья. `effect` — строка (например, `"speed"`, `"slowness"`, `"regeneration"`). `duration` в тиках. `amplifier` — уровень эффекта минус 1 (0 = уровень I).
`remove_potion_effect(effect)`	void	Удаляет эффект зелья по имени
`get_scale()`	number	Возвращает эффективный масштаб с модификаторами, либо 1.0 при недоступности
`set_scale(value)`	void	Меняет базовое значение атрибута масштаба, если он доступен

предупреждение

Не все сущности, возвращаемые get_nearby_entities(), являются живыми сущностями. Можно использовать entity.is_player, entity.is_hostile или entity.is_passive для фильтрации по категории, либо проверять if entity.damage then перед вызовом методов живой сущности, таких как damage(), push() или add_potion_effect().

Поля интеграции с плагинами

Таблицы могут включать поля интеграции; без соответствующего расширения они отсутствуют и читаются как nil. Флаги отслеживания, идентификатор модели, статус оператора и большинство вложенных данных — снимки на момент построения. Общие поля здоровья EliteMobs читаются лениво, а методы модели и разрешений проверяют объекты при вызове.

Поля EliteMobs

Доступны, когда установлен EliteMobs.

Поле	Тип	Примечания
`is_elite`	boolean	Является ли сущность элитой EliteMobs
`is_custom_boss`	boolean	Является ли сущность кастомным боссом EliteMobs (также доступно внутри подтаблицы `elite`)
`is_significant_boss`	boolean	Является ли сущность кастомным боссом с множителем здоровья больше 1 (то есть продуманное столкновение, а не элита-наполнитель)
`elite`	table или nil	Подтаблица информации об элите (см. ниже). `nil`, если сущность не элита.

Подтаблица elite содержит:

Поле	Тип	Примечания
`elite.level`	int	Уровень элиты
`elite.name`	string или nil	Отображаемое имя элиты
`elite.health`	number	Текущее здоровье
`elite.max_health`	number	Максимальное здоровье
`elite.is_custom_boss`	boolean	Является ли это кастомным боссом (в отличие от естественной элиты)
`elite.health_multiplier`	number	Множитель здоровья, заданный в конфиге
`elite.damage_multiplier`	number	Множитель урона, заданный в конфиге
`elite:remove()`	void	Удаляет через процедуру EliteMobs; это не убийство и не гарантия лута

Пример: разный урон элитам

local entities = context.world:get_nearby_entities(x, y, z, 5)
for _, entity in ipairs(entities) do
    if entity.is_elite then
        -- Deal double damage to elites
        entity:damage(20)
        context.log:info("Hit elite: " .. entity.elite.name .. " (level " .. entity.elite.level .. ")")
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

Поля FreeMinecraftModels

Доступны, когда установлен FreeMinecraftModels.

Поле	Тип	Примечания
`is_modeled`	boolean	Прикреплена ли к сущности FMM-модель (DynamicEntity или PropEntity)
`is_prop`	boolean	Является ли сущность FMM-пропсом (статической декоративной сущностью)
`model`	table или nil	Подтаблица информации о модели (см. ниже). `nil`, если сущность не смоделирована.

Подтаблица model содержит:

Поле	Тип	Примечания
`model.model_id`	string или nil	ID чертежа модели (например, `"torch_01"`)
`model.is_dynamic`	boolean	Является ли смоделированная сущность DynamicEntity (модель моба/босса), а не статичным пропсом
`model:play_animation(name, [blend], [loop])`	boolean	Принимает запрос анимации. `blend` и `loop` по умолчанию `false`. Очередь или подавленная атака могут дать `true` без немедленного воспроизведения. Терминальное состояние смерти отклоняет запрос
`model:stop_animations()`	void	Очищает очередь и возвращает к анимации покоя, если она есть; терминальное состояние смерти не меняется
`model:remove()`	void	Удаляет смоделированную сущность через корректный пайплайн удаления FMM.

Для таблиц игроков FMM также добавляет:

Поле / Метод	Тип	Примечания
`is_op`	boolean	Является ли игрок оператором сервера
`has_permission(node)`	boolean	Есть ли у игрока разрешение

Эти два значения игрока существуют только в скриптах FreeMinecraftModels. В общих таблицах, создаваемых внутри EliteMobs, собственный адаптер FreeMinecraftModels из EliteMobs добавляет is_modeled, is_prop и model, но не is_op и has_permission.

FMM предоставляет is_holding_elitemobs_item(filename): проверяется тег имени файла EliteMobs в основной руке, включая .yml, а не отображаемое имя. Пустая рука, другой предмет или недоступная интеграция дают false. Собственное общее расширение EliteMobs отдельно добавляет elite_player с боевым тиром, если данные доступны; необязательный адаптер FMM эту подтаблицу не добавляет.

Значения по умолчанию у моста и пропса

Мост модели использует false для blend и loop. В таблице пропса оба по умолчанию true для очереди и повтора. blend управляет очередью, а не плавным переходом между анимациями.

Пример: фильтрация сущностей по типу

local entities = context.world:get_nearby_entities(x, y, z, 10)
for _, entity in ipairs(entities) do
    if entity.is_prop then
        -- Skip props
    elseif entity.is_player then
        entity:damage(5)
    elseif entity.entity_type == "villager" then
        -- Don't hurt villagers
    elseif entity.is_elite then
        entity:damage(20)
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

Поля, специфичные для игрока

Сущности-игроки имеют все поля сущности и живой сущности плюс:

Поле	Тип	Примечания
`game_mode`	string	Игровой режим игрока (`"creative"`, `"survival"`, `"adventure"`, `"spectator"`)

Методы, специфичные для игрока

Форматирование текста

Там, где указана поддержка цветовых кодов, MagmaCore использует встроенный парсер MiniMessage. Можно смешивать коды &, hex &#RRGGBB, <#RRGGBB>, <gradient>, <rainbow> и другие теги. Kyori Adventure не является зависимостью, его API недоступен скриптам и не требуется.

Методы преобразуют текст в строку с обычными цветовыми кодами. Цвета, градиенты и оформление отображаются, а интерактивные теги (<hover>, <click>, <insert>, <font>, <key>, <lang>) разбираются без эффекта. Общие форматы описаны в цветовых кодах.

Метод	Возвращает	Примечания
`send_message(msg)`	void	Отправляет игроку сообщение в чат. Поддерживает цветовые коды.
`chat(text)`	void	Передаёт текст с обработанными цветами в чат Bukkit, включая команды со слешем от имени игрока
`get_held_item()`	table или nil	Возвращает `{type, amount, display_name}` основной руки, либо `nil`. `type` — Bukkit Material в верхнем регистре, например `"GOLD_INGOT"`
`consume_held_item(amount?)`	void	Ставит расходование в очередь для основной руки на момент выполнения. По умолчанию `1`; не сохраняет проверенный предмет и не подтверждает оплату. Передавайте положительное число: отрицательные не отклоняются
`has_item(material, amount?)`	boolean	Возвращает `true`, если у игрока есть как минимум `amount` (по умолчанию `1`) указанного материала где-либо в инвентаре
`get_target_entity([range])`	entity table или nil	Трассирует от глаз по блокам и сущностям, исключая игрока, с размером луча для сущностей 0.5. Игнорирует жидкости и проходимые блоки; дальность по умолчанию 50
`get_eye_location()`	location table	Возвращает таблицу локации на высоте глаз игрока
`get_look_direction()`	table	Возвращает вектор направления `{x, y, z}`, куда смотрит игрок
`send_block_change(x, y, z, material, [ticks])`	boolean	Ставит клиентский блок в очередь; положительные ticks задают сброс. True означает приём в очередь; неверный или неблочный материал даёт false
`reset_block(x, y, z)`	boolean	Ставит восстановление отображения настоящего блока в очередь и возвращает true
`sleep(x, y, z)`	void	Ставит в очередь настоящую белую кровать и попытку сна. При пробуждении или отключении восстанавливает только BlockData, не содержимое блока
`wake_up()`	void	Будит спящего игрока.

Отложенные изменения и сброс блоков читают мир игрока при выполнении: не полагайтесь на восстановление нужного блока после перехода в другой мир. Очистка сна проверяется через 20 тиков, затем каждые 10. Эти задачи не принадлежат context.scheduler.

Методы UI для игрока

Это методы общей таблицы игрока. Таблицы игроков сил боссов имеют другие сигнатуры UI, указанные в справочнике API. Общие полосы привязаны к игроку внутри копии MagmaCore плагина, а не к скрипту. Таймер истечения убирает только ту полосу или повторяющуюся панель действий, которая его запустила, поэтому старое истечение не убирает более новую. Таймеры Bukkit не принадлежат context.scheduler.

`player:show_boss_bar(text, [color], progress, [ticks])`

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

Параметр	Тип	По умолчанию	Примечания
`text`	string	обязательно	Отображаемый текст. Поддерживает цветовые коды.
`color`	string	`"WHITE"`	Цвет полосы. Один из: `"RED"`, `"BLUE"`, `"GREEN"`, `"YELLOW"`, `"PURPLE"`, `"PINK"`, `"WHITE"`
`progress`	number	обязательно	Заполнение от `0.0` (пусто) до `1.0` (полно)
`ticks`	int	`-1`	Положительное значение планирует удаление; иначе полоса остаётся до скрытия или замены

`player:hide_boss_bar()`

Убирает полосу босса с экрана игрока. Параметров не принимает.

`player:show_action_bar(text, [ticks])`

Показывает текст в области панели действий (над хотбаром).

Параметр	Тип	По умолчанию	Примечания
`text`	string	обязательно	Отображаемый текст. Поддерживает цветовые коды.
`ticks`	int	`-1`	Положительное значение повторяет отправку каждые 40 тиков до истечения; иначе отправляет один раз. Новый вызов отменяет предыдущую повторяющуюся задачу

`player:show_title(title, [subtitle], fade_in, stay, fade_out)`

Показывает игроку экранный заголовок.

Параметр	Тип	По умолчанию	Примечания
`title`	string	обязательно	Основной текст заголовка. Поддерживает цветовые коды.
`subtitle`	string	`""`	Подзаголовок под основным заголовком. Опционально.
`fade_in`	int	обязательно	Длительность появления в тиках
`stay`	int	обязательно	Сколько заголовок остаётся на экране в тиках
`fade_out`	int	обязательно	Длительность исчезновения в тиках

Что дальше

Для специфичных для плагина хуков, API и рабочих процессов:

EliteMobs: Начало работы | Скрипты NPC | Хуки и жизненный цикл | Боссы и сущности | Мир и окружение | Зоны и цели
FreeMinecraftModels: Начало работы | API пропсов | Примеры

Краткое введение в Lua
Lua-песочница
- Удалённые глобальные переменные
- Доступная стандартная библиотека
Контракт файла
Распространённые имена хуков
Синтаксис методов: : против .
Бюджет выполнения
context.state
context.log
context.cooldowns
context.scheduler
context.world
context.zones
context.event
Вспомогательное пространство имён em
Таблицы сущностей
Методы UI для игрока
Что дальше

Краткое введение в Lua​

Переменные​

Функции​

Проверки if​

nil​

Таблицы​

Возврат определения скрипта​

Комментарии​

Lua-песочница​

Удалённые глобальные переменные​

Доступная стандартная библиотека​

Контракт файла​

Обязательные и необязательные поля верхнего уровня​

Правила валидации​

Где лежат файлы скриптов​

Распространённые имена хуков​

Синтаксис методов: : против .​

Бюджет выполнения​

context.state​

context.log​

context.cooldowns​

cooldowns:check_local(key?, duration)​

cooldowns:local_ready(key?)​

cooldowns:local_remaining(key?)​

cooldowns:set_local(duration, key?)​

cooldowns:global_ready()​

cooldowns:set_global(duration)​

context.scheduler​

scheduler:run_later(ticks, callback)​

scheduler:run_repeating(delay, interval, callback)​

scheduler:cancel(taskId)​

context.world​

world.name​

world:get_block_at(x, y, z)​

world:set_block_at(x, y, z, material)​

world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)​

world:play_sound(sound, x, y, z, volume, pitch)​

world:strike_lightning(x, y, z)​

world:get_time()​

world:set_time(ticks)​

world:get_nearby_entities(x, y, z, radius)​

world:get_nearby_players(x, y, z, radius)​

world:spawn_entity(entity_type, x, y, z)​

world:get_highest_block_y(x, z)​

world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance], [fluid_mode], [blocks_only], [loaded_only])​

world:spawn_firework(x, y, z, colors, [type], [power])​

world:place_temporary_block(x, y, z, material, [ticks], [require_air])​

world:drop_item(x, y, z, material, [amount])​

context.zones​

zones:create_sphere(x, y, z, radius)​

zones:create_cylinder(x, y, z, radius, height)​

zones:create_cuboid(x, y, z, xSize, ySize, zSize)​

zones:watch(handle, onEnterCallback, onLeaveCallback)​

zones:unwatch(handle)​

Пример: триггерная зона по близости​

context.event​

Вспомогательное пространство имён em​

Таблицы сущностей​

Базовые поля сущности​

Базовые методы сущности​

Поля живой сущности​

Методы живой сущности​

Поля интеграции с плагинами​

Поля EliteMobs​

Поля FreeMinecraftModels​

Поля, специфичные для игрока​

Методы, специфичные для игрока​

Методы UI для игрока​

player:show_boss_bar(text, [color], progress, [ticks])​

player:hide_boss_bar()​

player:show_action_bar(text, [ticks])​

player:show_title(title, [subtitle], fade_in, stay, fade_out)​

Что дальше​

Краткое введение в Lua

Переменные

Функции

Проверки `if`

`nil`

Таблицы

Возврат определения скрипта

Комментарии

Lua-песочница

Удалённые глобальные переменные

Доступная стандартная библиотека

Контракт файла

Обязательные и необязательные поля верхнего уровня

Правила валидации

Где лежат файлы скриптов

Распространённые имена хуков

Синтаксис методов: `:` против `.`

Бюджет выполнения

`context.state`

`context.log`

`context.cooldowns`

`cooldowns:check_local(key?, duration)`

`cooldowns:local_ready(key?)`

`cooldowns:local_remaining(key?)`

`cooldowns:set_local(duration, key?)`

`cooldowns:global_ready()`

`cooldowns:set_global(duration)`

`context.scheduler`

`scheduler:run_later(ticks, callback)`

`scheduler:run_repeating(delay, interval, callback)`

`scheduler:cancel(taskId)`

`context.world`

`world.name`

`world:get_block_at(x, y, z)`

`world:set_block_at(x, y, z, material)`

`world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)`

`world:play_sound(sound, x, y, z, volume, pitch)`

`world:strike_lightning(x, y, z)`

`world:get_time()`

`world:set_time(ticks)`

`world:get_nearby_entities(x, y, z, radius)`

`world:get_nearby_players(x, y, z, radius)`

`world:spawn_entity(entity_type, x, y, z)`

`world:get_highest_block_y(x, z)`

`world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance], [fluid_mode], [blocks_only], [loaded_only])`

`world:spawn_firework(x, y, z, colors, [type], [power])`

`world:place_temporary_block(x, y, z, material, [ticks], [require_air])`

`world:drop_item(x, y, z, material, [amount])`

`context.zones`

`zones:create_sphere(x, y, z, radius)`

`zones:create_cylinder(x, y, z, radius, height)`

`zones:create_cuboid(x, y, z, xSize, ySize, zSize)`

`zones:watch(handle, onEnterCallback, onLeaveCallback)`

`zones:unwatch(handle)`

Пример: триггерная зона по близости

`context.event`

Вспомогательное пространство имён `em`

Таблицы сущностей

Базовые поля сущности

Базовые методы сущности

Поля живой сущности

Методы живой сущности

Поля интеграции с плагинами

Поля EliteMobs

Поля FreeMinecraftModels

Поля, специфичные для игрока

Методы, специфичные для игрока

Методы UI для игрока

`player:show_boss_bar(text, [color], progress, [ticks])`

`player:hide_boss_bar()`

`player:show_action_bar(text, [ticks])`

`player:show_title(title, [subtitle], fade_in, stay, fade_out)`

Что дальше