Скрипты Astral — это обычные файлы Kotlin с расширением .kts, которые клиент компилирует прямо во время игры. Каждый скрипт становится полноценным модулем: со своим именем, настройками, биндом и переключателем в меню. Сохранил файл, написал .script reload — через полсекунды изменения уже в игре, перезапуск не нужен.

Положи файл с расширением .kts в папку astralvisuals/scripts внутри папки с игрой и напиши в чат .script reload.

name("Hello Astral")
description("Печатает здоровье раз в секунду")

val period = slider("Каждые N тиков", 20, 1, 100)

var ticks = 0

onEnable { ticks = 0 }

on<TickEvent> {
    if (!inGame) return@on

    ticks++
    if (ticks % period.intValue() != 0) return@on

    print("hp ${player.health()} из ${player.maxHealth()}")
}

Импорты не нужны: всё API доступно напрямую. Скрипт появится в меню в разделе Scripts — там же будет ползунок «Каждые N тиков» и бинд.

Объявляй настройки на верхнем уровне файла, а не внутри обработчика: тело скрипта выполняется один раз, и настройка, созданная в тике, будет пересоздаваться с потерей сохранённого значения.

val enabled = checkBox("Включить", true)
val delay   = slider("Задержка", 5, 1, 20)          // целые
val chance  = slider("Шанс", 0.5, 0.0, 1.0, 0.05)   // дробные, с шагом
val band    = rangeSlider("Диапазон", 3.0, 6.0, 0.0, 10.0)  // две ручки на одной шкале
val label   = input("Подпись", "текст")
val colour  = colorPicker("Цвет", 0xFF00FF88.toInt())
val mode    = selectable("Режим", "Всегда", "На земле", "В воздухе")
val aim     = hotkey("Прицелиться", -1)             // клавиша, -1 = не назначена
val reset   = button("Сбросить счётчик") { count = 0 }

delay.visibleWhen { enabled.on() }
enabled.onChange { print("теперь " + enabled.on()) }

rangeSlider — «от и до»

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

val delay = rangeSlider("Задержка", 200.0, 450.0, 50.0, 1000.0, 10.0)

on<TickEvent> {
    // ради этого он и нужен: «попадает ли число в выбранную полосу»
    if (!delay.contains(sinceLastHit)) return@on
    // и случайная величина внутри полосы — для разброса
    nextDelay = delay.random()
}

У value() здесь нижний конец, а не пара: у всех остальных настроек value() — обычное число или строка, и скрипт, который до него дотянулся, не должен получать объект, с которым нечего делать. Явно — low() и high().

hotkey и button

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

val aim = hotkey("Прицелиться", -1)

on<KeyEvent> {
    if (it.pressed() && aim.matches(it.key())) rotations.lookAt(target)
}

button(...) значения не хранит — просто выполняет переданный код по нажатию. Обработчик выполняется в клиентском потоке, так что внутри действуют те же правила, что и в обработчике события: никаких длинных циклов.

var found = 0
val dump = button("Показать найденное") { chat.print("найдено: $found") }

Подписка — on<ИмяСобытия> { }. Внутри доступен объект события; выйти раньше времени — return@on.

on<AttackEvent> { e ->
    if (e.target().effectiveHealth() > 20f) e.cancel()
}

// с приоритетом: FIRST видит событие раньше модулей клиента
on<TickEvent>(Priority.FIRST) { }
on<MoveEvent>(Priority.LAST, ignoreCancelled = true) { }

Мир и взаимодействие

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

// авто-ответ на приглашение в группу
on<ChatReceiveEvent> {
    if (it.contains("пригласил вас в группу")) chat.send("/group accept")
}

// не давать сломать то, что стоит на защищённой территории
on<BlockAttackEvent> {
    if (it.y() < 40) it.cancel()
}

// счётчик, который переживает смену мира правильно
var broken = 0
on<BlockBreakEvent> { if (it.isA("diamond_ore")) broken++ }
on<WorldLoadEvent> { broken = 0 }

Имена экранов — это устойчивые идентификаторы, а не имена классов: inventory, creative, chest, shulker, hopper, crafting, furnace, brewing, anvil, grindstone, stonecutter, loom, cartography, enchanting, beacon, merchant, horse, container — нераспознанный контейнер, а также chat, pause, death, title, disconnected, sign, other. Пустая строка — вернулись в игру.

Локальный игрок. Вне мира всё возвращает нули и false, а не падает — но начинать обработчик с if (!inGame) return@on всё равно правильно.

val ground = world.block(player.position().add(0.0, -1.0, 0.0))
if (ground.isA("obsidian")) print("стоим на обсидиане")

val threat = world.nearestEntity(16.0) { it.isPlayer() && it.effectiveHealth() < 10f }

