Lua API 2.1

Создавайте свои модули, HUD и интерфейсы. Рисуйте в мире, управляйте ротациями и используйте данные клиента из Lua.

Nameless передаёт скрипту готовые пространства имён: events, modules, render, render3d, player, world, rotation и другие. Импортировать их не нужно.

Что можно написать

• Перетаскиваемый HUD с сохранением позиции.
• Собственный Click GUI с мышью, клавиатурой и текстовым вводом.
• Модуль с bind и стандартными настройками клиента.
• 3D-геометрию, меши и анимации в мировых координатах.
• Свою логику поворотов с отдельной камерой.
• Инструменты на основе снимков игроков, сущностей, блоков и инвентаря.

Среда: Lua 5.2, LuaJ Figura 3.0.8. Вызовы API выполняются на клиентском потоке. os, io, произвольная Java и сетевые запросы не открыты.

Установка и запуск

1. Установите сборку Nameless с Lua API 2.1.
2. Откройте Lua-раздел ClickGUI и нажмите «Папка».
3. Создайте UTF-8 файл с расширением .lua в корне папки.
4. Нажмите «Обновить», затем ЛКМ по скрипту для загрузки.

Стандартная папка Windows: C:\NamelessDLC\client26_3\lua. Параметр nameless.dataDir меняет корень данных.

ЛКМ переключает загрузку, R перезагружает, ПКМ раскрывает настройки ui.*. Скрипты не загружаются автоматически. Ошибки отображаются в Lua-разделе и журнале Minecraft.

Несколько файлов

require("helpers.math") читает lua/helpers/math.lua. Кэш импортов отдельный для каждого скрипта. Выход за пределы папки запрещён.

Скачать примеры и справочник · Скачать полный TXT

Первый скрипт

Сохраните как hello.lua и загрузите через Lua-раздел. Эта надпись появится в игре.

events.on("render", function(e)
    if not player.get() then return end
    render.text("Hello, Nameless", 20, 20, 12, 0xFFFFFFFF)
end)

Функции пространств имён вызываются через точку: player.get(). Методы объектов — через двоеточие: module:is_enabled(). Массивы Lua начинаются с 1, слоты инвентаря — с 0.

Свои модули

modules.create(name, category, description) регистрирует настоящий модуль в клиенте. Он начинается выключенным и появляется в стандартном ClickGUI. Категории: COMBAT, MOVEMENT, PLAYER, OTHER, RENDER.

local m = modules.create("My Module", "RENDER", "My Lua module")
local enabled = m:boolean("Show text", true)
local size = m:slider("Font size", 12, 8, 24, 1)
local mode = m:choice("Mode", "Simple", {"Simple", "Detailed"})
local tint = m:color("Tint", 0xFFFFFFFF)
m:set_key(75) -- K
m:on_enable(function() print("Enabled") end)
m:on_disable(function() print("Disabled") end)
m:on("render", function(e)
    if enabled:get() then
        render.text(mode:get(), 20, 80, size:get(), tint:get())
    end
end)

m:on(event, callback) вызывает обработчик только при включённом модуле. Обычный events.on работает независимо от состояния модулей.

ModuleHandle

is_enabled(), set_enabled(bool), toggle(), get_key(), set_key(code), settings(), setting(name). У созданного модуля также есть on, on_enable, on_disable, boolean, slider, choice, color.

SettingHandle

get([option]), set(value[, option]), info(), visible(), press(). press применим к кнопкам. Значения проверяются по типу и диапазону; выбор должен существовать в choices.

Настройки модулей сохраняются в стандартных конфигах клиента. Загружайте скрипт перед применением конфига с его настройками. ui.* создаёт отдельные постоянные настройки в карточке Lua-скрипта.

События

events.on(name, callback) возвращает id подписки. events.off(id) удаляет её.

action=1 — нажатие, action=0 — отпускание. Коды клавиш совместимы с GLFW: K=75, Insert=260, Escape=256. Кнопки мыши начинаются с 0.

Для повторных действий используйте tick, для задержки — client.after(ms, callback). Таймеры обслуживаются только на тиках игрока. Не задерживайте поток циклами ожидания.

Свой HUD

