StellarCrates

StellarCrates

StellarCrates 是一个适用于 Minecraft 1.21.1、NeoForge 和 Pixelmon 的服务器权威虚拟开箱平台。

它不依赖于可能被复制、丢失、拷贝或误操作的实体箱钥匙，而是使用由服务器安全存储的持久化虚拟点数。玩家可以打开可配置的箱子，其中包含物品、宝可梦、货币、权限、指令、组合包和自定义奖励。

每次奖励都是在开箱动画开始前由服务器选定并永久提交的。断开连接、重启服务器、反复点击、背包空间不足或 Pixelmon 存储已满，都无法使奖励重摇或重复获取。

未安装可选客户端组件的玩家仍可通过完整的原版箱子菜单后备界面进行访问。可选的客户端组件增加了 30 个动画箱子界面、10 个完整的目录主题、自定义开箱仪式、音效、无障碍设置、宝可梦预览、领取物、历史记录和详细的奖励页面。

功能特性

• 安全的虚拟通用及箱子特定点数
• 服务器权威的奖励选定
• 确定性且可恢复的箱子开启
• 加权和优先层级奖励池
• 不重复选定
• 独立奖励类别
• 基于选择的奖励支持
• 软保底和硬保底
• 全网有限奖励库存
• 重复奖励保护
• 物品、宝可梦、货币、指令、权限和组合奖励
• 未交付奖励的待领取
• 持久化开启历史记录
• 签名的一次性兑换券
• 玩家间点数转移
• 受保护的世界开箱方块
• SQLite、MySQL、MariaDB 和 PostgreSQL 存储
• 多服务器网络间的共享余额
• 运行时验证和概率模拟
• 审计日志、指标、对账和恢复
• 支持流行开箱插件的迁移
• 原版箱子菜单后备界面
• 可选的动画客户端组件
• 30 个自定义箱子主题
• 10 个完整目录主题
• 自定义主题和稀有度音效
• 减少动态效果和无障碍设置
• Pixelmon 宝可梦预览和安全队伍/PC 交付
• StellarGTS 点数市场集成
• NeoForge 权限支持
• 可配置的计划、限制、Webhook、安全性和奖励

虚拟点数系统

StellarCrates 用安全的虚拟余额取代了实体箱子钥匙。

支持两种主要类型的点数：

• stellarcredits，可用于任何兼容的箱子
• 只能用于一个已配置箱子的箱子特定点数

当一个箱子使用自己的点数时，StellarCrates 会首先消耗匹配的箱子特定点数，然后消耗通用点数。

例如，拥有 3 个“星铸熔炉”点数和 2 个通用“星辰点数”的玩家可以安全地使用这两种余额来完成 5 次“星铸熔炉”的开启。

虚拟点数：

• 无法丢弃
• 死亡不会丢失
• 无法从背包中清除
• 无法通过物品数据复制
• 可在多个连接的服务器间持久存在
• 通过可审计的余额账本记录

管理员可以发放、扣除或设置余额，并可选择要求填写原因。

服务器权威开启

开箱动画永远不会决定奖励。

在揭晓开始之前，服务器会：

1. 验证玩家和箱子

2. 检查权限和可用性

3. 检查冷却时间和每日限制

4. 验证玩家有足够的点数

5. 预留所需余额

6. 使用确定性种子选定奖励

7. 更新保底进度和有限库存

8. 存储完整的奖励结果

9. 将已提交的结果发送给客户端

10. 交付或安全存储奖励

动画只是展示服务器已经提交的结果。

重复点击、数据包重放、断开连接、服务器重启、延迟、代理转移和中断的动画都无法从同一次开启中生成不同的奖励。

奖励选定

StellarCrates 支持多种可配置的选定系统。

加权奖励

每个符合条件的奖励都会获得一个可配置的权重。

权重为 20 的奖励被选中的概率是权重为 10 的奖励的两倍。权重不需要加起来等于 100。

优先层级选定

系统首先选择一个稀有度层级，然后从该层级中选择一个符合条件的奖励。

这允许服务器在不同层级包含不同数量的奖励时，仍能保持精确的稀有度分布。

支持的稀有度包括：

• 常见
• 少见
• 稀有
• 史诗
• 传说
• 神话
• 大奖

不重复选定

