跳到主要内容

UnlockMethod 模板速查

本文档给策划、配表、资源作者、内容维护者使用。

目标只有一个：

  • 看到场景
  • 直接复制模板
  • 改几个值就能用

如果你想看完整解释，请看：docs/unlock-method-guide.md

如果你想看代码结构和扩展方式，请看：docs/unlock-method-developer-guide.md

先判断你该写哪种格式​

如果你要配的是 Arena​

写 metadata.yml：

unlock-method:
  ...

也可以直接写成数组，表示多种解锁方式：

unlock-method:
  - type: METHOD_A
    ...
  - type: METHOD_B
    ...

如果你想明确控制这些方式之间是 ALL 还是 ANY，可以写完整分组：

unlock-method:
  mode: ALL
  methods:
    - type: METHOD_A
      ...
    - type: METHOD_B
      ...

如果你要配的是 Song / Chart​

写 manifest.yml：

unlockSong:
unlockWorld:
unlockNether:
unlockVoid:

如果你要配的是收藏品 / 称号 / Tag​

走后端收藏品配置的 unlockMethod，不是插件本地文件。

Arena 常用模板​

0. 多种方式任意一种解锁​

unlock-method:
  - type: VIP_GATE
    events:
      - player.login
    player:
      permissions.rhythmc:vip:
        value: true

  - type: SHOP_GATE
    events:
      - player.login
    player:
      wattHour:
        operator: GTE
        value: 500
    grants:
      - type: COLLECTION
        target: rhythmc:title.shop-vip
      - type: CONSUME_WATT_HOUR
        target: 500

效果：

  • 有 VIP 的玩家直接解锁
  • 没 VIP 的玩家也可以花 500 购买
  • 两种方式任意一种满足即可

0.1 多种方式全部满足才解锁​

unlock-method:
  mode: ALL
  methods:
    - type: PASS_GATE
      events:
        - game.result
      values:
        pass: true

    - type: ACC_GATE
      events:
        - game.result
      values:
        accuracy:
          operator: GTE
          value: 98

效果：

  • 必须通关
  • 并且 ACC >= 98
  • 两条都满足才解锁

1. 通关某谱面后解锁 Arena​

unlock-method:
  type: CLEAR_LEVEL
  mode: ALL
  events:
    - game.result
  info:
    levelId: 123
  values:
    pass: true

2. 达到 98% ACC 后解锁 Arena​

unlock-method:
  type: HIGH_ACC
  mode: ALL
  events:
    - game.result
  info:
    levelId: 123
  values:
    accuracy:
      operator: GTE
      value: 98

3. FC 后解锁 Arena​

unlock-method:
  type: FC_UNLOCK
  mode: ALL
  events:
    - game.result
  values:
    fullCombo: true

4. AP 后解锁 Arena​

unlock-method:
  type: AP_UNLOCK
  mode: ALL
  events:
    - game.result
  values:
    allPerfect: true

5. 需要权限才能解锁 Arena​

unlock-method:
  type: VIP_ARENA
  mode: ALL
  events:
    - player.login
  player:
    permissions.rhythmc:vip:
      value: true

6. 需要玩家电池值达到阈值才能解锁 Arena​

unlock-method:
  type: MONEY_GATE
  mode: ALL
  events:
    - player.login
  player:
    wattHour:
      operator: GTE
      value: 2000

Arena 发奖模板​

1. 解锁后发一个收藏品​

unlock-method:
  type: REWARD_COLLECTION
  mode: ALL
  events:
    - game.result
  values:
    pass: true
  grants:
    - type: COLLECTION
      target: rhythmc:title.clear-123

2. 解锁后自动装备前缀​

unlock-method:
  type: REWARD_PREFIX
  mode: ALL
  events:
    - game.result
  values:
    allPerfect: true
  grants:
    - type: PLAYER_PREFIX
      target: rhythmc:title.ap-100014

3. 解锁后自动装备后缀​

unlock-method:
  type: REWARD_SUFFIX
  mode: ALL
  events:
    - game.result
  values:
    fullCombo: true
  grants:
    - type: PLAYER_SUFFIX
      target: rhythmc:title.fc-100014

4. 解锁后自动设置默认场地​

unlock-method:
  type: REWARD_ARENA
  mode: ALL
  events:
    - player.login
  player:
    permissions.rhythmc:vip:
      value: true
  grants:
    - type: DEFAULT_ARENA
      target: ancientcity

5. 解锁后扣除 500 电池值 / 金钱​

