Le monde et les joueurs

Lire et modifier des blocs, faire apparaître des entités, parler aux joueurs. En CraftScript, les noms utilisent le snake_case (block_at, max_health) ; en Kotlin et en Java, le camelCase (blockAt, maxHealth). Ce sont les mêmes objets.

Un exemple

command beacon requires "rubies.beacon" describe "Allume une balise là où tu te trouves" {
    if player == null { return "Réservé aux joueurs" }
    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("&eAllumé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("&eAllumée")
            }
        }
    }
}

Monde

world() en CraftScript (le monde principal, ou world("minecraft:the_nether")) ; Crafting.server?.world(id) ou player.world en Kotlin.

Membre	Ce qu’il fait
id, players, time, is_raining, data	Id du monde, joueurs, heure de la journée (lecture et écriture), s’il pleut, données enregistrées.
block_at(x, y, z)	Le bloc à cette position.
set_block(x, y, z, type)	Place un bloc.
set_block(x, y, z, type, states)	Place un bloc avec des états : { open: true }, { facing: "north" }.
spawn(type, location)	Fait apparaître une entité.
drop_item(location, stack)	Lâche un objet au sol.
explode(location, power, fire?)	Explosion.
strike_lightning(location)	Éclair.
spawn_particle(id, location, count?, spread?, speed?)	Particules.
spawn_particle(id, location, velocity)	Une particule qui part avec cette vitesse, en blocs par tick. Certaines, comme minecraft:enchant et minecraft:portal, vont vers l’endroit où elles apparaissent : elles viennent de location + velocity.
play_sound(location, id, volume?, pitch?)	Un son à une position.
light_at(x, y, z)	La quantité de lumière, de 0 à 15.
container_at(x, y, z)	L’inventaire d’un coffre, d’un tonneau…, ou null.
set_sign_text(x, y, z, lines)	Texte sur un panneau.
set_chunk_loaded(cx, cz, loaded)	Garde un chunk chargé même quand personne n’est à proximité.
entities()	Les entités du monde.
living_near(location, radius)	Les entités vivantes près d’un endroit, de la plus proche à la plus lointaine.
shoot(projectile, from, velocity, shooter?, damage?)	Lance un projectile, du jeu ou d’un mod.

Joueur

Membre	Ce qu’il fait
name, uuid, is_op, has_crafting_client	Identité ; si le client a Crafting installé.
send(msg), action_bar(msg), title(title, subtitle?)	Messages dans le chat, la barre d’action et à l’écran. Couleurs avec &.
inventory, held_item, give(stack)	Inventaire, l’objet en main, donner un objet.
set_held_item(stack)	Met un objet dans la main principale, à la place de ce qui s’y trouvait ; null la vide.
health, max_health, food_level, game_mode	Santé, faim (lecture et écriture) et mode de jeu.
is_sleeping	Si le joueur dort.
data	Données enregistrées avec le joueur (voir plus bas).
play_sound(id, volume?, pitch?)	Un son pour ce joueur uniquement.
has_permission(p), kick(reason)	Permissions ; expulser.

Un Player est aussi une entité vivante (voir plus bas).

Entités, blocs et inventaires

Type	Membres
Entity	uuid, type, world, location, custom_name, is_alive, data, direction, vehicle ; teleport, remove, set_rotation, add_tag, has_tag.
LivingEntity	Tout ce qu’a 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 (désactive ou réactive son propre comportement).
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).

Un ItemStack contient un id, une quantité, un nom, une description (lore) et les données propres au mod, et les conserve en passant d’un inventaire ou d’un coffre à l’autre. En CraftScript, tu en crées un avec item("rubies:ruby", 3) ; en Kotlin, avec ItemStack.of("rubies:ruby", 3) ou le constructeur complet.

stack.enchantments est une table qui associe l’id de chaque enchantement à son niveau (minecraft:sharpness → 3) ; pour un livre enchanté, ce sont ceux qu’il donne. En Kotlin, stack.withEnchantments(mapOf(Identifier.parse("minecraft:sharpness") to 3)) est la même pile avec ces enchantements. Une pile lue depuis le jeu garde tout ce qu’elle contient, y compris ce que l’API ne nomme pas (le contenu d’une carte, les effets d’une potion), quand un mod la déplace ou la modifie avec with_count ou withEnchantments (le copy de Kotlin ne le conserve pas).

Effets, attributs et équipement