当一个箱子进行多次抽取时，已选定的奖励会从剩余候选列表中移除。

这可以防止在同一次开启中重复选择同一个奖励。

独立类别

一个箱子可以独立评估多个奖励类别。

这可以用来提供组合，例如：

• 一件保底物品
• 一只随机宝可梦
• 一个货币奖励
• 一次额外的装饰性抽取

选择奖励

兼容的箱子设计可以允许玩家在服务器批准的已提交选项中进行选择，而不允许客户端创建或替换奖励。

保底系统

StellarCrates 支持可配置的软保底和硬保底。

软保底

在达到配置的未成功开启次数后，符合条件的奖励会获得逐渐增加的概率提升。

管理员可以配置：

• 保底起始点
• 每次开启后应用的倍率
• 最大概率倍率
• 哪些稀有度符合条件
• 保底进度是否可见

硬保底

硬保底保证在达到配置的阈值后必定获得符合条件的奖励，前提是仍然存在有效的可选奖励。

保底可以通过共同的保底组在多个箱子之间共享。

保底永远不会绕过权限、库存、资格规则或已禁用的奖励。

有限奖励库存

奖励可以拥有无限或有限的库存。

有限库存在奖励被选中时会原子性地递减，而不是在动画结束时。

当多个服务器共享同一个数据库时，所有服务器都使用同一个实时库存计数器。两名玩家不可能同时获得一个限量奖励的最后一份。

管理员可以通过经过审计的恢复指令来检查和调整实时库存。

奖励类型

StellarCrates 支持多种内置奖励类型。

物品奖励

物品奖励可以包含：

• 原版物品
• 模组物品
• 自定义名称
• 描述
• 闪光效果
• 数据组件
• 自定义模型数据
• 附魔
• 精确导出的物品数据

管理员可以直接将手持物品导出到奖励定义中，保留支持的组件和模组数据。

宝可梦奖励

宝可梦奖励可以通过 Pixelmon 规格创建，或从管理员的队伍中导出。

宝可梦奖励可以保留或配置：

• 种族
• 形态
• 配色
• 闪光状态
• 等级
• 性格
• 特性
• 成长
• 个体值 (IVs)
• 努力值 (EVs)
• 招式
• 携带物品
• 精灵球
• 其他受支持的 Pixelmon 属性

一旦抽取，最终的宝可梦数据即被提交，在交付重试期间无法重新抽取。

货币奖励

箱子可以通过幂等的账本条目授予内部虚拟货币。

外部经济集成也可以通过经审查的提供者实现。

指令奖励

配置的控制台指令可以作为奖励执行。

出于安全考虑，指令根必须在服务器的指令白名单中。下载或迁移的配置不能仅仅因为解析正确就获得不受限制的控制台访问权限。

权限奖励

权限奖励可以通过配置和白名单化的指令授予头衔、临时权限或其他权限提供者的福利。

组合奖励

组合奖励包含多个子奖励。

每个子奖励都独立交付和跟踪。如果某个组成部分无法交付，它可以变成待领取物，而不会重复已经成功交付的组成部分。

自定义奖励

其他模组可以注册自定义奖励提供者，同时保留 StellarCrates 的服务器权威和幂等交付要求。

领取与安全交付

StellarCrates 永远不会将未交付的奖励扔到地上作为不安全的溢出后备方案。

如果奖励无法安全交付，它会变成待领取物。

常见原因包括：

• 玩家背包已满
• 宝可梦队伍已满
• Pixelmon PC 存储已满
• 外部奖励需要人工审核
• 指令交付状态不确定
• 临时集成失败

玩家可以打开他们的“领取”页面，腾出空间，然后重试交付。

每个领取物都包含一个支持参考编号，管理员可以用它来检查原始的已提交开启记录。

已交付的组件会单独签收，防止重试时重复发放已经收到的奖励。

签名兑换券

管理员和外部商店集成可以签发签名的一次性兑换券代币。

兑换券可以包含：

• 点数类型
• 点数数量
• 过期时间
• 可选的玩家限制
• 唯一的兑换券身份标识
• 加密签名

兑换券无法被篡改或重复兑换。

玩家使用以下指令兑换兑换券：

/crates redeem <token>

未兑换的兑换券代币应像密码一样妥善保管。

