VeloCDK

For English introduction, please scroll down.

VeloCDK

一个轻量、零依赖的 Paper / Spigot 1.21.11 兑换码（CDK）插件。
创建兑换码、绑定控制台命令、限制使用次数、设置过期时间，并阻止同一玩家重复兑换。

没有数据库、没有外部接口、没有多余功能 —— 只有一个 YAML 文件和几条干净的指令。

为什么选择 VeloCDK？

市面上的兑换码插件，要么早已停止维护，要么塞满你根本用不上的 GUI 菜单，要么在新版 Paper 上直接报错。VeloCDK 选择相反的路：

• 只做一件事。 创建兑换码、发放、让玩家兑换，仅此而已。
• 全部以控制台身份执行。 奖励命令永远不以玩家身份运行，无法通过命令语法钻空子。
• 一人一次。 内置防刷机制，同一玩家无法重复兑换同一个码，重启服务器也依然有效。
• 支持聊天兑换。 玩家直接在聊天框输入兑换码即可。该消息会被拦截并不会广播，兑换码不会泄露给其他在线玩家。
• 并发安全。 多人同时兑换不会超发。实测 6 名玩家抢一个 3 次的兑换码，结果恰好 3 人成功。
• 体积小、速度快。 12 个类，约 46 KB，除服务端 API 外无任何依赖。

功能

兑换码管理

功能 · 说明
创建兑换码 · 一个兑换码可绑定一条或多条控制台命令
使用次数 · 可设置固定次数，或填 inf 表示无限制
过期时间 · 支持 min / hour / day 三种单位
一人一次 · 每名玩家对每个兑换码只能兑换一次
使用记录 · 可查看谁在什么时间兑换过
在线修改 · 随时调整已有兑换码的次数或有效期
数据持久化 · 所有改动即时写入 codes.yml

兑换方式

• /cdk use —— 命令兑换
• 在聊天框直接输入兑换码 —— 自动拦截、执行兑换，且不广播给其他玩家
• 奖励命令以控制台身份执行，命令中的 %player% 会替换为玩家名
• 兑换码不存在 / 已过期 / 次数用尽 / 已兑换过，都会安全失败，不会消耗次数

显示效果

• 颜色区分：绿色表示成功，红色表示错误，灰色为标签，白色为数值
• /cdk list 列出所有兑换码及其状态、剩余次数与剩余时间
• /cdk info 分三个清晰的区块显示：详细信息、命令列表、使用记录
• 列表使用彩色状态圆点（绿色可兑换、红色已过期或用尽）
• 分隔线宽度经过调整，在默认聊天框内不会折行

命令

所有命令以 /cdk 开头（别名 /vcdk）。

命令 · 说明 · 权限
/cdk help · 显示帮助 · velocdk.use
/cdk list · 列出所有兑换码及状态 · velocdk.use
/cdk info · 详细信息：详情、命令、使用记录 · velocdk.use
/cdk use · 自行兑换 · velocdk.use
/cdk add · 创建兑换码 · velocdk.admin
/cdk set count · 修改可兑换次数 · velocdk.admin
/cdk set time · 设置有效期 · velocdk.admin
/cdk remove · 删除兑换码 · velocdk.admin

velocdk.use 默认所有玩家都有；velocdk.admin 默认仅管理员。

使用示例

创建简单兑换码

/cdk add HelloWorld give %player% diamond 3 5

可使用 5 次，每次给予 3 颗钻石。

用分号分隔多条命令

/cdk add VIP give %player% diamond 1;say 欢迎 %player%;effect give %player% speed 60 1 true 2

奖励命令不需要加引号，直接书写即可。多条命令之间用英文分号 ; 分隔。
如果你习惯加引号，插件也会自动去除，两种写法都支持：

/cdk add VIP "give %player% diamond 1;say 欢迎 %player%" 10

无限制次数

/cdk add Unlimited give %player% emerald 64 inf

设置有效期

/cdk set time HelloWorld 5 min # 五分钟后过期
/cdk set time HelloWorld 2 hour # 两小时后过期
/cdk set time HelloWorld 1 day # 一天后过期

修改可兑换次数

/cdk set count HelloWorld 20
/cdk set count HelloWorld inf

查看兑换码详情

/cdk info HelloWorld

──────── 详细信息 ────────
兑换码 HelloWorld
状态 可兑换
剩余 4 / 5 次
过期 1小时59分钟59秒后
──────── 命令列表 ────────

1. give %player% diamond 3
2. say 欢迎 %player%

──────── 使用记录 ────────
总计 1 人 · 剩余 4 次

1. Steve (2025-11-07 21:46:40)

────────

玩家如何兑换

两种方式，均受 velocdk.use 权限控制：

方式一：命令

/cdk use HelloWorld

方式二：直接在聊天框输入

玩家在聊天框发送 HelloWorld。VeloCDK 识别到这是一个已注册的兑换码后，会取消该条消息（其他玩家看不到），并在主线程上执行奖励命令。

只有内容恰好等于某个兑换码的消息才会被拦截。普通聊天，以及句中包含兑换码的消息，都不会受影响。

兑换规则

