Світ і гравці

Читай і змінюй блоки, створюй сутності, спілкуйся з гравцями. У CraftScript назви записуються в snake_case (block_at, max_health); у Kotlin і Java — у camelCase (blockAt, maxHealth). Це ті самі об’єкти.

Приклад

command beacon requires "rubies.beacon" describe "Запалити маяк там, де ти стоїш" {
    if player == null { return "Лише для гравців" }
    let w = player.world
    let at = player.location
    w.set_block(at.block_x, at.block_y, at.block_z, "minecraft:lantern", { hanging: false })
    w.spawn_particle("minecraft:flame", at, 30, 0.5, 0.02)
    w.play_sound(at, "minecraft:block.lantern.place")
    player.title("&eЗапалено", "")
}

object BeaconCommand {
    fun register() {
        Crafting.commands.command("beacon") {
            permission = "rubies.beacon"
            executes { c ->
                val at = c.player.location
                val world = c.player.world
                world.setBlock(at.blockX, at.blockY, at.blockZ, Identifier.parse("minecraft:lantern"), mapOf("hanging" to false))
                world.spawnParticle(Identifier.parse("minecraft:flame"), at, count = 30, spread = 0.5, speed = 0.02)
                world.playSound(at, Identifier.parse("minecraft:block.lantern.place"))
                c.player.title("&eЗапалено")
            }
        }
    }
}

Світ

world() у CraftScript (основний світ або world("minecraft:the_nether")); Crafting.server?.world(id) або player.world у Kotlin.

Член	Що робить
id, players, time, is_raining, data	Id світу, гравці, час доби (читання й запис), чи йде дощ, збережені дані.
block_at(x, y, z)	Блок у цій позиції.
set_block(x, y, z, type)	Ставить блок.
set_block(x, y, z, type, states)	Ставить блок зі станами: { open: true }, { facing: "north" }.
spawn(type, location)	Створює сутність.
drop_item(location, stack)	Викидає предмет на землю.
explode(location, power, fire?)	Вибух.
strike_lightning(location)	Удар блискавки.
spawn_particle(id, location, count?, spread?, speed?)	Частинки.
spawn_particle(id, location, velocity)	Одна частинка, що летить із цією швидкістю, у блоках за тік. Деякі, як minecraft:enchant і minecraft:portal, летять до місця, де їх створено: вони з’являються в location + velocity.
play_sound(location, id, volume?, pitch?)	Звук у певній позиції.
light_at(x, y, z)	Скільки там світла, від 0 до 15.
container_at(x, y, z)	Інвентар скрині, бочки… або null.
set_sign_text(x, y, z, lines)	Текст на табличці.
set_chunk_loaded(cx, cz, loaded)	Тримає чанк завантаженим, навіть коли поруч нікого немає.
entities()	Сутності у світі.
living_near(location, radius)	Живі сутності поруч із місцем, від найближчої до найдальшої.
shoot(projectile, from, velocity, shooter?, damage?)	Запускає снаряд гри або мода.

Гравець

Член	Що робить
name, uuid, is_op, has_crafting_client	Ідентичність; чи встановлено Crafting на клієнті.
send(msg), action_bar(msg), title(title, subtitle?)	Повідомлення в чаті, на панелі дій і на екрані. Кольори через &.
inventory, held_item, give(stack)	Інвентар, предмет у руці, видати предмет.
set_held_item(stack)	Кладе предмет в основну руку замість того, що там було; null спорожнює руку.
health, max_health, food_level, game_mode	Здоров’я, голод (читання й запис) і режим гри.
is_sleeping	Чи спить гравець.
data	Дані, збережені разом із гравцем (нижче).
play_sound(id, volume?, pitch?)	Звук лише для цього гравця.
has_permission(p), kick(reason)	Дозволи; вигнати з сервера.

Player — це також жива сутність (нижче).

Сутності, блоки й інвентарі

Тип	Члени
Entity	uuid, type, world, location, custom_name, is_alive, data, direction, vehicle; teleport, remove, set_rotation, add_tag, has_tag.
LivingEntity	Усе з Entity, а також health, max_health; damage, heal, set_ai, add_effect, remove_effect, has_effect, effects, add_modifier, remove_modifier, attribute, set_attribute, equipment, set_equipment (вимикає або вмикає її власну поведінку).
Block	type, x, y, z, world, location, is_solid, data; set_type, relative(dx, dy, dz).
Inventory	size; get(slot), set(slot, stack), add(stack), count(id), clear().
Location	world, x, y, z, yaw, pitch, block_x, block_y, block_z; add(dx, dy, dz), distance_to(other).

ItemStack містить id, кількість, назву, опис (lore) і власні дані мода та зберігає їх, переміщуючись між інвентарями й скринями. У CraftScript його створюють через item("rubies:ruby", 3); у Kotlin — через ItemStack.of("rubies:ruby", 3) або повний конструктор.

stack.enchantments — це мапа з id кожного зачарування в його рівень (minecraft:sharpness → 3); у зачарованої книги це ті зачарування, які вона дає. У Kotlin stack.withEnchantments(mapOf(Identifier.parse("minecraft:sharpness") to 3)) — той самий стек із цими зачаруваннями. Стек, прочитаний із гри, зберігає все, що в нього є, зокрема те, чого API не називає (вміст мапи, ефекти зілля), коли мод переміщує його або змінює через with_count чи withEnchantments (copy у Kotlin цього не зберігає).

Ефекти, атрибути та спорядження