hud.create(id, x, y, width, height, callback) создаёт HUD. Откройте чат и перетащите элемент мышью. Позиция сохраняется для этого скрипта.

-- Drag in chat. The position is saved for this script.
hud.create("status", 20, 40, 180, 48, function(e)
    local p = player.get()
    if not p then return end
    render.panel(e.x, e.y, e.width, e.height)
    render.text("Nameless / Lua", e.x + 10, e.y + 8, 10, 0xFFFFFFFF)
    render.text(string.format("%s  HP %.0f", p.name, p.health),
        e.x + 10, e.y + 26, 9, 0xFFB8B8B8)
end)

Callback получает x, y, width, height, partial_ticks, editing. Рисуйте с учётом e.x/e.y. Handle поддерживает position(), set_position(x,y), set_visible(bool), remove().

Все 2D-координаты используют фиксированный масштаб 2: окно 1920×1080 даёт область 960×540 независимо от GUI scale Minecraft.

Свой Click GUI

gui.open(title) открывает экран вашего скрипта и освобождает курсор. В gui_render доступны все функции render.*. Вы можете нарисовать любую компоновку и обработать ввод через события.

ui.boolean("Show HUD", true)
ui.slider("Size", 12, 8, 20)
-- GLFW-compatible code for Insert. Escape closes the screen.
events.on("key", function(key)
    if key == 260 then gui.open("My Click GUI") end
end)
events.on("gui_render", function(e)
    local x, y = (e.width - 260) / 2, (e.height - 150) / 2
    render.panel(x, y, 260, 150)
    render.text("My Click GUI", x + 16, y + 16, 13, 0xFFFFFFFF)
    local enabled = gui.checkbox("hud", "Show HUD", ui.get("Show HUD"), x + 16, y + 50, 228)
    if enabled ~= ui.get("Show HUD") then ui.set("Show HUD", enabled) end
    local size = gui.slider("size", "Font size", ui.get("Size"), 8, 20, x + 16, y + 76, 228)
    if size ~= ui.get("Size") then ui.set("Size", size) end
    if gui.button("close", "Close", x + 16, y + 106, 228, 26) then gui.close() end
end)
events.on("render", function(e)
    if ui.get("Show HUD") then render.text("Lua HUD", 20, 20, ui.get("Size"), 0xFFFFFFFF) end
end)

gui.button возвращает true один раз за клик, gui.checkbox — новое значение. Вызовы делайте каждый кадр в gui_render. id задаёт имя элемента. Встроенного автоматического размещения нет: координаты и размеры задаёт скрипт.

Для текстового поля используйте gui_char, для Backspace — gui_key, для прокрутки — gui_scroll. Escape закрывает экран; gui.close() возвращает предыдущий экран. Скрипт управляет только своим экраном.

2D-рендер

Рисуйте в render, gui_render или callback HUD. Доступны прямоугольники, обводки, текст, линии, круги, градиенты, стекло, общий материал HUD и clipping.

events.on("render", function(e)
    render.rect(20, 100, 180, 60, 0xE0181818, 6)
    render.outline(20, 100, 180, 60, 1, 0xFF444444, 6)
    render.with_clip(20, 100, 180, 60, function()
        render.text("Custom rendering", 30, 120, 12, color.rgba(255,255,255))
    end)
end)

Цвета имеют формат 0xAARRGGBB. color.rgba, color.alpha, color.mix помогают собирать и смешивать их. render.with_clip закрывает scissor даже при ошибке.

3D-рендер

Сначала render3d.push(x,y,z) задаёт абсолютную точку мира. Дальнейшие координаты локальные. Парный pop() восстанавливает матрицу. Внутри доступны translate, rotate_x/y/z и scale.

local mod = modules.create("Lua World Marker", "RENDER", "3D marker at the local player")
local height = mod:slider("Height", 1, 0.2, 3, 0.1)
local tint = mod:color("Color", 0x704AC7A1)
mod:set_key(75) -- K. Module starts disabled.
mod:on("render3d", function(e)
    local p = player.get()
    if not p then return end
    render3d.push(p.x - 0.35, p.y, p.z - 0.35)
    render3d.box(0.7, height:get(), 0.7, tint:get())
    render3d.pop()
end)

Меши и освещение

