Świat i gracze

Czytaj i zmieniaj bloki, przywołuj byty, rozmawiaj z graczami. W CraftScript nazwy używają snake_case (block_at, max_health); w Kotlinie i Javie camelCase (blockAt, maxHealth). To te same obiekty.

Przykład

command beacon requires "rubies.beacon" describe "Zapala latarnię tam, gdzie stoisz" {
    if player == null { return "Tylko dla graczy" }
    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("&eZapalono", "")
}

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("&eZapalono")
            }
        }
    }
}

Świat

world() w CraftScript (główny świat lub world("minecraft:the_nether")); Crafting.server?.world(id) lub player.world w Kotlinie.

Składowa	Co robi
id, players, time, is_raining, data	Id świata, gracze, pora dnia (odczyt i zapis), czy pada deszcz, zapisane dane.
block_at(x, y, z)	Blok na tej pozycji.
set_block(x, y, z, type)	Stawia blok.
set_block(x, y, z, type, states)	Stawia blok ze stanami: { open: true }, { facing: "north" }.
spawn(type, location)	Przywołuje byt.
drop_item(location, stack)	Upuszcza przedmiot na ziemię.
explode(location, power, fire?)	Eksplozja.
strike_lightning(location)	Piorun.
spawn_particle(id, location, count?, spread?, speed?)	Cząsteczki.
spawn_particle(id, location, velocity)	Jedna cząsteczka lecąca z tą prędkością, w blokach na tick. Niektóre, jak minecraft:enchant i minecraft:portal, lecą ku miejscu, w którym się pojawiają: zaczynają w location + velocity.
play_sound(location, id, volume?, pitch?)	Dźwięk w danym miejscu.
light_at(x, y, z)	Ile jest światła, od 0 do 15.
container_at(x, y, z)	Ekwipunek skrzyni, beczki… lub null.
set_sign_text(x, y, z, lines)	Tekst na tabliczce.
set_chunk_loaded(cx, cz, loaded)	Utrzymuje chunk wczytany, nawet gdy nikogo nie ma w pobliżu.
entities()	Byty w świecie.
living_near(location, radius)	Żywe jednostki w pobliżu miejsca, od najbliższej.
shoot(projectile, from, velocity, shooter?, damage?)	Wystrzeliwuje pocisk, z gry lub z moda.

Gracz

Składowa	Co robi
name, uuid, is_op, has_crafting_client	Tożsamość; czy klient ma zainstalowany Crafting.
send(msg), action_bar(msg), title(title, subtitle?)	Wiadomości na czacie, na pasku akcji i na ekranie. Kolory przez &.
inventory, held_item, give(stack)	Ekwipunek, przedmiot w ręce, przekazanie przedmiotu.
set_held_item(stack)	Wkłada przedmiot do głównej ręki w miejsce poprzedniego; null ją opróżnia.
health, max_health, food_level, game_mode	Zdrowie, głód (odczyt i zapis) i tryb gry.
is_sleeping	Czy gracz śpi.
data	Dane zapisane z graczem (niżej).
play_sound(id, volume?, pitch?)	Dźwięk tylko dla tego gracza.
has_permission(p), kick(reason)	Uprawnienia; wyrzucenie z serwera.

Player jest też żywym bytem (niżej).

Byty, bloki i ekwipunki

Typ	Składowe
Entity	uuid, type, world, location, custom_name, is_alive, data, direction, vehicle; teleport, remove, set_rotation, add_tag, has_tag.
LivingEntity	Wszystko z Entity plus health, max_health; damage, heal, set_ai, add_effect, remove_effect, has_effect, effects, add_modifier, remove_modifier, attribute, set_attribute, equipment, set_equipment (wyłącza lub włącza własne zachowanie).
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 przechowuje id, liczbę, nazwę, opis (lore) i własne dane moda, i zachowuje je, gdy przemieszcza się między ekwipunkami i skrzyniami. W CraftScript tworzysz go przez item("rubies:ruby", 3); w Kotlinie przez ItemStack.of("rubies:ruby", 3) lub pełny konstruktor.

stack.enchantments to mapa z id każdego zaklęcia na jego poziom (minecraft:sharpness → 3); w zaklętej księdze to te, które daje. W Kotlinie stack.withEnchantments(mapOf(Identifier.parse("minecraft:sharpness") to 3)) to ten sam stos z tymi zaklęciami. Stos odczytany z gry zachowuje wszystko, co ma, także to, czego API nie nazywa (zawartość mapy, efekty mikstury), gdy mod go przenosi lub zmienia przez with_count albo withEnchantments (copy w Kotlinie tego nie zachowuje).

Efekty, atrybuty i wyposażenie

