Die Welt und die Spieler

Blöcke lesen und ändern, Objekte erscheinen lassen, mit Spielern sprechen. In CraftScript nutzen Namen snake_case (block_at, max_health), in Kotlin und Java camelCase (blockAt, maxHealth). Es sind dieselben Objekte.

Ein Beispiel

command beacon requires "rubies.beacon" describe "Ein Leuchtzeichen an deiner Position entzünden" {
    if player == null { return "Nur für Spieler" }
    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("&eEntzündet", "")
}

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("&eEntzündet")
            }
        }
    }
}

Welt

world() in CraftScript (die Hauptwelt oder world("minecraft:the_nether")), Crafting.server?.world(id) oder player.world in Kotlin.

Member	Was es macht
id, players, time, is_raining, data	ID der Welt, Spieler, Tageszeit (lesen und schreiben), ob es regnet, Speicherdaten.
block_at(x, y, z)	Der Block an dieser Position.
set_block(x, y, z, type)	Setzt einen Block.
set_block(x, y, z, type, states)	Setzt einen Block mit Zuständen: { open: true }, { facing: "north" }.
spawn(type, location)	Lässt ein Objekt erscheinen.
drop_item(location, stack)	Lässt einen Gegenstand auf den Boden fallen.
explode(location, power, fire?)	Explosion.
strike_lightning(location)	Blitzschlag.
spawn_particle(id, location, count?, spread?, speed?)	Partikel.
spawn_particle(id, location, velocity)	Ein einzelnes Partikel, das sich mit dieser Geschwindigkeit bewegt, in Blöcken pro Tick. Manche, wie minecraft:enchant und minecraft:portal, bewegen sich zu dem Ort hin, an dem sie erzeugt werden: sie kommen von location + velocity.
play_sound(location, id, volume?, pitch?)	Ein Geräusch an einer Position.
light_at(x, y, z)	Wie viel Licht es gibt, von 0 bis 15.
container_at(x, y, z)	Das Inventar einer Truhe, eines Fasses…, oder null.
set_sign_text(x, y, z, lines)	Text auf einem Schild.
set_chunk_loaded(cx, cz, loaded)	Hält einen Chunk geladen, auch wenn niemand in der Nähe ist.
entities()	Die Objekte in der Welt.
living_near(location, radius)	Die lebenden Entitäten in der Nähe eines Ortes, die nächste zuerst.
shoot(projectile, from, velocity, shooter?, damage?)	Schießt ein Projektil ab, das des Spiels oder das eines Mods.

Spieler

Member	Was es macht
name, uuid, is_op, has_crafting_client	Identität; ob der Client Crafting installiert hat.
send(msg), action_bar(msg), title(title, subtitle?)	Nachrichten im Chat, in der Aktionsleiste und auf dem Bildschirm. Farben mit &.
inventory, held_item, give(stack)	Inventar, der Gegenstand in der Hand, einen Gegenstand geben.
set_held_item(stack)	Legt einen Gegenstand in die Haupthand, anstelle dessen, was dort war; null leert sie.
health, max_health, food_level, game_mode	Gesundheit, Hunger (lesen und schreiben) und Spielmodus.
is_sleeping	Ob der Spieler schläft.
data	Mit dem Spieler gespeicherte Daten (siehe unten).
play_sound(id, volume?, pitch?)	Ein Geräusch nur für diesen Spieler.
has_permission(p), kick(reason)	Berechtigungen; rauswerfen.

Ein Player ist auch ein lebendes Objekt (siehe unten).

Objekte, Blöcke und Inventare

Typ	Member
Entity	uuid, type, world, location, custom_name, is_alive, data, direction, vehicle; teleport, remove, set_rotation, add_tag, has_tag.
LivingEntity	Alles aus 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 (schaltet das eigene Verhalten aus oder ein).
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).

Ein ItemStack enthält eine ID, eine Anzahl, einen Namen, eine Beschreibung (lore) und die eigenen Daten der Mod und behält sie, während er durch Inventare und Truhen wandert. In CraftScript erstellst du einen mit item("rubies:ruby", 3), in Kotlin mit ItemStack.of("rubies:ruby", 3) oder dem vollständigen Konstruktor.

stack.enchantments ist eine Map von der ID jeder Verzauberung zu ihrer Stufe (minecraft:sharpness → 3); bei einem verzauberten Buch sind es die, die es verleiht. In Kotlin ist stack.withEnchantments(mapOf(Identifier.parse("minecraft:sharpness") to 3)) derselbe Stapel mit diesen Verzauberungen. Ein aus dem Spiel gelesener Stapel behält alles, was er hat, auch das, was die API nicht benennt (den Inhalt einer Karte, die Effekte eines Tranks), wenn eine Mod ihn verschiebt oder mit with_count oder withEnchantments ändert (das copy von Kotlin behält es nicht).

Effekte, Attribute und Ausrüstung