Effets. Toute entité vivante peut avoir les effets du jeu. e.add_effect("minecraft:speed", 8, 3) prend l'id, les secondes et le niveau (1 est I) ; un dernier argument facultatif, true ou false, indique s'il affiche des particules. remove_effect(id), has_effect(id) et effects (une table d'id vers { level, seconds }) complètent l'ensemble. En Kotlin : addEffect(Identifier.parse("minecraft:speed"), 8.0, 3) et ActiveEffect(level, seconds).

Un mod peut déclarer ses propres effets (voir Blocs, objets et recettes) ; on les donne et on les lit avec ces mêmes membres.

Attributs. attribute("minecraft:movement_speed") renvoie la valeur actuelle, armure et effets compris. set_attribute("minecraft:scale", 1.6) change la valeur de base : scale, attack_damage, max_health, jump_strength, armor… En Kotlin : attribute(id) et 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) }
}

Modificateurs. Un modificateur change un attribut sans remplacer sa valeur de base : plusieurs peuvent donc s’additionner et chacun peut être retiré. e.add_modifier("minecraft:movement_speed", "mymod:frozen_slow", -0.3, "percent_of_base") prend l’attribut, un id pour le modificateur, la quantité et l’opération ; e.remove_modifier("minecraft:movement_speed", "mymod:frozen_slow") le retire. Ajouter à nouveau le même id le remplace. Les opérations sont add (ajoute la quantité), percent_of_base (ajoute la quantité multipliée par la valeur de base) et multiply_total (multiplie le résultat par 1 plus la quantité). En 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")
}

Monture et effets de zone. entity.vehicle est ce que l’entité monte, ou null. world.living_near(location, radius) liste les entités vivantes autour d’un endroit, de la plus proche à la plus lointaine, ce dont les effets de zone ont besoin :

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

Équipement. e.equipment("head") est l'objet porté à cet emplacement, ou null ; e.set_equipment("main_hand", item("minecraft:iron_sword")) le change. Les emplacements sont main_hand, off_hand, head, chest, legs et feet. En Kotlin : EquipmentSlot.HEAD, equipment(slot) et setEquipment(slot, stack).

Direction et temps de recharge. entity.direction est la direction de son regard, un vecteur d'un bloc de long. player.set_cooldown(item, seconds) et player.has_cooldown(item) mettent un objet en recharge et le vérifient.

Données enregistrées

Les joueurs, les entités, les blocs et les mondes ont des data : un stockage clé-valeur qui survit aux redémarrages. Il stocke des chaînes, des nombres, des booléens, des listes et des 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	Ce qu’il fait
data.set(k, v) ou data[k] = v	data[k] = v	Enregistre une valeur (null la supprime).
data[k]	data[k]	Lit une valeur telle qu’elle a été enregistrée, ou null.
data.get_int(k), get_number, get_string, get_boolean	getInt(k), getNumber, getString, getBoolean	Lit une valeur de ce type, ou null s’il n’y en a pas.
data.remove(k), data.clear(), data.keys	remove(k), clear(), keys	Supprime une clé, supprime tout, liste les clés.

• Les clés sont partagées par tous les mods. Commence chaque clé par l’id de ton mod (rubies.visits) pour ne pas écraser les clés d’un autre mod.
• Combien de temps elles durent : les données d’un joueur restent avec le joueur ; celles d’une entité disparaissent à sa mort ; celles d’un bloc disparaissent quand un joueur le casse ou quand il est remplacé via l’API.
• Les nombres sont stockés en décimal ; get_int les renvoie en entiers.
• Mets les clés et leurs fonctions dans un seul fichier (lib/storage.craft, storage/ en Kotlin) : le reste du mod n’a pas besoin de les connaître. Voir Organiser un mod.

Serveur

Membre	Ce qu’il fait
players, worlds, motd, tps, is_dedicated	État du serveur ; tps est la moyenne de ticks par seconde (20 est l’idéal).
player(name), world(id)	Trouve un joueur en ligne ou un monde.
broadcast(msg)	Message à tout le monde.
stop()	Sauvegarde et arrête le serveur.
run_command(cmd)	Porte de sortie : exécute une commande du jeu (voir plus bas).

Portes de sortie

Deux fonctions acceptent les formats propres au jeu : run_command (run(…) en CraftScript), qui exécute une commande du jeu, et summon(type, location, nbt), qui crée une entité avec des données au format interne du jeu. Elles existent pour ce que l’API ne couvre pas encore, mais ces formats appartiennent à Minecraft et peuvent changer dans une nouvelle version : un mod qui en dépend peut donc casser. Utilise-les le moins possible et préfère toujours l’API.