一次兑换成功，必须同时满足以下所有条件：

• 兑换码存在
• 尚未过期
• 该玩家此前未兑换过（按 UUID 判定）
• 剩余次数不为 0（inf 除外）
• 兑换码至少绑定了一条可执行命令

失败时会给出明确原因：

情况 · 提示
兑换码不存在 · 兑换码不存在
已过期 · 兑换码已过期
该玩家已兑换过 · 你已经兑换过该兑换码了
次数用尽 · 兑换码使用次数已用尽
未绑定命令 · 兑换码配置有误

兑换失败不会消耗次数，也不会发放任何物品。

说明：inf 表示全局次数无限制，但"一人一次"的限制依然生效，即每名玩家对 inf 兑换码仍只能兑换一次。

兑换码命名规则

兑换码只允许包含字母、数字和短横线：[A-Za-z0-9-]+

• HelloWorld —— 合法
• SPRING-2025 —— 合法
• Hello_World —— 会被拒绝（不允许下划线）
• 中文兑换码 —— 会被拒绝

查找不区分大小写（/cdk use helloworld 也能用），但各处显示都会保留你最初创建时的大小写。

安装

1. 把 VeloCDK-x.x.x.jar 放入服务端的 plugins/ 目录。
2. 重启服务器（或执行 /reload confirm）。
3. 控制台显示 Welcome! 即安装完成。

需要 Java 21 与 1.21.11 的 Paper/Spigot 系服务端。

配置文件

无需任何配置。所有文本内置于插件中，所有数据保存在：

plugins/VeloCDK/codes.yml

codes:
HelloWorld:
commands:

• give %player% diamond 3
• say 欢迎 %player%

max-uses: 5 # -1 表示无限制
used: 1 # 已成功兑换次数
expires-at: 1762500000000 # 0 表示永不过期
usage:
HelloWorld:

• player: Steve

uuid: 069a79f4-44e9-4726-a5be-fca90e38aaf5
at: 1762480000000

写入采用原子替换（临时文件 + 移动），中途崩溃不会损坏数据。文件损坏时只会记录一条警告，既不会导致服务器崩溃，也不会清空已有兑换码。

权限

权限节点 · 默认 · 说明
velocdk.use · 所有玩家 · 查看兑换码并兑换
velocdk.admin · 仅管理员 · 创建、修改、删除兑换码

/cdk 命令本身故意不设权限，这样 /cdk list、/cdk info、/cdk help 对所有玩家可用；管理类子命令则在各自逻辑内单独校验权限。

兼容性

Minecraft · 1.21.11
服务端 · Paper、Spigot、Purpur、Leaf（基于 Paper API 开发）
Java · 21
依赖 · 无
Folia · 不支持（已标记 folia-supported: false）

数据安全

• 兑换次数在发放奖励之前扣减，即使奖励执行失败也不会导致次数被多扣
• 多条奖励命令中若有一条执行失败，其余命令仍会继续执行
• "一人一次"按 UUID 判定，玩家改名或服务器重启都不会失效
• 并发兑换在主线程串行处理，不会超发次数

VeloCDK 是 SHINE Network 工具集的一部分。

English Version

Lightweight redeem code (CDK) plugin for 1.21.11. Create codes that run console commands, with use limits, expiry timers, one redemption per player, and chat-based redemption.

A lightweight, dependency-free redeem code (CDK) plugin for Paper / Spigot 1.21.11.
Create codes that run console commands, control how many times they can be used, set expiry
timers, and stop the same player from redeeming twice.

No database, no external API, no bloat — just one YAML file and a few clean commands.

Why VeloCDK?

Most redeem-code plugins on the market are either abandoned, **bloated with GUI menus you
never asked for, or **broken on modern Paper. VeloCDK takes the opposite approach:

• Single purpose. Create codes, hand them out, let players redeem. That's it.
• Runs everything as console. Reward commands are never executed as the player, so nothing

can be exploited by clever command syntax.

• One player, one redemption. Built-in anti-abuse — the same player physically cannot farm a

code twice, even across server restarts.

• Chat redemption. Players can just type the code in chat. The message is intercepted and

never broadcast, so codes aren't leaked to everyone online.

• Race-free. Concurrent redemptions are safe. Six players hitting a 3-use code ends with

exactly 3 successes.

• Tiny and fast. 12 classes, ~46 KB, no dependencies beyond the server API itself.

Features

Redeem code management

Feature · Description
Create codes · Attach one or many console commands to a single code
Use limits · Set a finite number of redemptions, or inf for unlimited
Expiry timers · Codes can expire after min / hour / day
Per-player limit · Every player may redeem each code exactly once
Usage tracking · See exactly who redeemed what, and when
Live editing · Change the use count or expiry of an existing code
Persistence · Everything saved to a single codes.yml immediately

Redemption

• /cdk use — the explicit command
• Type the code in chat — intercepted, redeemed, and never broadcast to other players
• Reward commands execute as console with %player% substituted
• A missing, expired, exhausted or already-used code fails safely without consuming a use

Display

