Claimo

插件

· 作者 Naimad

适用于 PaperMC 1.21.1-26.2 的兑换码插件。玩家可通过可配置命令兑换代码。

0 本站下载 0 关注 更新于 3 个月前

最新 1.4 · 1.21.11 · Folia / Paper

一键开服(送7天)

Claimo

适用于 PaperMC 26.2 的优惠券/代码兑换插件。玩家可通过可配置命令兑换代码;每个代码可运行一条或多条服务器命令,并可设置前置条件(如挖掘方块数、游戏时长等)作为兑换门槛。该前置条件系统为公开 API,因此插件扩展可以接入新的检查项——例如“关注我们的 TikTok / YouTube / X / Instagram”。

构建

./gradlew build

阴影插件 jar 文件将生成至 build/libs/Claimo-<version>-all.jar。

命令与权限

命令 描述 权限
/<command> 打开分页优惠券 GUI(玩家);打印用法(控制台) claimo.use(默认:所有人)
/<command> <voucher> 兑换优惠券 claimo.use(默认:所有人)
/<command> create 打开游戏内代码创建对话框(1.21.7+) claimo.admin(默认:op)
/<command> reload 重载配置文件和优惠券文件 claimo.admin(默认:op)

<command> 默认为 code,由 command: 配置键设定(别名:/claimo)。优惠券名称支持 Tab 补全。不带参数运行命令会打开一个列出可用代码的分页 GUI;点击其中一个即可兑换。标记为 hide: true 的优惠券不会出现在 GUI 和 Tab 补全中(但仍可通过直接输入代码进行兑换)。

在游戏内创建代码(1.21.7+)

/<command> create 会打开一个多页 Dialog 向导。第一页用于设置代码本身(名称、支持 %player% 的命令、以控制台身份运行、从列表中隐藏,以及可选的使用次数限制——最大使用次数并带有单人/共享切换选项)。后续页面列出所有注册的前置条件类型——包括内置的和任何由插件扩展添加的类型——每项都有开关及其可配置字段;开启你需要的项并设置其值。前置条件是分页显示的,因此如果一项太多无法在一页显示,向导会自动添加新页面。使用 « Back / Next » 在页面间移动,并在最后一页点击 Create 以写入 vouchers/<name>.yml 并执行重载。对于高级选项(多条命令、白名单/黑名单),请编辑生成的文件。

Dialog API 仅存在于 Paper 1.21.7+。在 1.21.1–1.21.6 版本上,创建器会被自动禁用(插件仍会加载且其他功能正常);/<command> create 会提示其不可用,你需要手动编写优惠券文件。该 jar 基于 1.21.8 API 构建,但保留了 api-version: 1.21,且所有 Dialog 相关代码均被隔离,因此绝不会在旧版服务器上加载。

配置

配置分散在插件数据文件夹的几个文件中,首次运行时会自动创建。编辑它们后运行 /<command> reload。

plugins/Claimo/
├── config.yml            # 核心设置
├── messages.yml          # 所有面向玩家的文本(MiniMessage)
├── gui.yml               # 优惠券列表 GUI
└── vouchers/             # 每个优惠券对应一个 .yml 文件;文件名即为代码
    └── test.yml

config.yml

# 玩家输入用于兑换的命令。设置为 "kod" 则变为 /kod <voucher>。
# 更改此设置需要重启服务器。
command: code
# 当不带参数运行命令时,打开分页优惠券 GUI。
gui-list-enabled: true

# 存储兑换计数(全局池和每位玩家的使用情况)的位置。
# type: yaml | sqlite | mysql | postgresql | mongodb
#   yaml   -> plugins/Claimo/usage.yml   (无需设置,单服务器)
#   sqlite -> plugins/Claimo/data.db     (无需设置,单服务器)
#   mysql / postgresql / mongodb -> 共享数据库(适合多服务器)
# MariaDB 由 mysql 后端提供服务(其驱动程序支持 MariaDB 协议),
# 因此 "mysql" 或 "mariadb" 均可工作。
# host/port/database/username/password/table-prefix 适用于网络后端。
# 对于 mongodb,你可以将 `uri` 设置为完整的连接字符串
# (例如 mongodb+srv://...);当设置此项时,它会覆盖 host/port/凭据,而
# `database` 选择数据库,`table-prefix` 为集合添加前缀。
# 更改存储类型需要重启服务器。
storage:
  type: yaml
  uri: ""
  host: localhost
  port: 3306
  database: claimo
  username: root
  password: ""
  table-prefix: claimo_
  pool-size: 10

messages.yml

占位符:<command>、<voucher>、<type>,以及 <description>(注入到 requirement-met / requirement-unmet 中的每条前置条件行)。