Ефекти. Будь-яка жива сутність може мати ефекти гри. e.add_effect("minecraft:speed", 8, 3) приймає id, секунди та рівень (1 — це I); необов'язковий останній аргумент, true або false, визначає, чи показувати частинки. Доповнюють це remove_effect(id), has_effect(id) і effects (словник з id у { level, seconds }). У Kotlin: addEffect(Identifier.parse("minecraft:speed"), 8.0, 3) і ActiveEffect(level, seconds).

Мод може оголошувати власні ефекти (див. Блоки, предмети й рецепти); вони накладаються та перевіряються тими самими членами.

Атрибути. attribute("minecraft:movement_speed") повертає поточне значення з урахуванням броні та ефектів. set_attribute("minecraft:scale", 1.6) змінює базове значення: scale, attack_damage, max_health, jump_strength, armor… У Kotlin: attribute(id) і setAttribute(id, value).

command grow() {
    let p = player
    if p.attribute("minecraft:scale") > 1.2 { p.set_attribute("minecraft:scale", 1) } else { p.set_attribute("minecraft:scale", 1.6) }
}

Модифікатори. Модифікатор змінює атрибут, не замінюючи його базового значення, тож кілька модифікаторів додаються, і кожен можна прибрати. e.add_modifier("minecraft:movement_speed", "mymod:frozen_slow", -0.3, "percent_of_base") приймає атрибут, id модифікатора, величину й операцію; e.remove_modifier("minecraft:movement_speed", "mymod:frozen_slow") прибирає його. Повторне додавання з тим самим id замінює його. Операції: add (додає величину), percent_of_base (додає величину, помножену на базове значення) і multiply_total (множить результат на 1 плюс величина). У Kotlin: addModifier(attr, id, amount, ModifierOperation.PERCENT_OF_BASE).

command chill() {
    player.add_modifier("minecraft:movement_speed", "mymod:chill", -0.3, "percent_of_base")
    // later: player.remove_modifier("minecraft:movement_speed", "mymod:chill")
}

Їзда та ефекти по області. entity.vehicle — це те, на чому їде сутність, або null. world.living_near(location, radius) перелічує живі сутності навколо місця, від найближчої до найдальшої, а це те, що потрібно ефектам по області:

command frostwave() {
    let p = player
    for other in p.world.living_near(p.location, 8) {
        if other.type != "minecraft:player" { other.add_effect("mymod:frozen", 4, 1) }
    }
}

Спорядження. e.equipment("head") — предмет, вдягнений у цей слот, або null; e.set_equipment("main_hand", item("minecraft:iron_sword")) його змінює. Слоти: main_hand, off_hand, head, chest, legs і feet. У Kotlin: EquipmentSlot.HEAD, equipment(slot) і setEquipment(slot, stack).

Напрямок і перезарядка. entity.direction — куди дивиться сутність, вектор довжиною в один блок. player.set_cooldown(item, seconds) і player.has_cooldown(item) ставлять предмет на перезарядку та перевіряють її.

Збережені дані

Гравці, сутності, блоки й світи мають data: сховище «ключ — значення», що переживає перезапуски. Воно зберігає рядки, числа, логічні значення, списки й мапи.

// Data that survives restarts. Keys start with the mod id: they're shared by every mod.
const VISITS = "rubies.visits"

fun visits(p: Player): number {
    return p.data.get_int(VISITS) ?? 0
}

fun add_visit(p: Player): number {
    let n = visits(p) + 1
    p.data.set(VISITS, n)
    return n
}

package com.example.rubies.storage

object Visits {
    private const val KEY = "rubies.visits"   // shared by every mod: prefix it with the mod id

    fun of(player: Player): Int = player.data.getInt(KEY) ?: 0

    fun add(player: Player): Int = (of(player) + 1).also { player.data[KEY] = it }
}

CraftScript	Kotlin / Java	Що робить
data.set(k, v) або data[k] = v	data[k] = v	Зберігає значення (null видаляє його).
data[k]	data[k]	Читає значення в тому вигляді, як його було збережено, або null.
data.get_int(k), get_number, get_string, get_boolean	getInt(k), getNumber, getString, getBoolean	Читає значення цього типу або null, якщо його немає.
data.remove(k), data.clear(), data.keys	remove(k), clear(), keys	Видаляє ключ, видаляє все, перелічує ключі.

• Ключі спільні для всіх модів. Починай кожен ключ з id свого мода (rubies.visits), щоб не перезаписати ключі іншого мода.
• Скільки вони живуть: дані гравця лишаються з гравцем; дані сутності зникають, коли вона гине; дані блока зникають, коли гравець його ламає або коли його замінюють через API.
• Числа зберігаються як дробові; get_int повертає їх як цілі.
• Тримай ключі та їхні функції в одному файлі (lib/storage.craft, storage/ у Kotlin): решті мода не треба їх знати. Дивись Як організувати мод.

Сервер

Член	Що робить
players, worlds, motd, tps, is_dedicated	Стан сервера; tps — середня кількість тактів за секунду (20 — ідеально).
player(name), world(id)	Знайти гравця в мережі або світ.
broadcast(msg)	Повідомлення для всіх.
stop()	Зберігає й зупиняє сервер.
run_command(cmd)	Запасний вихід: виконує ігрову команду (дивись нижче).

Запасні виходи

Дві функції приймають власні формати гри: run_command (run(…) у CraftScript), що виконує ігрову команду, і summon(type, location, nbt), що створює сутність із даними у внутрішньому форматі гри. Вони існують для того, чого API поки не охоплює, але ці формати належать Minecraft і можуть змінитися в новій версії, тож мод, що від них залежить, може зламатися. Користуйся ними якомога менше й завжди віддавай перевагу API.