
重要提示:
配置文件更改后,必须重启服务器才能生效。
KrepAPI-Plugin
当玩家按下按键时运行服务器命令——通过简单的 YAML 文件配置,无需编程。
此插件是 KrepAPI 的“服务端”部分。它与玩家游戏客户端上的官方 KrepAPI 模组通信,注册自定义按键,当有人按下你分配的按键时,它会以该玩家的身份运行命令(权限等同于他们在聊天栏中手动输入)。
这适合我吗?
| 如果你想要… |
此插件 |
可以运行 /menu、/warp shop 等命令的额外按键 |
是 |
| 一个允许所有人使用原版客户端加入的服务器 |
仅当你关闭严格模组检查时适用(见下文);否则玩家需要安装 KrepAPI 模组 |
| 仅在 Spigot 上运行,或客户端不需要 Fabric + KrepAPI 的功能 |
否——玩家需要为其 Minecraft 版本安装匹配的 KrepAPI 模组 |
你需要什么
- Paper 服务器,大致支持 1.21.4 到 26.1.1(一个插件 JAR 适用于该版本范围;更新后务必在确切的 Paper 构建版本上进行测试)。
- Java 版本需符合你的 Paper 下载要求(通常为 Java 21;较新的 Minecraft 版本可能需要更高版本的 Java——请遵循 Paper 下载页面的说明)。
- 在每位玩家的电脑上:需要 Minecraft + Fabric + KrepAPI 模组,且构建版本需与他们的游戏版本匹配(例如 1.21.x 和 26.x 需要不同的模组文件——详见 KrepAPI 项目)。
直白地说: 我们旨在通过使用通用且稳定的 API,让一个 JAR 包兼容多个 Paper 版本。如果未来的 Paper 更新导致问题,你可能需要更新插件——若发生这种情况,请报告给我们。
安装(普通服务器管理员)
- 下载
KrepAPI-Plugin-*.jar(从发布页面获取或自行构建——见下文)。
- 将其放入服务器的
plugins 文件夹中。
- 启动服务器一次,以便生成
config.yml。
- 编辑
plugins/KrepAPI/config.yml(绑定、超时时间等)。
- 重启服务器以确保更改可靠应用(除非你知道自己在做什么,否则避免使用
/reload)。
配置 (config.yml)
全局选项
| 设置项 |
默认值 |
通俗解释 |
require-krepapi |
true |
如果为 true,没有该模组(或未在规定时间内完成设置)的玩家将被踢出。仅在你接受原版客户端或不完整握手的情况下设为 false。 |
minimum-mod-version |
"1.0" |
你允许的最低 KrepAPI 模组版本。语法错误会导致插件在启动时禁用——请检查服务器日志。 |
handshake-timeout-ticks |
200 |
在踢出玩家之前等待客户端响应的时长(20 tick ≈ 1 秒)。 |
每个按键:bindings.<your-id>
| 设置项 |
默认值 |
通俗解释 |
key |
(必填) |
游戏使用的键盘代码(GLFW)。网上有许多列表(例如 71 通常代表 G)。 |
display-name |
(必填) |
玩家在控制界面中看到的名称。 |
command |
(必填) |
按下按键时运行的命令(带或不带 /)。以玩家身份运行,因此权限与普通聊天命令相同。 |
override-vanilla |
false |
如果为 true,会尝试阻止 Minecraft 将该按键用于其默认功能(在客户端支持的情况下)。 |
category |
server |
控制菜单中的分组。 |
示例
bindings:
open_menu:
key: 71
display-name: "Open server menu"
override-vanilla: false
category: server
command: "menu"
损坏的绑定块会被跳过并在控制台记录日志。你可以定义大量的绑定(数千个),在普通服务器上你不会达到上限。
安全性(必读)
- 按键仅运行你在
config.yml 中列出的命令。随机或伪造的数据包无法通过此插件触发其他命令。
- 每个玩家都有短暂的冷却时间,以防止重复数据包滥用命令。
- 尽管如此:命令仍以该玩家的权限运行。除非只有受信任的玩家拥有相关权限,否则不要将按键映射到危险命令上。
从源代码构建(可选)
仅在你进行开发或不使用预编译 JAR 时需要。
- 你需要 KrepAPI 的源代码仓库位于此文件夹旁边(默认为
../KrepAPI),以便 Gradle 能够拉取共享的 protocol 模块。
- 运行
./gradlew build。输出:build/libs/KrepAPI-Plugin-1.0.0.jar。
build.gradle 中的 net.shik:protocol:… 版本必须与 KrepAPI/gradle.properties 中的 mod_version 匹配。
给插件开发者
主类为 net.shik.krepapi.plugin.KrepAPIPlugin。Bukkit 中的插件名称为 KrepAPI。其他插件可以添加额外的最低客户端版本要求:
Plugin k = getServer().getPluginManager().getPlugin("KrepAPI");
if (k instanceof KrepAPIPlugin krep) {
krep.versionGate(this).requireMinimumBuildVersion("1.3.0");
}
协议和版本语法:请参阅 KrepAPI 仓库(docs/protocol.md, docs/paper-plugin.md)。此处的源代码作为你自身 KrepAPI 集成的模板进行了注释。
许可证 / 作者
请参阅本仓库及 plugin.yml 以获取署名和许可信息。