Effekte. Jede lebende Entität kann die Effekte des Spiels haben. e.add_effect("minecraft:speed", 8, 3) nimmt die Id, die Sekunden und die Stufe (1 ist I); ein optionales letztes Argument, true oder false, legt fest, ob Partikel gezeigt werden. Dazu gehören remove_effect(id), has_effect(id) und effects (eine Map von Id auf { level, seconds }). In Kotlin: addEffect(Identifier.parse("minecraft:speed"), 8.0, 3) und ActiveEffect(level, seconds).

Ein Mod kann eigene Effekte deklarieren (siehe Blöcke, Gegenstände und Rezepte); sie werden mit denselben Mitgliedern vergeben und gelesen.

Attribute. attribute("minecraft:movement_speed") gibt den aktuellen Wert zurück, mit Rüstung und Effekten. set_attribute("minecraft:scale", 1.6) ändert den Basiswert: scale, attack_damage, max_health, jump_strength, armor … In Kotlin: attribute(id) und 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) }
}

Modifikatoren. Ein Modifikator ändert ein Attribut, ohne seinen Basiswert zu ersetzen, sodass sich mehrere addieren können und jeder einzeln entfernt werden kann. e.add_modifier("minecraft:movement_speed", "mymod:frozen_slow", -0.3, "percent_of_base") nimmt das Attribut, eine Id für den Modifikator, den Betrag und die Operation; e.remove_modifier("minecraft:movement_speed", "mymod:frozen_slow") entfernt ihn. Wird dieselbe Id erneut hinzugefügt, ersetzt sie den alten. Die Operationen sind add (addiert den Betrag), percent_of_base (addiert den Betrag mal den Basiswert) und multiply_total (multipliziert das Ergebnis mit 1 plus dem Betrag). In 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")
}

Reiten und Flächeneffekte. entity.vehicle ist das, worauf die Entität reitet, oder null. world.living_near(location, radius) listet die lebenden Entitäten rund um einen Ort auf, die nächste zuerst, was Flächeneffekte brauchen:

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

Ausrüstung. e.equipment("head") ist der dort getragene Gegenstand oder null; e.set_equipment("main_hand", item("minecraft:iron_sword")) ändert ihn. Die Plätze sind main_hand, off_hand, head, chest, legs und feet. In Kotlin: EquipmentSlot.HEAD, equipment(slot) und setEquipment(slot, stack).

Blickrichtung und Abklingzeiten. entity.direction ist die Blickrichtung, ein Vektor von einem Block Länge. player.set_cooldown(item, seconds) und player.has_cooldown(item) setzen eine Abklingzeit und prüfen sie.

Speicherdaten

Spieler, Objekte, Blöcke und Welten haben data: einen Schlüssel-Wert-Speicher, der Neustarts übersteht. Er speichert Strings, Zahlen, Wahrheitswerte, Listen und Maps.

// 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	Was es macht
data.set(k, v) oder data[k] = v	data[k] = v	Speichert einen Wert (null löscht ihn).
data[k]	data[k]	Liest einen Wert so, wie er gespeichert wurde, oder null.
data.get_int(k), get_number, get_string, get_boolean	getInt(k), getNumber, getString, getBoolean	Liest einen Wert dieses Typs oder null, wenn keiner da ist.
data.remove(k), data.clear(), data.keys	remove(k), clear(), keys	Löscht einen Schlüssel, löscht alles, listet die Schlüssel auf.

• Schlüssel teilen sich alle Mods. Beginne jeden Schlüssel mit der ID deiner Mod (rubies.visits), damit du nicht die Schlüssel einer anderen Mod überschreibst.
• Wie lange sie halten: Die Daten eines Spielers bleiben beim Spieler, die Daten eines Objekts verschwinden, wenn es stirbt, die Daten eines Blocks verschwinden, wenn ein Spieler ihn abbaut oder er über die API ersetzt wird.
• Zahlen werden als Dezimalzahlen gespeichert, get_int gibt sie als Ganzzahlen zurück.
• Leg die Schlüssel und ihre Funktionen in eine einzige Datei (lib/storage.craft, storage/ in Kotlin): Der Rest der Mod muss sie nicht kennen. Siehe Eine Mod organisieren.

Server

Member	Was es macht
players, worlds, motd, tps, is_dedicated	Zustand des Servers; tps ist der Durchschnitt der Ticks pro Sekunde (20 ist ideal).
player(name), world(id)	Einen Spieler, der online ist, oder eine Welt finden.
broadcast(msg)	Nachricht an alle.
stop()	Speichert und stoppt den Server.
run_command(cmd)	Notausgang: führt einen Spielbefehl aus (siehe unten).

Notausgänge

Zwei Funktionen akzeptieren die eigenen Formate des Spiels: run_command (run(…) in CraftScript), das einen Spielbefehl ausführt, und summon(type, location, nbt), das ein Objekt mit Daten im internen Format des Spiels erstellt. Sie gibt es für das, was die API noch nicht abdeckt, aber diese Formate gehören Minecraft und können sich in einer neuen Version ändern, also kann eine Mod, die von ihnen abhängt, kaputtgehen. Nutze sie so wenig wie möglich und bevorzuge immer die API.