配置与规则

本页以当前代码实现为准，描述服务端音效配置目录、字段与默认行为。

1. 目录结构

/plugins/Behemiron/sound/
  config.yml
  combat.yml
  chemdah.yml
  AmbientSounds/**/*.yml
  AreaSounds/**/*.yml
  DungeonSounds/**/*.yml
  OtherSounds/**/*.yml

加载入口：SoundConfigRepository.loadAll()。

2. 路径规则（强制）

所有音轨路径都必须是相对路径：

• 正确：ui/confirm、ambient/forest/day
• 错误：behemiron:ui/confirm、sound/ui/confirm、sounds/ui/confirm

写法	结果
ui/confirm	合法
ambient/forest/day	合法
behemiron:ui/confirm	非法
sound/ui/confirm	非法

3. 全局规则（config.yml）

AmbientInterval: 20~60
AreaInterval: 20~60
DungeonInterval: 20~60
SceneInterval: 20~60
CombatRange: 16
CombatHold: 8s
CombatScanInterval: 1s
CombatLoopInterval: 20~40
BlockVanillaSources:
  - AMBIENT
  - MUSIC
  - WEATHER

字段	说明	默认值
AmbientInterval	环境音随机间隔	20~60 秒
AreaInterval	区域音随机间隔	20~60 秒
DungeonInterval	地牢音随机间隔	20~60 秒
SceneInterval	场景音随机切换间隔	20~60 秒
CombatRange	战斗检测半径	16.0
CombatHold	战斗保持时间	8s
CombatScanInterval	战斗检测周期	1s
CombatLoopInterval	战斗循环换曲间隔	20~40 秒
BlockVanillaSources	需要屏蔽的原版 SoundSource	[AMBIENT,MUSIC,WEATHER]

时间写法支持：20~60、20s~60s、500ms~1500ms、1m~2m。

4. 通用音轨结构

音轨可出现在 pool / tracks 列表，或单条对象里。

- file: "ambient/forest"
  volume: 0.6
  pitch: 1
  loop: false
  weight: 2
  stream: false
  bus: environment
  source: AMBIENT

字段	类型	默认值	说明
file / id / sound	string	必填	音效路径（单条对象允许三者；pool 内对象允许 file/id）
volume	number	1.0	音量
pitch	number	1.0	音高
loop	boolean	false	是否循环
weight	int	1	池化随机权重
stream	boolean	false	是否流式播放
bus	string	继承外层默认	逻辑总线
source	string	继承外层默认	Minecraft SoundSource

5. Ambient（AmbientSounds/*.yml）

ExampleAmbient:
  world: "minecraft:overworld"
  match: glob
  time: [day, night]
  weather: [clear, rain]
  interval: 20~60
  bus: environment
  source: AMBIENT
  pool:
    - file: "ambient/forest"
      volume: 0.6
      weight: 2

支持字段：

• 世界匹配：world / worlds
• 匹配模式：match = glob / contains / prefix / regex
• 时间过滤：time / times（day/night）
• 天气过滤：weather / weathers（clear/rain/thunder）
• 条目内间隔覆盖：interval

6. Combat（combat.yml）

CombatStart:
  pool:
    - file: "combat/start_1"
      bus: combat
      source: MUSIC

CombatLoop:
  pool:
    - file: "combat/loop_1"
      loop: true
      bus: combat
      source: MUSIC

CombatStop:
  pool:
    - file: "combat/stop_1"
      bus: combat
      source: MUSIC

CombatStart / CombatLoop / CombatStop 每组都支持：

• pool / tracks（多条）
• 或单条对象（file/id/sound + 其他字段）

7. Quest（chemdah.yml）

QuestAccept:
  file: "ui/quest_accept"
  bus: ui
  source: MASTER

QuestComplete:
  file: "ui/quest_complete"

QuestFail:
  file: "ui/quest_fail"

固定键：QuestAccept、QuestComplete、QuestFail。 客户端事件 ID 对应：quest_accept、quest_complete、quest_fail。

8. Dungeon（DungeonSounds/*.yml）

ExampleDungeon:
  worlds:
    - "dungeon_*"
  match: glob
  interval: 20~60
  bus: dungeon
  source: AMBIENT
  pool:
    - file: "dungeon/ambient_1"

支持字段：

• 世界匹配：world / worlds / dungeon
• 匹配模式：match = glob / contains / prefix / regex
• 播放池：pool / tracks

9. Area（AreaSounds/*.yml）

ExampleArea:
  world: "glob:minecraft:overworld*"
  selector:
    - "0 64 0 ~ 30"
  inside: true
  interval: 20~60
  bus: environment
  source: AMBIENT
  pool:
    - file: "ambient/forest"

支持字段：

• 选择器：selector / selectors / area / areas
• 维度约束：world / worlds / dimension / dimensions
• 区域语义：inside（true = 在区域内激活，false = 在区域外激活）
• 播放池：pool / tracks

10. Scenes / Events（OtherSounds/*.yml）

scenes:
  ExampleScene:
    interval: 20~40
    bus: environment
    source: AMBIENT
    tracks:
      - id: "ambient/forest"
        loop: true

events:
  ExampleEvent:
    sound: "ui/confirm"
    bus: ui
    volume: 1

• scenes：手动上下文切换（context=scene）
• events：一次性事件播放（SoundServerAPI.playEvent 或 Kether sound event）

11. 触发方式

Kotlin（Spigot）

SoundServerAPI.playEvent(player, "ExampleEvent")
SoundServerAPI.setContext(player, "scene", "ExampleScene", true)
SoundServerAPI.playSound(player, "ui/confirm")
SoundServerAPI.stopSound(player, "ui/confirm")

Kether

sound event ExampleEvent
sound scene scene ExampleScene true
sound play "ui/confirm" volume 1 pitch 1
sound stop "ui/confirm"