Efekty. Każda żywa jednostka może mieć efekty z gry. e.add_effect("minecraft:speed", 8, 3) przyjmuje id, sekundy i poziom (1 to I); opcjonalny ostatni argument, true lub false, określa, czy pokazywać cząsteczki. Dopełniają to remove_effect(id), has_effect(id) i effects (mapa z id na { level, seconds }). W Kotlinie: addEffect(Identifier.parse("minecraft:speed"), 8.0, 3) i ActiveEffect(level, seconds).

Mod może deklarować własne efekty (zobacz Bloki, przedmioty i receptury); nadaje się je i odczytuje tymi samymi członkami.

Atrybuty. attribute("minecraft:movement_speed") zwraca aktualną wartość, z pancerzem i efektami. set_attribute("minecraft:scale", 1.6) zmienia wartość bazową: scale, attack_damage, max_health, jump_strength, armor… W Kotlinie: attribute(id) i 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) }
}

Modyfikatory. Modyfikator zmienia atrybut bez zastępowania jego wartości bazowej, więc kilka może się sumować, a każdy można zdjąć. e.add_modifier("minecraft:movement_speed", "mymod:frozen_slow", -0.3, "percent_of_base") przyjmuje atrybut, id modyfikatora, wartość i operację; e.remove_modifier("minecraft:movement_speed", "mymod:frozen_slow") go usuwa. Dodanie tego samego id ponownie go zastępuje. Operacje to add (dodaje wartość), percent_of_base (dodaje wartość razy wartość bazowa) i multiply_total (mnoży wynik przez 1 plus wartość). W Kotlinie: 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")
}

Jazda i efekty obszarowe. entity.vehicle to to, na czym jednostka jedzie, albo null. world.living_near(location, radius) wypisuje żywe jednostki wokół miejsca, od najbliższej, czego potrzebują efekty obszarowe:

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) }
    }
}

Wyposażenie. e.equipment("head") to przedmiot noszony w tym miejscu albo null; e.set_equipment("main_hand", item("minecraft:iron_sword")) go zmienia. Miejsca to main_hand, off_hand, head, chest, legs i feet. W Kotlinie: EquipmentSlot.HEAD, equipment(slot) i setEquipment(slot, stack).

Kierunek i czasy odnowienia. entity.direction to kierunek, w którym patrzy jednostka, wektor długości jednego bloku. player.set_cooldown(item, seconds) i player.has_cooldown(item) nakładają czas odnowienia na przedmiot i go sprawdzają.

Zapisane dane

Gracze, byty, bloki i światy mają data: magazyn klucz-wartość, który przetrwa restarty. Przechowuje napisy, liczby, wartości logiczne, listy i mapy.

// 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	Co robi
data.set(k, v) lub data[k] = v	data[k] = v	Zapisuje wartość (null ją usuwa).
data[k]	data[k]	Odczytuje wartość tak, jak ją zapisano, lub null.
data.get_int(k), get_number, get_string, get_boolean	getInt(k), getNumber, getString, getBoolean	Czyta wartość tego typu lub null, jeśli jej nie ma.
data.remove(k), data.clear(), data.keys	remove(k), clear(), keys	Usuwa klucz, usuwa wszystko, wyświetla klucze.

• Klucze są wspólne dla wszystkich modów. Zaczynaj każdy klucz od id swojego moda (rubies.visits), żeby nie nadpisać kluczy innego moda.
• Jak długo trwają: dane gracza zostają z graczem; dane bytu znikają, gdy ten zginie; dane bloku znikają, gdy gracz go zniszczy lub gdy zostanie zastąpiony przez API.
• Liczby są zapisywane jako dziesiętne; get_int zwraca je jako całkowite.
• Umieść klucze i ich funkcje w jednym pliku (lib/storage.craft, storage/ w Kotlinie): reszta moda nie musi ich znać. Zobacz Porządkowanie moda.

Serwer

Składowa	Co robi
players, worlds, motd, tps, is_dedicated	Stan serwera; tps to średnia liczba ticków na sekundę (20 to ideał).
player(name), world(id)	Znajduje gracza online lub świat.
broadcast(msg)	Wiadomość do wszystkich.
stop()	Zapisuje i zatrzymuje serwer.
run_command(cmd)	Furtka awaryjna: wykonuje polecenie gry (zobacz niżej).

Furtki awaryjne

Dwie funkcje przyjmują własne formaty gry: run_command (run(…) w CraftScript), które wykonuje polecenie gry, i summon(type, location, nbt), które tworzy byt z danymi w wewnętrznym formacie gry. Istnieją dla tego, czego API jeszcze nie obejmuje, ale te formaty należą do Minecrafta i mogą się zmienić w nowej wersji, więc mod, który od nich zależy, może się zepsuć. Używaj ich jak najmniej i zawsze wybieraj API.