prefix: "<gray>[<aqua>Claimo</aqua>]</gray> "
usage: "<gray>使用 <white>/<command> <code></white> 兑换奖励代码。</gray>"
no-such-voucher: "<red>未找到优惠券代码 <white><voucher></white>。</red>"
players-only: "<red>此命令只能由玩家使用。</red>"
requirements-not-met: "<red><white><voucher></white> 的前置条件:</red>"
requirement-met: "<green>✔</green> <gray><description></gray>"
requirement-unmet: "<red>✖</red> <white><description></white>"
requirement-unavailable: "前置条件 '<type>' 不可用。"
requirement-error: "检查此前置条件失败。"
requirement-blocks-mined: "挖掘方块:<mined>/<amount>"
requirement-playtime: "在线时长:<played>/<required>"
requirement-account-age: "账号年龄:<current>/<required> 天"
success: "<green>成功兑换代码 <white><voucher></white>!</green>"
reloaded: "<green>Claimo 配置已重载。</green>"

当兑换失败时,会打印整个前置条件检查清单——满足的行使用 requirement-met,未满足的行使用 requirement-unmet,每行包裹着前置条件自己的 <description>。

gui.yml

标题占位符:<page>、<pages>。voucher-name/voucher-lore 占位符:<voucher>。设置 filler: NONE 以不显示背景。rows 被限制在 2–6 之间(底部一行用于页面导航)。

title: "<dark_gray>可用代码 (<page>/<pages>)"
rows: 6
filler: GRAY_STAINED_GLASS_PANE
voucher-material: PAPER
voucher-name: "<aqua><voucher>"
voucher-lore:
  - "<gray>点击兑换此代码。</gray>"
previous-material: ARROW
previous-name: "<yellow>« 上一页</yellow>"
next-material: ARROW
next-name: "<yellow>下一页 »</yellow>"

vouchers/<code>.yml

vouchers/ 目录中的每个文件定义一个兑换码;文件名(不含 .yml 后缀)即为玩家用于兑换的代码。通过放入新文件来添加新的兑换码。

# vouchers/test.yml  →  使用 /code test 进行兑换

# 单个命令(字符串)或多个命令(列表)。前导的 "/" 是可选的。
# %player% 会被替换为玩家的名字。如果安装了 PlaceholderAPI,
# 任何其他 %placeholder%(例如 %player_uuid%, %vault_eco_balance%)也会被解析。
cmd: "lp user %player% parent addtemp vip 7d"
# 以控制台身份运行(true)或以玩家身份运行(false)。默认值:true。
console: true
# 在 GUI 和 Tab 补全中隐藏(仍可通过代码兑换)。默认值:false。
hide: false
# 可选的兑换限制。省略表示无限制。
#   mode: global      -> 共享 `amount` 次一次性兑换池:前
#                        `amount` 个不同的玩家各兑换一次后,该兑换码即失效
#         per-player  -> 每个玩家可以兑换 `amount` 次(无共享池)
#   amount: 池大小(global)或每位玩家的允许次数(per-player)。默认值为 1。
limit:
  mode: per-player
  amount: 1
# 所有条件都必须满足,兑换码才可被兑换。可选。
requirements:
  - type: blocks_mined
    amount: 100
    # 可选:仅统计这些材质类型的方块。
    whitelist:
      - DIAMOND_ORE
      - DEEPSLATE_DIAMOND_ORE
    # 可选:这些材质类型的方块永远不会被统计。
    # blacklist:
    #   - STONE
  - type: playtime
    seconds: 3600
  - type: messages_sent
    amount: 25
    min-length: 10
    delay-seconds: 20
  - type: account_age
    days: 7
  - type: permission
    permissions: [claimo.vip, claimo.mvp]   # 必须至少拥有其中一项权限
    denied-permissions: [claimo.redeemed]   # 必须不拥有任何权限
  - type: rank
    denied-ranks: [admin, owner]            # 工作人员不能兑换此兑换码

内置要求类型

type 参数 含义
blocks_mined amount: <int>, whitelist: <material list> (可选), blacklist: <material list> (可选) 玩家已破坏至少 amount 个方块(由 Claimo 追踪,重启后持久保存)。如果有 whitelist,则只统计那些材质类型;如果有 blacklist,则从不统计那些材质类型。材质名称为 Bukkit 常量,例如 DIAMOND_ORE。
playtime seconds: <int> 玩家在服务器上的总在线时长至少为 seconds(原版游戏时间统计数据)。
messages_sent amount: <int>, min-length: <int> (默认 10), delay-seconds: <int> (默认 20) 玩家已发送至少 amount 条符合条件的聊天消息。只有当消息长度至少为 min-length 字符,且距离上一条被统计的消息已过去至少 delay-seconds 时,该消息才算数——这可以防止玩家通过刷屏短消息来刷取要求。每对不同的 (min-length, delay-seconds) 组合都会单独追踪,因此不同的兑换码可以使用不同的规则。
account_age days: <int> 玩家账号首次加入服务器的时间至少距今 days 天——以此阻止全新账号和分身小号获取奖励。
permission permissions: <node list>, denied-permissions: <node list> 玩家必须至少拥有 permissions 中的一员(省略此项表示无正向要求),且不拥有 denied-permissions 中的任何一项。使用拒绝列表可以将某些兑换码锁定给尚未持有特定权限的玩家。两者均接受 YAML 列表或逗号分隔的字符串;单数形式的 permission / denied-permission 键也有效。
rank ranks: <group list>, denied-ranks: <group list> 与 permission 类似,但针对通过 Vault 解析的权限组:玩家必须属于 ranks 中的至少一组,且不属于 denied-ranks 中的任何一组。需要 Vault 提供商(如 LuckPerms 等);如果没有提供程序,则无法通过正面向 ranks 要求。单数形式的 rank / denied-rank 键也有效。