render3d.mesh(vertices) создаёт меш: плоский массив, по девять чисел на треугольник. Создавайте его один раз при загрузке. render3d.draw(id,argb) рисует в текущей матрице. triangle и quad строят геометрию напрямую.

render3d.camera() возвращает координаты и углы камеры, light(x,y,z) — освещённость, shade(factor) — множитель яркости. Геометрия имеет тест глубины: блоки её закрывают. Состояние матриц сбрасывается между скриптами.

Программируемые ротации

API 2.1 даёт контроллер с состоянием и возможность полностью описать алгоритм в Lua. Контроллер принимает EntityHandle другого игрока или точку {x,y,z}.

Настроить динамику и точку наведения

local r = rotation.controller({
    mode = "spring",       -- также linear, exponential, custom
    yaw_speed = 240,       -- градусы в секунду
    pitch_speed = 120,
    acceleration = 1000,   -- градусы / секунду²
    response = 10,
    damping = 1,
    point = "chest",
    prediction = 0.5,      -- тики наблюдаемого движения цели
    visible = true,
    silent = true,
    quantize = true,
    respect_owner = true
})
events.on("tick", function()
    if input.key_down(74) then
        r:update(entities.nearest({range = 16, friends = false}))
    else
        r:release(true)
    end
end)

spring учитывает скорость, ускорение, response и damping. linear использует ограниченную скорость с разгоном. exponential сближается с целью по экспоненте. В режиме custom следующие углы определяет ваш callback.

Свой алгоритм на Lua

Callback получает желаемые углы, ошибки по осям, текущую угловую скорость, dt, цель, точку наведения и постоянную таблицу state. Верните {yaw,pitch} либо nil, чтобы пропустить применение. Дополнительное сглаживание к результату custom не применяется.

-- Hold J to follow another player. Vanilla transmits the resulting rotation.
-- The callback below defines the angular dynamics entirely in Lua.
local controller = rotation.controller({
    mode = "custom",
    point = "chest",
    prediction = 0.5, -- observed target motion, half a tick ahead
    visible = true,
    silent = true,
    quantize = true, -- continuous state retains fractions of a mouse count
    respect_owner = true, -- yield to another active rotation owner
    callback = function(c)
        local s = c.state
        local dt = c.dt
        local distance = c.target and c.target:get_distance() or 4
        local response = distance < 4 and 10 or 7
        -- Critically damped response with a Lua-defined acceleration limit.
        local function axis(error, velocity, speed)
            local acceleration = response * response * error - 2 * response * velocity
            acceleration = math.max(-1200, math.min(1200, acceleration))
            return math.max(-speed, math.min(speed, velocity + acceleration * dt))
        end
        s.yaw_velocity = axis(c.delta_yaw, s.yaw_velocity or 0, 200)
        s.pitch_velocity = axis(c.delta_pitch, s.pitch_velocity or 0, 100)
        return {
            yaw = c.continuous_yaw + s.yaw_velocity * dt,
            pitch = c.continuous_pitch + s.pitch_velocity * dt
        }
    end
})
local target
events.on("tick", function()
    if not input.key_down(74) then
        target = nil
        controller:release(true)
        return
    end
    if not target or not target:is_valid() or not target:is_alive()
        or target:get_distance() > 16 or target:is_friend() then
        target = entities.nearest({range = 16, friends = false, fov = 120, sort = "angle"})
    end
    controller:update(target) -- one update per game tick, dt defaults to 0.05 s
end)
events.on("world", function() target = nil; controller:release(false) end)

Контекст: yaw, pitch, continuous_yaw, continuous_pitch, target_yaw, target_pitch, delta_yaw, delta_pitch, yaw_velocity, pitch_velocity, dt, sensitivity, target, point, state. Для накопления движений меньше шага мыши рассчитывайте следующий угол от continuous_yaw/continuous_pitch.

Точки хитбокса и прогноз

point: nearest, center, eyes, chest, feet, relative. Для relative задайте x/y/z от 0 до 1 внутри хитбокса. Prediction — от 0 до 5 тиков наблюдаемого движения. Partial_ticks — от 0 до 1. Visible=true проверяет выбранную точку и при необходимости ищет доступную точку внутри хитбокса. При отсутствии такой точки update вернёт nil и отпустит свою ротацию.

