Arena 地图格式

本文档详细介绍 RhythMC 地图（Arena）的格式，基于 YAML 配置文件和 Schematic 文件。

如果你是想手动添加解锁规则，而不是只看字段定义，请直接看 docs/unlock-method-guide.md。

目录结构

arena_name/
├── metadata.yml    # 必需，地图元数据
└── arena.schem     # 必需，地图结构文件（可自定义文件名）

metadata.yml

name: arena_name
display-name: "显示名称"
author: "作者名"
description: "地图描述"
icon: STONE
border: CYAN_CONCRETE
success: GREEN_CONCRETE
schematic: arena.schem
hide: false
unlock-method:
  type: EVENT_RULES
  mode: ALL
  events:
    - chart.clear
  values:
    score:
      operator: GTE
      value: 950000
  player:
    permissions.rhythmc.vip:
      operator: EQUALS
      value: true

字段	类型	默认值	说明
name	String	文件夹名	地图名称（小写）
display-name	String	name	显示名称
author	String	Unknown	作者
description	String	""	描述
icon	Material	GRASS_BLOCK	物品栏图标
border	Material	CYAN_CONCRETE	边界方块
success	Material	GREEN_CONCRETE	成功判定方块
schematic	String	arena.schem	结构文件路径
hide	Boolean	false	是否隐藏
unlock-method / unlockMethod	Section	空	通用解锁规则，支持 `events`、`info`、`values`、`player` 四类触发条件

`unlock-method` 规则说明

CommonUnlockMethod 本身不是 Arena 专属。Arena 这里只是一个接入示例；同一套规则模型同样适用于 Chart、Song、称号、前后缀、收藏品或任何实现了 Unlockable 的对象。

type: 规则类型标识，仅作为命名/分类，不限制具体触发内容。
mode: ALL 或 ANY，决定多个条件需要全部满足还是任意满足。
events: 事件触发列表，匹配 UnlockContext.event。
info: 任意信息匹配，适合关卡、地图、模式等上下文字段。
values: 数值匹配，支持 GT、GTE、LT、LTE、EQUALS 等操作符。
player: 玩家属性匹配，适合权限、身份组、统计字段等玩家相关触发。
conditions / rules: 需要更细粒度时可直接写显式规则项：trigger、key、operator、value。
grant / grants: 规则命中后的发放动作。当前内置支持 COLLECTION、PLAYER_PREFIX、PLAYER_SUFFIX、DEFAULT_ARENA。

运行时上下文来源

player.login: 玩家完成在线/离线登录后写入一次登录事件。
player.arena.select: 玩家在设置菜单中成功选择场地后写入一次场地选择事件。
game.result: 每次游戏结算都会写入一次结果事件，包含 levelId、songId、arena、acc、accuracy、pass、fullCombo、allPerfect、maxCombo 等字段。
player.*: 始终带有当前玩家快照，例如 player.uid、player.playerType、player.aptitude、player.wattHour、player.permissions.rhythmc:vip、player.collections.rhythmc:title.beta、player.songRecords.123.pass。

匹配到收藏品解锁规则后，插件会直接把该收藏品 Key 放进玩家 PlayerData.collections 里，后续规则可以继续引用 player.collections.* 做联动判断。

例如下面的规则表示：玩家结算后只要通过 123 号谱面且准确率达到 98%，就解锁该场地：

unlock-method:
  type: RESULT_GATE
  mode: ALL
  info:
    levelId: 123
  values:
    pass: true
    accuracy:
      operator: GTE
      value: 98

Schematic 文件

地图结构使用 WorldEdit 的 .schem 格式存储。

文件名可自定义，在 metadata.yml 中指定
支持多种格式：schematic、worldedit、mcedit 等

示例

创建名为 my_arena 的地图：

在 arenas 目录下创建文件夹 my_arena
创建 metadata.yml：

name: my_arena
display-name: "我的地图"
author: "玩家名"
description: "这是一个示例地图"
icon: DIAMOND_BLOCK
border: RED_CONCRETE
success: EMERALD_BLOCK
schematic: map.schem
hide: false

放入结构文件 map.schem

注意事项

name 必须小写，系统会将其转换为小写存储
schematic 文件必须存在于指定路径
结构文件使用 WorldEdit 格式

目录结构​

metadata.yml​

unlock-method 规则说明​

运行时上下文来源​

Schematic 文件​

示例​

注意事项​