Сущность: name() id() typeId() position() distanceTo() health() effectiveHealth() alive() isPlayer() isSelf() sneaking() sprinting() invisible() width() height()

Слоты нумеруются как в игре: 0–8 хотбар, 9–35 основная сетка, 36–39 броня, 40 вторая рука. Поиск возвращает ScriptInventory.NOT_FOUND, то есть -1.

val slot = inventory.find { it.food() && it.nutrition() >= 4 }
if (slot in 0..8) control.selectSlot(slot)

val best = inventory.findBest { it.enchantmentLevel("sharpness").toDouble() }

Предмет: empty() id() name() isA() displayName() count() damage() maxDamage() durability() durabilityFraction() enchanted() enchantmentLevel("sharpness") food() nutrition() saturation()

rotations.lookAt(target)
if (rotations.angleTo(target.position()) < 30f) interaction.attack(target)

usingSlot — временно взять другой предмет

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

val pearl = inventory.findInHotbar("ender_pearl")
if (pearl != -1) control.usingSlot(pearl) { interaction.useItem() }

Это не «тихая» смена в смысле пакетов: сервер видит смену слота, действие и смену обратно — ровно то же, что увидел бы, сделай это игрок руками. Так задумано: вариант, прячущий подмену от сервера, — именно то, что ищут анти-читы, и он не стоит той поддержки, которой обойдётся. Неверный слот или слот, который уже выбран, просто выполняют блок без подмены.

// правильно — обе стороны, каждый тик
val нужно = player.health() < 6f
if (нужно != player.sneaking()) control.sneaking(нужно)

// неправильно — присядет и останется сидеть навсегда
if (player.health() < 6f) control.sneaking(true)

Только внутри on<Render2DEvent> — в другом месте вызовы просто ничего не нарисуют. Цвета — упакованные ARGB-числа, ровно то, что отдаёт colorPicker.

on<Render2DEvent> { e ->
    if (!inGame) return@on

    val w = 140f
    val x = e.width() - w - 10f

    render.blur(x, 10f, w, 46f, 6f, 6f, render.rgba(20, 20, 20, 140))

    val hp = player.health() / player.maxHealth()
    val bar = render.mix(render.rgb(220, 60, 60), render.rgb(0, 255, 136), hp)
    render.roundedRect(x + 8f, 20f, (w - 16f) * hp, 6f, 3f, bar)

    render.styledText(player.name(), x + 8f, 32f, 8f, render.rgb(255, 255, 255), "semibold")
}

Координаты — в масштабируемом пространстве интерфейса игры. Привязывайся к e.width() и e.height(), иначе при другом масштабе GUI всё уедет. blur читает кадровый буфер: одна панель — нормально, размытие на каждую сущность — нет.

Скрипты выполняются в песочнице. Разрешено всё нужное: стандартная библиотека Kotlin, коллекции, строки, математика, Random, java.time, java.math — и, конечно, всё API Astral.

Запрещено и не заработает:

• файлы и папки — вместо этого storage;
• сеть;
• потоки и таймеры — вместо этого afterTicks и timer();
• рефлексия и загрузка классов;
• запуск процессов, System, доступ к внутренностям клиента.

Обработчик, упавший пять раз подряд, выключает скрипт: иначе ошибка в тике писала бы в консоль двадцать строк в секунду. Одно успешное выполнение сбрасывает счётчик. Медленные обработчики отмечаются предупреждением в консоли.

Автоматическая еда на низком здоровье

name("Auto Eat")

val threshold = slider("Здоровье", 8.0, 1.0, 20.0, 0.5)
val cooldown  = timer()

on<TickEvent> {
    if (!inGame) return@on
    if (player.health() + player.absorption() > threshold.value()) return@on
    if (player.usingItem() || !cooldown.passed(1500)) return@on

    val slot = inventory.find { it.food() && it.nutrition() >= 4 }
    if (slot !in 0..8) return@on

    control.selectSlot(slot)
    interaction.useItem()
    cooldown.reset()
}

Счётчик убийств, который переживает перезапуск

name("Kill Counter")

var kills = storage.getInt("kills", 0)

on<AttackEvent> { e ->
    if (e.target().effectiveHealth() > 2f) return@on
    kills++
    storage.put("kills", kills)
    notify("Kill Counter", "всего: $kills", "success")
}

onUnload { storage.put("kills", kills) }

Предупреждение о слабом противнике рядом

name("Low Health Warning")

val radius = slider("Радиус", 16, 4, 64)
var last = ""

on<TickEvent> {
    if (!inGame) return@on

    val weak = world.nearestEntity(radius.value().toDouble()) {
        it.isPlayer() && it.alive() && it.effectiveHealth() < 6f
    } ?: return@on

    if (weak.name() == last) return@on
    last = weak.name()
    chat.overlay("${weak.name()} — ${weak.effectiveHealth().toInt()} hp")
}