IMPORTANT:
Changes to the config file will not take effect until the server is restarted
KrepAPI-Plugin
Run server commands when a player presses a key—configured in a simple YAML file, no programming required.
This plugin is the “server side” of KrepAPI. It talks to the official KrepAPI mod on the player’s game client, registers your custom keys, and when someone presses a key you assigned, it runs the command as that player (same permissions as if they typed it in chat).
Is this for me?
| You want… |
This plugin |
Extra keys that run /menu, /warp shop, etc. |
Yes |
| A server where everyone can join with a plain vanilla client |
Only if you turn off strict mod checks (see below); otherwise players need the KrepAPI mod |
| Something that works on Spigot only, or without Fabric + KrepAPI on the client |
No—players need the matching KrepAPI mod for their Minecraft version |
What you need
- Paper server, roughly 1.21.4 through 26.1.1 (one plugin JAR for that range; always test on your exact Paper build after updates).
- Java version required by your Paper download (often 21; newer Minecraft lines may ask for a newer Java—follow Paper’s download page).
- On each player’s PC: Minecraft + Fabric + the KrepAPI mod build that matches their game version (e.g. different mod files for 1.21.x vs 26.x—see the KrepAPI project).
Straight talk: we aim for one JAR across many Paper versions by using only common, stable APIs. If a future Paper update breaks something, you may need a plugin update—report it if that happens.
Install (normal server owner)
- Download
KrepAPI-Plugin-*.jar (from releases or build it yourself—see below).
- Put it in your server’s
plugins folder.
- Start the server once so
config.yml is created.
- Edit
plugins/KrepAPI/config.yml (bindings, timeouts, etc.).
- Restart the server so changes apply reliably (avoid
/reload unless you know what you’re doing).
Configure (config.yml)
Global options
| Setting |
Default |
In plain English |
require-krepapi |
true |
If true, players without the mod (or who don’t finish setup in time) can be kicked. Set false only if you accept vanilla clients or incomplete handshakes. |
minimum-mod-version |
"1.0" |
Lowest KrepAPI mod version you allow. Wrong syntax here disables the plugin at startup—check the server log. |
handshake-timeout-ticks |
200 |
How long to wait for the client to answer before kicking (20 ticks ≈ 1 second). |
Per key: bindings.<your-id>
| Setting |
Default |
In plain English |
key |
(required) |
Keyboard code used by the game (GLFW). Many lists exist online (e.g. 71 is often G). |
display-name |
(required) |
Name players see in the Controls screen. |
command |
(required) |
Command that runs when the key is pressed (with or without /). Runs as the player, so permissions are the same as normal chat commands. |
override-vanilla |
false |
If true, tries to stop Minecraft from using that key for its normal job (where the client supports it). |
category |
server |
Group in the controls menu. |
Example
bindings:
open_menu:
key: 71
display-name: "Open server menu"
override-vanilla: false
category: server
command: "menu"
Broken binding blocks are skipped and logged in the console. There is a large upper limit on how many bindings you can define (thousands); you won’t hit it on a normal server.
Safety (read this)
- Keys only run commands you listed in
config.yml. Random or forged packets can’t trigger other commands through this plugin.
- There is a short cooldown per player so repeated packets can’t spam commands.
- Still: a command runs with that player’s permissions. Don’t map a key to dangerous commands unless only trusted players have those permissions.
Building from source (optional)
Only needed if you develop or don’t use a prebuilt JAR.
- You need the KrepAPI source repo next to this folder (default:
../KrepAPI) so Gradle can pull the shared protocol module.
- Run
./gradlew build. Output: build/libs/KrepAPI-Plugin-1.0.0.jar.
- The
net.shik:protocol:… version in build.gradle must match mod_version in KrepAPI/gradle.properties.
For plugin developers
The main class is net.shik.krepapi.plugin.KrepAPIPlugin. Plugin name in Bukkit is KrepAPI. Other plugins can add extra minimum client versions:
Plugin k = getServer().getPluginManager().getPlugin("KrepAPI");
if (k instanceof KrepAPIPlugin krep) {
krep.versionGate(this).requireMinimumBuildVersion("1.3.0");
}
Protocol and version syntax: see the KrepAPI repo (docs/protocol.md, docs/paper-plugin.md). The source here is commented as a template for your own KrepAPI integrations.
License / authors
See this repository and plugin.yml for credits and licensing.
评论 0
登录后参与评分
还没有评论,来抢沙发吧