• Colour-coded output: green for success, red for errors, grey labels, white values
• /cdk list shows every code with its status, remaining uses and time left
• /cdk info shows three clean blocks: details, command list, and usage log
• Coloured status dots on the list (green = redeemable, red = expired or exhausted)
• Divider widths tuned so nothing wraps in the default chat box

Commands

All commands start with /cdk (alias: /vcdk).

Command · What it does · Permission
/cdk help · Show the help menu · velocdk.use
/cdk list · List every code and its status · velocdk.use
/cdk info · Details: fields, commands, usage log · velocdk.use
/cdk use · Redeem a code yourself · velocdk.use
/cdk add · Create a new code · velocdk.admin
/cdk set count · Change the redemption limit · velocdk.admin
/cdk set time · Set how long the code stays valid · velocdk.admin
/cdk remove · Delete a code · velocdk.admin

velocdk.use is granted to everyone by default. velocdk.admin defaults to operators only.

Examples

Create a simple code

/cdk add HelloWorld give %player% diamond 3 5

5 uses, giving 3 diamonds each time.

Multiple commands with ;

/cdk add VIP give %player% diamond 1;say Welcome %player%;effect give %player% speed 60 1 true 2

Reward commands do not need quotes — write them naturally. Separate several commands with a
semicolon (;). If you prefer to quote commands, quotes are accepted and stripped, so both
forms work:

/cdk add VIP "give %player% diamond 1;say Welcome %player%" 10

Unlimited uses

/cdk add Unlimited give %player% emerald 64 inf

Give a code a time limit

/cdk set time HelloWorld 5 min # expires in five minutes
/cdk set time HelloWorld 2 hour # expires in two hours
/cdk set time HelloWorld 1 day # expires in one day

Change the redemption limit

/cdk set count HelloWorld 20
/cdk set count HelloWorld inf

Inspect a code

/cdk info HelloWorld

──────── 详细信息 ────────
兑换码 HelloWorld
状态 可兑换
剩余 4 / 5 次
过期 1小时59分钟59秒后
──────── 命令列表 ────────

1. give %player% diamond 3
2. say Welcome %player%

──────── 使用记录 ────────
总计 1 人 · 剩余 4 次

1. Steve (2025-11-07 21:46:40)

────────

Note: the plugin's in-game messages are currently Chinese. An English localisation is

planned.

How players redeem

Two ways, both gated by velocdk.use:

1. The command

/cdk use HelloWorld

2. Just type it in chat

A player types HelloWorld into chat. VeloCDK recognises it as a registered code, cancels the
message so other players never see it, and runs the reward on the main thread.

Only messages that are exactly a registered code are intercepted. Ordinary chat, and messages

that merely contain a code mid-sentence, pass through untouched.

Redeem rules

A redemption succeeds only when all of the following are true:

• The code exists
• It has not expired
• This player has not redeemed it before (checked by UUID)
• The remaining use count is not zero (unless the code is inf)
• The code has at least one executable command

Failures are reported with a specific reason for each case (unknown code, expired, already
redeemed, uses exhausted, or misconfigured).

A failed redemption never consumes a use and never grants items.

Note: inf means the global count is unlimited. The per-player limit still applies, so each
player can redeem an inf code once.

Code naming rules

Codes may contain letters, numbers and hyphens only: [A-Za-z0-9-]+

• HelloWorld — valid
• SPRING-2025 — valid
• Hello_World — rejected (underscore not allowed)
• Non-ASCII codes — rejected

Lookups are case-insensitive (/cdk use helloworld works), but the original spelling is kept for
display everywhere.

Installation

1. Drop VeloCDK-x.x.x.jar into your server's plugins/ folder.
2. Restart the server (or /reload confirm).
3. The console prints Welcome! — the plugin is ready.

Requires Java 21 and a 1.21.11 Paper/Spigot-based server.

Configuration

There is nothing to configure. All text lives in the plugin itself, and all data is stored in:

plugins/VeloCDK/codes.yml

codes:
HelloWorld:
commands:

• give %player% diamond 3
• say Welcome %player%

max-uses: 5 # -1 means unlimited
used: 1 # successful redemptions so far
expires-at: 1762500000000 # 0 means never expires
usage:
HelloWorld:

• player: Steve

uuid: 069a79f4-44e9-4726-a5be-fca90e38aaf5
at: 1762480000000

Saves are atomic (temp file + move), so a crash mid-write can't corrupt your codes. A damaged
file logs a warning instead of crashing the server or wiping your codes.

Permissions

Node · Default · Description
velocdk.use · everyone · View codes and redeem them
velocdk.admin · operators · Create, edit and delete codes

There is deliberately no permission on the /cdk command itself, so /cdk list, /cdk info
and /cdk help remain available to every player. Administrative sub-commands are checked
individually.

Compatibility

Minecraft · 1.21.11
Server · Paper, Spigot, Purpur, Leaf (built against Paper API)
Java · 21
Dependencies · None
Folia · Not supported (marked folia-supported: false)

Data safety

• Redemptions are counted before anything is granted, so a failed reward can never leave a

code over-consumed

• If one command in a multi-command reward fails, the remaining commands still run
• The per-player check is keyed on UUID, so