Claimo 在其 PDC(Persistent Data Container)中为每个玩家存储已破坏方块的累计总数。为了保持玩家数据体积较小,仅针对实际出现在某个兑换码的 blocks_mined 白名单/黑名单中的材质才会保留按材质分类的计数器——其他所有方块只会增加总数。总数始终是精确的;某种材质的按类型计数从它首次出现在配置文件中开始累积。

API — 添加自定义要求

插件扩展包通过注册新的要求类型来扩展 Claimo。一种类型只是一个键(在 config.yml 中使用),绑定到一个构建 Requirement 的工厂方法。

1. 依赖 Claimo

编译时引用发布的 API 工件(它仅提供 API 类;Claimo 插件在运行时提供实现):

repositories {
    maven("https://repo.vao.zone/releases")   // 或使用 /snapshots 获取 -SNAPSHOT 版本
}
dependencies {
    compileOnly("zone.vao:claimo-api:1.0-SNAPSHOT")
}

plugin.yml:

depend: [Claimo]   # 或者 softdepend: [Claimo]

依赖 Claimo 可保证你的插件在其之后启用,从而使 API 准备就绪。

2. 实现 Requirement

Requirement.check(...) 返回一个 CompletableFuture<RequirementResult>,因此网络调用(如社交媒体关注检查、Web API 请求等)会在主线程之外运行。返回 RequirementResult.satisfied(description) 或 RequirementResult.unsatisfied(description)。description 是在要求清单中显示的行(包裹在 messages.yml 中的 requirement-met / requirement-unmet 中),因此请中性地措辞——例如 Follow @Naimadx123 on TikTok。

import net.kyori.adventure.text.Component
import zone.vao.claimo.requirement.Requirement
import zone.vao.claimo.requirement.RequirementContext
import zone.vao.claimo.requirement.RequirementResult
import java.util.concurrent.CompletableFuture
class TikTokFollowRequirement(private val account: String) : Requirement {
    override fun check(context: RequirementContext): CompletableFuture<RequirementResult> {
        return myTikTokClient.isFollowing(context.player.uniqueId, account).thenApply { follows ->
            val description = Component.text("在 TikTok 上关注 @$account")
            if (follows) RequirementResult.satisfied(description)
            else RequirementResult.unsatisfied(description)
        }
    }
}

3. 注册类型

从插件的 onEnable 中执行:

import zone.vao.claimo.ClaimoApi
import zone.vao.claimo.requirement.RequirementInput

ClaimoApi.registerRequirement(
    "tiktok_follow",
    { cfg -> TikTokFollowRequirement(cfg.getString("account")!!) },
    // 可选:使该要求出现在 /code create 命令中并允许配置。
    listOf(RequirementInput.TextInput("account", "TikTok 账号")),
)

cfg 是该条目的 RequirementConfig;从中读取你自己的参数(getString、getInt、getLong、getDouble、getBoolean、getStringList、has)。在工厂函数内部抛出异常会将该兑换标记为失败,而不是导致命令崩溃。

可选的 inputs 列表(RequirementInput.NumberInput / TextInput / BoolInput)告诉游戏内创建器为你的类型渲染哪些字段,以及将这些字段写入哪些配置键。省略它(使用双参数重载)则该类型在文件中仍然有效,并在创建器中显示为无参数的简单开关。

4. 在凭证中使用

# vouchers/social_reward.yml
cmd: "give %player% diamond 5"
requirements:
  - type: tiktok_follow
    account: vao.zone

要求在每次兑换时延迟解析,因此即使 Claimo 已经加载了其配置后(插件的典型情况)再注册类型也能正常工作。

事件

监听这些事件(zone.vao.claimo.event),方式与任何 Bukkit 事件相同:

事件 触发时机 备注
PlayerRedeemVoucherEvent 要求通过,但在命令执行之前 Cancellable(可取消)——取消以阻止兑换(不执行命令,不显示成功消息)。暴露 player、voucher。
VoucherRedeemedEvent 命令分发之后 信息性事件。暴露 player、voucher。

API 接口

zone.vao.claimo.ClaimoApi

成员 用途
registerRequirement(type, factory) 注册一种要求类型。
unregisterRequirement(type) 移除已注册的类型。
requirements RequirementRegistry(包含 isRegistered、types 等)。
stats ClaimoStats —— 只读的 blocksMined(player)、blocksMined(player, whitelist, blacklist)、playtimeSeconds(player)。
vouchers() / voucher(id) 列出已加载的凭证 / 查找某个凭证。
redeem(player, voucherId) 以编程方式运行完整的兑换流程。
reload() 重新加载配置和凭证文件。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源