Crate
概览
Crate 为你的服务器添加战利品箱。一个箱子拥有一份奖励列表，每个奖励都有稀有度，玩家通过消耗一把虚拟钥匙来打开它。中奖的奖励会在任何动画开始之前就在服务器上抽定，因此玩家在开箱期间的任何操作都无法改变结果。开箱会计入里程碑，在达到一定开箱次数后可以触发额外奖励。
奖励是 TypeWriter 触发器，因此一个奖励可以给予物品、运行命令、授予装饰品或启动一个序列。开箱过程会展示在玩家面前的世界中：以悬浮物品展示实体预览奖励，或者进行翻牌小游戏。菜单让玩家可以浏览各个箱子及其可能给出的奖励。
该扩展运行于 TypeWriter 的 BTC 构建版本（BTC Core，Paper/Folia），此处的文档仅供参考。
功能
- 加权奖励 — 稀有度带有权重，每个奖励的概率会显示在菜单中。
- 虚拟钥匙 — 钥匙按玩家记录在箱子的数据构件中，每次开箱消耗一把。
- 安全开箱 — 钥匙会先被预留，只有在奖励揭晓时才会被消耗；断线、超时或重启都会退还钥匙。
- 里程碑 — 在达到一定开箱次数后触发额外奖励。
- 翻牌小游戏 — 玩家翻开一排背面朝上的卡牌中的一张，而奖励早已确定。
- 世界预览 — 奖励以
PAGINATED、FLEX或SIMPLE布局漂浮在玩家周围，可选配 NPC 和全息图。 - 菜单 — 全局箱子菜单以及每个箱子的奖励菜单，支持边框、分页和自定义按钮。
- 统计数据 — 开箱次数、钥匙、已用钥匙、上次开箱和里程碑，均可作为占位符使用。
安装
- 安装 TypeWriter 的 Basic 扩展和 GUI 扩展（在 BTC 构建版本中为
GuiAndDialogs）。没有它们，Crate 将无法加载。 - 将 Crate 的 JAR 放入
plugins/Typewriter/extensions/并重启服务器。 - 将“权限”一节中的权限授予你的管理员。
快速上手
创建一个有三个奖励的箱子，并给自己一把钥匙：
- 在 TypeWriter 网页面板中，打开一个**清单（manifest）**页面，添加一个 Crate Data 构件。保留生成的
artifactId，并且每个箱子使用一个构件。 - 添加一个 Crate 条目。将
dataArtifact设为该构件，并编写noKeyMessage。 - 在
rarities中，添加权重为70的Common和权重为30的Rare。 - 在
rewards中添加三个奖励：为每个奖励设置一个rarity、在预览中显示的item、一个name，并在action中设置给予该奖励的触发器。保持grantItem开启可自动给予该item，如果由该动作自己给予物品，则将其关闭。 - 在
rewardSlots中，列出奖励菜单的物品栏槽位（从 0 开始计数），例如10-12。没有奖励槽位的箱子会拒绝打开。 - 在
icon中，设置该箱子在全局菜单中的x和y、一个item和一个name。 - 添加一个指向该箱子的 Open Crate 动作，并从 NPC、方块或物品触发它。
- 发布，然后运行
/tw crate give <crate entry id> 5并打开箱子。使用/tw crate menu浏览各个箱子。
在箱子的奖励菜单中，点击某个奖励会直接触发该奖励的 action，不会消耗钥匙，也不会计入统计。如果某个奖励的动作会给出有价值的东西，请不要让玩家访问奖励菜单，或者只把该菜单留给管理员使用。
钥匙通过 /tw crate give <crate> <amount> [targets] 添加。没有专门用于钥匙的动作，但命令动作可以运行该命令，例如在任务奖励或商店中。
工作原理
奖励的概率等于其稀有度的权重除以所有奖励的总权重。稀有度未列在 rarities 中的奖励权重为 1。奖励揭晓时，钥匙被消耗，开箱次数和已用钥匙计数增加，任何被跨过的里程碑会触发，然后给予物品（如果 grantItem 开启），并运行奖励的 action。一位玩家同一时间只能进行一次开箱。
菜单
- 全局菜单 — 通过
/tw crate menu打开。它为每个箱子显示一个图标，放置在图标的x（0 到 8）和y（0 到 5）处，点击图标会打开该箱子的奖励菜单。可选的 Crate Main Menu 条目用于设置大小、标题、边框、按钮、每页物品数，以及为分页箭头保留的列。 - 奖励菜单 — 通过点击图标打开，或使用 Open Crate Menu 动作打开。它在
rewardSlots中显示奖励，包含其名称、lore，以及可选的概率和稀有度行（chanceLore和rarityLore，使用{chance}和{rarity}）。guiLayout为PAGINATED、FLEX（居中，四列）或SIMPLE。frameItem、itemsPerPage和paginationColumn用于调整边框和分页，buttons则添加带有动作的自定义按钮。
按钮有类型（INFORMATION、NEXT、PREVIOUS、FILL）和位置。FILL 按钮会被复制到每个空槽位。crate_button: 标记（CRATE_OPEN、CRATE_PREVIEW、CRATE_GLOBAL_BROWSE、CRATE_REWARD_SLOT、NAV_BACK、NAV_CLOSE）在 GUI 编辑器中可选用，但在此版本中它们只显示一个占位物品。
配置
Crate 没有配置文件。一切都在条目中配置。玩家数据存放在 Crate Data 构件中：钥匙、开箱次数、已用钥匙、上次开箱时间、里程碑以及待处理的开箱。它是异步写入的，崩溃遗留的待处理开箱会在启动时恢复（并退还钥匙）。
命令
所有命令都是 TypeWriter 命令的子命令，因此以 /typewriter 或 /tw 开头。<crate> 是某个箱子的条目，支持自动补全。
| 命令 | 说明 | 权限 |
|---|---|---|
/tw crate menu | 打开全局箱子菜单。 | typewriter.crate.menu |
/tw crate open <crate> | 打开箱子，消耗一把钥匙。 | typewriter.crate.open |
/tw crate give <crate> [targets] | 给自己或所选玩家一把钥匙。 | typewriter.crate.give |
/tw crate give <crate> <amount> [targets] | 给予多把钥匙。 | typewriter.crate.give |
/tw crate remove <crate> [targets] | 移除一把钥匙，仅当玩家拥有时。 | typewriter.crate.remove |
/tw crate remove <crate> <amount> [targets] | 移除多把钥匙，仅当玩家拥有足够数量时。 | typewriter.crate.remove |
基础权限 typewriter.crate 保护整个命令。扩展注册了一个供菜单点击使用的内部命令 /cratemenu；它不是用来手动输入的。
权限
| 权限 | 授予 |
|---|---|
typewriter.crate | 访问 /tw crate 命令。 |
typewriter.crate.menu | /tw crate menu。 |
typewriter.crate.open | /tw crate open。 |
typewriter.crate.give | /tw crate give。 |
typewriter.crate.remove | /tw crate remove。 |
占位符
这些是 crate 扩展的 MiniPlaceholders 标签。请将 id 替换为箱子的条目 ID。未知的箱子会返回空值。
| 占位符 | 返回 |
|---|---|
<crate_openings:id> | 玩家开启该箱子的次数。 |
<crate_keys:id> | 玩家持有的钥匙数。 |
<crate_keys_used:id> | 玩家已消耗的钥匙数。 |
<crate_last_open:id> | 上次开箱的时间，以自 1970 年 1 月 1 日起的毫秒数表示。 |
<crate_milestone:id> | 已达到的最高里程碑。 |
在 hologramLines 中，请改用令牌 {openings}、{keys}、{last_open} 和 {milestone}。
条目
6 个条目，由扩展源码生成。
动作2
- Open CrateOuvre une caisse
- Open Crate MenuOuvre le menu d'une caisse
构件1
- Crate ArtifactDonnées de caisse
清单3
- CrateDéfinition d’une caisse
- Crate Main MenuApparence du menu principal
- Crate Minigame CardsMini-jeu Caisse : Cartes
故障排查
“This crate is not configured correctly”。 该箱子未通过验证，服务器日志会列出原因：没有奖励、稀有度权重无效（必须大于零）、没有 rewardSlots，或槽位超出 0 到 53 的范围或重复、按钮或 icon 超出 9 乘 6 的网格，或者里程碑为零次开箱或重复。启动时会运行相同的检查并写入警告。
玩家收到 noKeyMessage。 玩家没有该箱子的钥匙，或者该箱子没有 dataArtifact。请使用 /tw crate give 发放钥匙，并检查构件链接。
“You are already opening a crate”。 该玩家正在进行一次开箱。它会在奖励揭晓或玩家断线时结束。
开箱后统计数据和钥匙没有变化。 它们只有在奖励揭晓时才会改变。如果玩家在此之前离开或服务器停止，钥匙会被退还，计数保持不变。
预览什么都不显示或显示了错误的奖励。 预览使用每个奖励的 item。item 为空的奖励会被跳过，preview.maxVisibleRewards 限制一次最多显示多少个。preview.distance 和 *Location 偏移量用于移动展示位置。
翻牌小游戏没有启动。 请在箱子的 minigame 字段中链接一个 Crate Minigame: Cards 条目。其 columns 最大为 10，rows 最大为 10，cardCount 上限为 100。
同一个奖励被给予了两次。 只有在 action 不会同时给予该物品时，才应保持 grantItem 开启。
相关扩展
- GUI — 箱子菜单所使用的菜单引擎。