_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 <兑换码> <数字\|inf>` | 修改可兑换次数 | `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 ``` ```yaml 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
```

```yaml
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 it survives name changes and server restarts
- Concurrent redemptions are processed on the main thread and cannot over-issue uses

---

VeloCDK is part of the **SHINE Network** toolset.

VeloCDK

Compatibility

Minecraft: Java Edition

Platforms

Tags

Creators

Details