Методы контроллера

• update(target[,dt=.05]) — расчёт и применение в tick. Повторный вызов за тот же тик не умножает скорость.
• calculate(target[,dt]) — расчёт без применения.
• step(yaw,pitch[,dt]) — расчёт по готовым целевым углам без применения.
• reset([yaw,pitch]) — сброс скорости и Lua-state.
• configure(options) — изменить параметры.
• release([smooth=true]) — отпустить только свою ротацию, сбросить состояние.
• state() — углы, непрерывные углы, скорости, owns_rotation, target_uuid и state.

Dt задаётся в секундах: 0.000001–0.25, по умолчанию 0.05. Контроллер сам не подписывается на события. До 32 контроллеров на скрипт. При respect_owner=true чужая активная ротация не перехватывается: результат содержит blocked=true.

Низкоуровневый API

rotation.apply(yaw,pitch,{silent=true,quantize=false}) применяет ваши углы без скрытого сглаживания и округления. Есть wrap, delta, lerp, angles, direction, quantize. rotation.trace(yaw,pitch,range,entity) проверяет луч по хитбоксу с учётом блока перед целью.

Плавные контроллеры сохраняют доли шага чувствительности отдельно от отправленного угла. Pitch остаётся в пределах −90..90, переход yaw через −180/180 идёт по короткой дуге. При выгрузке освобождается только ротация, принадлежащая этому скрипту или его контроллеру.

Другие игроки и сущности

entities.players() возвращает других загруженных игроков. Себя он исключает по умолчанию. Это handles с методами для чтения актуальных данных конкретного игрока.

for _, enemy in ipairs(entities.players({range = 64})) do
    print(enemy.name,
        enemy:get_health(),          -- текущее HP
        enemy:get_max_health(),      -- максимальное HP
        enemy:get_absorption(),      -- жёлтые сердца
        enemy:get_armor())           -- очки брони

    local armor = enemy:get_equipment()
    print(armor.chest.id, armor.chest.durability_percent)
end

Выбрать нужного игрока

local enemy = entities.nearest({
    range = 16, friends = false, fov = 120,
    sort = "angle", visible = true
})
if enemy and enemy:is_valid() then
    local hp = enemy:get_health()
    local helmet = enemy:get_item("head")
end
local named = entities.by_name("PlayerName")
local same_player = entities.by_uuid("00000000-0000-0000-0000-000000000000")

entities.query выбирает также мобов и другие сущности. Общие фильтры: range, alive, visible, friends, spectators, invisible, fov, sort, limit, predicate. Для query также доступны players_only, living_only, type.

Значения по умолчанию: range=64, alive=true, visible=false, friends=true, spectators=false, invisible=true, fov=360, include_self=false, limit=128. friends=false исключает друзей. Сортировка: distance, health, armor, angle. Predicate получает handle и возвращает boolean.

Методы EntityHandle

Предмет содержит id, name, count, empty, damage, max_damage, remaining_durability, durability_percent, enchanted. get_armor() возвращает очки защиты, а get_equipment() — сами предметы и их прочность.

Handle и снимок — как обновлять данные

Методы каждый раз находят сущность по id, UUID и исходному миру. После удаления или смены мира is_valid() вернёт false, методы данных — nil. Handle не начнёт ссылаться на нового игрока с повторно использованным id.

Поля вроде enemy.health и enemy.x остаются снимком момента получения. Для актуального значения вызывайте enemy:get_health(), enemy:get_position() или enemy:snapshot(). world.players() остаётся прежним API снимков, включая себя.

HP и экипировка берутся из данных, переданных сервером клиенту Minecraft. Скрытые сервером значения API восстановить не может. get_velocity() рассчитывает наблюдаемое движение удалённого игрока, чья локальная физическая velocity может быть нулевой.

HUD другого игрока