受保护的箱子方块

管理员可以将已配置的箱子附加到现有的世界方块上。

被附加的方块会获得：

• 防止普通玩家破坏的保护
• 防止常见爆炸的保护
• 防止活塞移动的保护
• 防止流体替换的保护
• 防止常见工具和实体破坏的保护
• 一个悬浮的箱子标题
• 一段简短描述
• 一个可见的交互提示

左键或右键点击该方块会打开其附着的箱子。

原始方块会被保留。StellarCrates 不会用自定义注册方块替换它。

玩家目录

玩家可以使用以下指令打开箱子目录：

/crates

别名包括：

/crate

/stellarcrates

目录会显示玩家有权查看的箱子。

每个箱子都有专门的页面，用于：

• 概览
• 奖励
• 领取
• 开启历史

“概览”页面可以显示箱子描述、花费、余额、库存、保底进度、可用性和开启控制。

“奖励”页面在服务器允许显示时展示符合条件的奖励和配置的几率。

“领取”页面包含等待安全交付的奖励。

“历史”页面显示最近的开箱记录及其已提交的结果。

可选客户端界面

服务器包含完整的箱子引擎，不要求玩家安装可选的客户端组件。

没有安装该组件的玩家在启用后备界面时可以使用原版箱子菜单。

可选的客户端组件增加了：

• 动画箱子目录
• 专用箱子界面
• 开箱仪式
• 宝可梦预览
• 奖励几率和稀有度显示
• 领取和历史页面
• 滚动界面
• 自定义主题音效
• 稀有度获胜音效
• 减少动态效果模式
• 紧凑显示模式
• 分通道音量控制
• 开箱节奏控制
• 过渡控制
• 本地主题预览

服务器在点数、抽取、保底、库存、交付、权限、精确几率和箱子可用性方面保持权威。

本地客户端设置可以减少演示效果，但无法改变服务器规则。

箱子主题

StellarCrates 包含 30 个自定义箱子主题：

• event_horizon
• nebula_conservatory
• astral_forge
• celestial_orrery
• quantum_vault
• supernova_theatre
• wormhole_transit
• cosmic_aquarium
• starship_bridge
• lunar_archive
• meteor_museum
• aurora_cathedral
• pulsar_radio
• zodiac_bazaar
• infinity_garden
• chronos_paradox
• dreamweaver_loom
• leviathan_sanctum
• prism_masquerade
• atlas_memory_engine
• team_rocket_hq
• pokemon_center
• indigo_league
• professor_lab
• fossil_resurrection
• safari_expedition
• contest_spectacular
• eeveelution_nexus
• ultra_space
• legendary_shrine

每个主题都有自己独特的场景几何、界面结构、控件、环境动态和奖励揭晓编排。

主菜单主题

箱子目录包含 10 个服务器选择的主题：

• grand_hotel
• stellar_crown
• chronorail_terminal
• galactic_arcade
• abyssal_sonar
• dream_auction
• botanical_helix
• quantum_detective
• origami_atelier
• mythic_planetarium

服务器控制活动的目录主题。

在允许的情况下，玩家可以在本地预览主题，但他们无法覆盖服务器为正常使用配置的主题。

音效系统

每个目录主题都可以为以下事件定义音效：

• 进入目录
• 更改选择
• 开始开箱
• 锁定已提交的结果
• 揭示最终奖励

还支持单独的稀有度音效，包括：

• 常见
• 少见
• 稀有
• 史诗
• 传说
• 神话
• 大奖

玩家可以独立配置主音量、界面、目录、开箱和稀有度的音量通道。

最终的稀有度提示音只在权威的已提交结果被揭示时播放。

存储

StellarCrates 支持：

• SQLite
• MySQL
• MariaDB
• PostgreSQL

SQLite 适用于使用本地磁盘的单服务器。

多服务器网络应使用 MySQL、MariaDB 或 PostgreSQL，并满足：

• 相同的共享数据库
• 相同的网络作用域
• 协调的箱子定义
• 同步的系统时钟
• 兼容的模组和数据库模式版本

StellarCrates 不使用不安全的纯内存权威后备方案。

如果存储不可用，新的开箱操作将安全失败，而不是冒免费奖励、余额丢失或重复交付的风险。

安全性

