API

声音与粒子

自定义声音和粒子像纹理一样随模组一起提供，你可以像使用游戏自带的一样通过 id 使用它们。声明方式和其他内容相同。

声音

content/sounds.craftCraftScript

sound "ruby_chime" { file: "ruby/chime", subtitle: "A ruby chimes", pitch: 1.2 }

sound "ruby_crumble" { files: ["ruby/crumble_1", "ruby/crumble_2"], subtitle: "Ruby ore crumbles", volume: 0.8 }

属性	取值	默认值
`file`	不带扩展名的文件路径：`ruby/chime` 即模组中的 `sounds/ruby/chime.ogg`	`sounds/<id>.ogg`
`files`	多个路径；每次随机播放其中一个	—
`subtitle`	开启字幕时显示的内容	—
`volume`	0–1	1
`pitch`	音调；1 为原始音调	1

播放方式和任何游戏声音一样：player.play_sound("rubies:ruby_chime") 向单个玩家播放，world().play_sound(location, "rubies:ruby_chime") 在某个位置播放。文件格式为 .ogg。

粒子

content/particles.craftCraftScript

particle "ruby_spark" { textures: ["ruby_spark_0", "ruby_spark_1"], motion: "sparkle" }

属性	取值	默认值
`textures`	`textures/particle/` 中的图片，不带扩展名。多张图片按顺序组成动画	`textures/particle/<id>.png`
`motion`	`float_up`：上升并淡出。`flame`：几乎静止，逐渐缩小。`sparkle`：飘动并闪烁。`drift`：原地漂浮。	`float_up`

通过 id 生成：world().spawn_particle("rubies:ruby_spark", location, 30, 1.5, 0.02)，数量、扩散范围和速度与游戏中的粒子用法相同。若要让单个粒子朝指定方向飞行，改为传入速度：world().spawn_particle("minecraft:end_rod", location, vector(0, 0.1, 0))，单位是格每刻。像 minecraft:enchant 这样被吸向某个位置的粒子，会从 location + velocity 出发，飞向 location。

实际用例

在示例模组中，矿石额外掉落一颗红宝石时，会播放清脆的提示音，并在方块原来的位置迸出火花：

events/mining.craftCraftScript

import { give_rubies } from "/lib/rewards"
import { SETTINGS } from "/settings"

on break(e) {
    let p = e.player
    if p == null { return }
    if e.block.type == "minecraft:diamond_ore" and chance(SETTINGS["bonus_chance"]) {
        give_rubies(p, 1)
        p.play_sound("rubies:ruby_chime")
        p.world.spawn_particle("rubies:ruby_spark", e.block.location, 12, 0.4, 0.02)
    }
}

Kotlin 中

content/Sounds.ktKotlin

package com.example.rubies.content

object Sounds {
    const val CHIME = "rubies:ruby_chime"

    fun register(content: ContentBuilder) {
        content.sound("ruby_chime") { file("ruby/chime"); subtitle = "A ruby chimes"; pitch = 1.2f }
        content.sound("ruby_crumble") { file("ruby/crumble_1"); file("ruby/crumble_2"); subtitle = "Ruby ore crumbles"; volume = 0.8f }
    }
}

content/Particles.ktKotlin

package com.example.rubies.content

object Particles {
    const val SPARK = "rubies:ruby_spark"

    fun register(content: ContentBuilder) {
        content.particle("ruby_spark") { texture("ruby_spark_0"); texture("ruby_spark_1"); motion = ParticleMotion.SPARKLE }
    }
}

在 ContentBuilder 中使用 sound(id) { file(...); subtitle; volume; pitch } 和 particle(id) { texture(...); motion = ParticleMotion.SPARKLE }。播放和生成：player.playSound(id)、world.playSound(at, id)、world.spawnParticle(id, at, count, spread, speed) 和 world.spawnParticle(id, at, Vector(0.0, 0.1, 0.0))。

文件

模组	位置
CraftScript（文件夹）	`mods/rubies/sounds/ruby/chime.ogg`、`mods/rubies/textures/particle/ruby_spark_0.png`
Kotlin 或 Java	`src/main/resources/assets/rubies/sounds/ruby/chime.ogg`、`…/assets/rubies/textures/particle/ruby_spark_0.png`