-- Other players only. No local-player health is used for this HUD.
local target
events.on("tick", function()
    target = entities.nearest({range = 64, players_only = true})
end)
events.on("world", function() target = nil end)
hud.create("other_player", 20, 140, 240, 94, function(e)
    if not target or not target:is_valid() then return end
    local hp, absorption = target:get_health(), target:get_absorption()
    local armor, equipment = target:get_armor(), target:get_equipment()
    if not hp or not equipment then return end
    render.panel(e.x, e.y, e.width, e.height)
    render.text(target.name, e.x + 10, e.y + 8, 11, 0xFFFFFFFF)
    render.text(string.format("HP %.1f / %.1f + %.1f | Armor %d",
        hp, target:get_max_health(), absorption, armor), e.x + 10, e.y + 29, 9, 0xFFCCCCCC)
    local chest = equipment.chest
    render.text(chest.empty and "Chest: empty" or string.format("%s: %.0f%% durability",
        chest.name, chest.durability_percent), e.x + 10, e.y + 49, 9, 0xFFCCCCCC)
    render.text(string.format("Distance %.1f | Ping %s ms", target:get_distance(),
        tostring(target:get_ping() or "?")), e.x + 10, e.y + 69, 9, 0xFFCCCCCC)
end)

Клиент и настройки

Через modules.list() и module:settings() можно исследовать реальные модули и настройки установленной сборки. Не угадывайте названия режимов — читайте setting:info().

local sprint = modules.get("Sprint")
print(sprint.name, sprint:is_enabled())
for _, setting in ipairs(sprint:settings()) do
    print(setting.name, setting.type)
end
ui.slider("Opacity", 0.8, 0, 1)
local opacity = ui.get("Opacity")
storage.set("counter", storage.get("counter", 0) + 1)

Также доступны инвентарь и контейнеры, локальный и серверный чат, друзья, темы и конфиги. client.window() сообщает FPS и размеры окна, client.server() — текущий сервер, client.screen() — название экрана.

storage хранит собственные числа, строки и boolean в lua/.settings/<filename>.json. Произвольные таблицы не сохраняются. Значения ui.* используют то же хранилище и проходят проверку типа.

Лимиты и выгрузка

• Исходник до 256 KiB; 256 callback и 256 таймеров на скрипт.
• 200 000 Lua-инструкций на вызов; 100 мс загрузка, 20 мс событие.
• 32 собственных модуля, 64 настройки на модуль, 32 HUD на скрипт.
• 64 меша, 4096 треугольников на меш, 30 000 треугольников на 3D-кадр, глубина матриц 32.

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

unload вызывается при штатной выгрузке. После ошибки скрипт уже остановлен: Java-очистка выполнится, но Lua unload не гарантируется. Изменения встроенных модулей, тем, друзей и конфигов автоматически не откатываются.

Компиляция и автономные проверки движка не подтверждают внешний вид и поведение на сервере. Свои скрипты проверяйте в отдельном мире.

events.*

Справочник функций, сформированный из Java-регистраций API 2.1.

client.*

Справочник функций, сформированный из Java-регистраций API 2.1.

chat.*

Справочник функций, сформированный из Java-регистраций API 2.1.

modules.*

Справочник функций, сформированный из Java-регистраций API 2.1.

settings.*

Справочник функций, сформированный из Java-регистраций API 2.1.

player.*

Справочник функций, сформированный из Java-регистраций API 2.1.

world.*

Справочник функций, сформированный из Java-регистраций API 2.1.

inventory.*

Справочник функций, сформированный из Java-регистраций API 2.1.

input.*

Справочник функций, сформированный из Java-регистраций API 2.1.

render.*

Справочник функций, сформированный из Java-регистраций API 2.1.

render3d.*

Справочник функций, сформированный из Java-регистраций API 2.1.

color.*

Справочник функций, сформированный из Java-регистраций API 2.1.

theme.*

Справочник функций, сформированный из Java-регистраций API 2.1.

friends.*

Справочник функций, сформированный из Java-регистраций API 2.1.

config.*

Справочник функций, сформированный из Java-регистраций API 2.1.

storage.*

Справочник функций, сформированный из Java-регистраций API 2.1.

ui.*

Справочник функций, сформированный из Java-регистраций API 2.1.

gui.*

Справочник функций, сформированный из Java-регистраций API 2.1.

hud.*

Справочник функций, сформированный из Java-регистраций API 2.1.

rotation.*

Справочник функций, сформированный из Java-регистраций API 2.1.

entities.*

Справочник функций, сформированный из Java-регистраций API 2.1.