StellarCrates 包含可配置的安全设置，用于：

• 兑换券签名
• 兑换券过期
• 玩家绑定兑换券
• 指令奖励白名单
• Webhook 主机白名单
• HTTPS Webhook 要求
• 管理员操作原因必填
• 玩家地址哈希
• 请求防抖
• 并发开箱限制
• 待领取物限制
• 审计日志
• 有界存储和 Webhook 队列

管理性余额、保底、库存、兑换券、转移、领取、修复和恢复操作可以被永久审计。

恢复与可靠性

中断的开箱会在启动后、登录时以及定期的恢复扫描过程中进行对账。

根据存储的状态，中断的开箱将：

• 释放未使用的预抽取预留
• 继续交付已提交的奖励
• 创建待领取物
• 当外部交付无法证明时进入管理员审核

同一次开箱在恢复过程中永远不会被故意重新抽取。

指令和外部集成可能会造成不确定性，如果另一个系统在 StellarCrates 记录结果之前执行了操作。这些操作会进入管理员保留状态，而不是被盲目重复。

迁移支持

StellarCrates 包含以下插件的迁移工具：

• PhoenixCrates
• EnvyCrates
• ExcellentCrates
• CrazyCrates
• Aquatic Crates

迁移工具会转换支持的箱子定义、奖池、奖励、花费、指令、权限和展示设置。

导入的箱子会保持禁用状态，直到管理员：

1. 审查迁移报告

2. 修复不兼容的 ID 或指令

3. 验证生成的配置

4. 模拟奖励概率

5. 测试奖励交付

6. 启用批准的箱子

玩家余额、实体钥匙、历史记录和专有运行时数据库不会从原始开箱插件中静默复制。

验证与模拟

管理员可以在激活整个候选配置之前对其进行验证。

一次失败的重载不会部分替换活动的箱子目录。

概率模拟最多可以执行一百万次测试抽取，并可使用可选的固定种子。

模拟不会：

• 消耗点数
• 改变保底进度
• 减少库存
• 交付奖励
• 创建历史记录

管理员可以使用相同的种子和迭代次数来比较箱子修订版本之间的概率变化。

StellarGTS 集成

StellarCrates 支持与 StellarGTS 的安全市场集成。

玩家可以上架：

• 通用星辰点数
• 单个箱子的特定点数

点数不会被转换为实体钥匙物品。

相反，StellarCrates 会创建原子化的市场托管，并在上架生效前从卖家的可用余额中扣除上架数量。

该集成可以防范：

• 点数复制
• 双重购买
• 数据包重放
• 重复点击
• 并发代理服务器
• 重启重试
• 重复卖家结算

StellarCrates 始终保持对每笔点数变动的权威，而 StellarGTS 负责市场展示和支付。

玩家指令

/crates

打开箱子目录。

/crates open <crate> [amount]

请求一次或多次箱子开启。

/crates preview <crate>

打开箱子的详细信息和奖励视图。

/crates balance

显示可用的点数余额。

/crates claims

打开待领取的奖励。

/crates history

显示最近的开启历史记录。

/crates redeem <voucher>

兑换签名兑换券。

/crates transfer <player> <credit> <amount>

在服务器允许玩家转移时转移虚拟点数。

管理员工具

管理员可以：

• 创建起始箱子定义
• 导出手持物品
• 导出队伍宝可梦
• 验证所有内容
• 事务性地重载内容
• 发放、扣除或设置点数
• 检查和修改保底
• 检查和修改有限库存
• 模拟箱子概率
• 生成概率报告
• 签发和作废兑换券
• 检查中断的开箱
• 对账待处理交易
• 重新分配领取物
• 检查存储健康
• 创建 SQLite 备份
• 附加受保护的箱子方块
• 导入受支持的第三方箱子配置
• 查看指标和系统健康

服务器权威设计

所有点数、奖励、概率、保底、库存、领取、历史、兑换券、存储、资格和交付都由服务器控制。

可选的客户端组件只显示经过验证的目录数据和已提交的开箱结果。

安装或修改客户端组件不会允许玩家：

• 创建点数
• 选定奖励
• 更改概率
• 推进或重置保底
• 恢复有限库存
• 绕过限制
• 重新抽取开箱
• 重复领取
• 更改交付结果

StellarCrates 团队