unlock-method:
  type: COST_500
  mode: ALL
  events:
    - game.result
  values:
    pass: true
  grants:
    - type: CONSUME_WATT_HOUR
      target: 500

也可以写别名：

grants:
  - type: CONSUME_MONEY
    target: 500

推荐用法：

  • 与 COLLECTION 一起使用，表示“购买成功后发一个持久化拥有凭证”
  • 不建议单独给非持久化对象无限使用，否则重登后可能再次发生扣费逻辑

6. 购买后发收藏品并扣 500​

unlock-method:
  type: BUY_TITLE
  mode: ALL
  events:
    - player.login
  player:
    wattHour:
      operator: GTE
      value: 500
  grants:
    - type: COLLECTION
      target: rhythmc:title.shop-500
    - type: CONSUME_WATT_HOUR
      target: 500

7. 隐藏真实解锁条件​

unlock-method:
  type: SECRET_UNLOCK
  hideCondition: true
  events:
    - game.result
  values:
    allPerfect: true

效果：

  • 规则照常生效
  • 但菜单 / 描述文本只会显示“我也不知道”

Song / Chart 常用模板（旧格式）​

1. 整首歌默认解锁​

unlockSong:
  - type: regular

2. world 难度需要某个权限​

unlockWorld:
  - type: permission
    value: rhythmc:vip.world

3. nether 难度需要电池值达到 500​

unlockNether:
  - type: money
    value: 500

4. void 难度要求本难度历史最好成绩达到 98%​

unlockVoid:
  - type: songacc
    song: thisDef
    value: 98

5. void 难度要求另一张谱面达到 99%​

unlockVoid:
  - type: songacc
    song: 100014
    value: 99

6. world 难度同时要求权限和电池值​

unlockWorld:
  - type: permission
    value: rhythmc:vip.world
  - type: money
    value: 1000

说明：

  • 旧格式当前按“全部满足”理解
  • 也就是这两个条件要同时成立

收藏品 / 称号 常用模板（后端下发）​

1. 登录即发 Beta 称号​

{
  "type": "LOGIN_REWARD",
  "mode": "ALL",
  "events": ["player.login"],
  "player": {
    "permissions.rhythmc:beta": {
      "value": true
    }
  }
}

2. 通关某谱面后解锁称号​

{
  "type": "CLEAR_TITLE",
  "mode": "ALL",
  "events": ["game.result"],
  "info": {
    "levelId": 123
  },
  "values": {
    "pass": true
  }
}

3. AP 后解锁称号并自动装备前缀​

{
  "type": "AP_TITLE",
  "mode": "ALL",
  "events": ["game.result"],
  "info": {
    "levelId": 100014
  },
  "values": {
    "allPerfect": true
  },
  "grants": [
    {
      "type": "COLLECTION",
      "target": "rhythmc:title.ap-100014"
    },
    {
      "type": "PLAYER_PREFIX",
      "target": "rhythmc:title.ap-100014"
    }
  ]
}

可直接替换的字段表​

你通常最常改的值​

  • levelId
  • accuracy
  • pass
  • fullCombo
  • allPerfect
  • permissions.xxx
  • wattHour
  • target

常用事件名​

  • player.login
  • player.arena.select
  • game.result

常用数值比较写法​

accuracy:
  operator: GTE
  value: 98
wattHour:
  operator: GTE
  value: 2000

常用布尔写法​

pass: true
fullCombo: true
allPerfect: true

常用权限写法​

player:
  permissions.rhythmc:vip:
    value: true

最短可用模板​

最短 Arena 模板​

unlock-method:
  type: TEST_UNLOCK
  events:
    - game.result
  values:
    pass: true

最短 Song 模板​

unlockSong:
  - type: regular

最短 world 难度权限模板​

unlockWorld:
  - type: permission
    value: rhythmc:vip.world

配置前检查清单​

写完后最好自己过一遍：

  • 这是 Arena 还是 Song / Chart？
  • Arena 是否写在 metadata.yml？
  • Song / Chart 是否写在 manifest.yml？
  • Song / Chart 是否误写成了 .rmcc 顶层？
  • levelId 是否写对？
  • target 是否写完整 Key？
  • songacc.value 是否按百分比写？
  • 如果是权限型，权限 Key 是否写对？

当前限制速记​

  • 旧 Song 格式当前支持：regular / permission / money / songacc
  • 当前没有 unlockEnd
  • songacc.song 稳定用法：数字 levelId 或 thisDef
  • 收藏品配置主要从后端下发

相关文档​

  • 完整说明：docs/unlock-method-guide.md
  • 开发者详解：docs/unlock-method-developer-guide.md