ワールドとプレイヤー

ブロックを読んで変える、エンティティを出現させる、プレイヤーに話しかける。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点灯")
            }
        }
    }
}

ワールド

CraftScript では world()（メインのワールド、または world("minecraft:the_nether")）。Kotlin では Crafting.server?.world(id) または player.world。

メンバー	内容
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)	その速度（1 ティックあたりのブロック数）で進むパーティクル 1 つ。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?)	飛び道具を発射する。ゲーム内のものでも Mod のものでも可。

プレイヤー

メンバー	内容
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）、Mod 独自のデータを持ち、インベントリやチェストの間を移動してもそれらを保ちます。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)) が、それらのエンチャントを持つ同じスタックです。ゲームから読み取ったスタックは、Mod が移動したり with_count や withEnchantments で変更したりしても、API が名前を挙げていないもの（地図の内容、ポーションの効果）を含め、持っているすべてを保ちます（Kotlin の copy は保ちません）。

エフェクト、属性、装備

**エフェクト。**生きているエンティティはどれもゲームのエフェクトを持てます。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) です。

Mod は独自のエフェクトを宣言できます（ブロック、アイテム、レシピを参照）。付与や確認には、これらと同じメンバーを使います。

属性。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 は視線の向きで、長さ 1 ブロックのベクトルです。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	キーを削除、すべて削除、キーを一覧表示。

• **キーはすべての Mod で共有されます。**他の Mod のキーを上書きしないよう、各キーは Mod の id で始めましょう（rubies.visits）。
• **保存される期間：**プレイヤーのデータはプレイヤーとともに残ります。エンティティのデータはエンティティが死ぬと消えます。ブロックのデータは、プレイヤーが壊したとき、または API で置き換えられたときに消えます。
• 数値は小数として保存されます。get_int は整数として返します。
• キーとその関数は 1 つのファイル（lib/storage.craft、Kotlin では storage/）にまとめましょう。Mod の他の部分はキーを知る必要がありません。Mod の整理を参照してください。

サーバー

メンバー	内容
players, worlds, motd, tps, is_dedicated	サーバーの状態。tps は 1 秒あたりの平均ティック数（理想は 20）。
player(name), world(id)	オンラインのプレイヤーやワールドを探します。
broadcast(msg)	全員へのメッセージ。
stop()	保存してサーバーを停止します。
run_command(cmd)	抜け道：ゲームのコマンドを実行します（下記参照）。

抜け道

ゲーム独自の形式を受け付ける関数が 2 つあります。ゲームのコマンドを実行する run_command（CraftScript では run(…)）と、ゲーム内部の形式のデータでエンティティを作る summon(type, location, nbt) です。API がまだ対応していないことのためにありますが、これらの形式は Minecraft のもので、新しいバージョンで変わる可能性があるため、依存した Mod は壊れることがあります。使うのは最小限にして、常に API を優先してください。