NimBlock 运行由 JSON 规则(而非编译后的 Java)编写的插件。
你只需将一个 jar 文件放入服务器。你的插件是位于 plugins/NimBlock/specs/ 目录下的 .json 文件。引擎会读取它们并执行:当满足这些条件时,则执行相应操作。
插件长什么样
Y=16 以下的钻石矿石仅对拥有特定权限的玩家开放。这就是整个文件,没有任何省略:
{
"specVersion": 1,
"name": "Diamond guard",
"rules": [
{
"name": "Diamond ore below Y=16 is permission-only",
"trigger": { "type": "block.break" },
"conditions": [
{ "type": "text.equals", "params": { "text": "{block}", "value": "DIAMOND_ORE" } },
{ "type": "number.compare", "params": { "left": "{y}", "operator": "<", "right": "16" } },
{ "type": "player.has_permission", "params": { "permission": "mine.diamond" }, "not": true }
],
"actions": [
{ "type": "cancel_event" },
{ "type": "player.send_actionbar", "params": { "message": "&cThat ore is reserved." } }
]
}
]
}
将其保存为 plugins/NimBlock/specs/diamond-guard.json,运行 /nimblock reload,即可生效。无需构建、无需重启、也无需你自己的 jar 包。
大家最先问到的功能
当玩家首次加入时,给他们一颗钻石并欢迎他们。 自 1.1.0 起,这成为一个规则,以下是完整文件内容:
{
"specVersion": 1,
"name": "Welcome gift",
"rules": [
{
"name": "First visit",
"trigger": { "type": "player.join" },
"conditions": [
{ "type": "player.first_time" }
],
"actions": [
{ "type": "player.give_item", "params": { "material": "DIAMOND", "amount": 1 } },
{ "type": "player.send_message", "params": { "message": "&bFirst time here. Take this to get started." } }
]
}
]
}
player.first_time 不会自行创建存储:它会询问 Paper 服务器是否曾经保存过该玩家的数据。因此,在第一次保存之前(对于 player.join 触发器而言即首次加入),它在整个首个会话期间都为真。
为什么这不是代码生成器
任何地方都不会生成 Java 代码。没有编译步骤,没有需要重建的 jar 包,服务器更新时也无需重新编译。你的规则只是数据;引擎是唯一可能需要更改的东西。
这一事实带来的实际影响是:当新的 Minecraft 版本发布时,崩溃的不是你的插件,而是引擎——它只需为所有人承受一次冲击。
它具体能做什么
语法是封闭且已发布的:9 个触发器、11 个条件、14 个动作。每一个及其参数都在你下载任何东西之前就在公共页面上列出:
超出此目录范围的功能是不可能的,并非“在路线图里”。在为此花费一个晚上之前,值得了解的三个限制:
- 条件不嵌套。 仅有
all / any,以及每个条件的 not。没有布尔树结构。
- 引擎自身不保留任何记忆。 它仅对刚刚发生的事件做出反应且不存储任何内容:没有计数器、没有“这个玩家做过多少次”、没有累计值。唯一的例外不是引擎的记忆,而是服务器的:
player.first_time 读取 Paper 自身的玩家数据,因此它在玩家的整个首个会话期间保持为真,直到第一次保存。
- 玩家检查仅限于已发布的条件。 规则可以读取权限、OP 状态、当前世界、当前生命值、玩家脚部当前位置(
player.position)以及主手中的物品材质(player.holding,空手时为 AIR)。player.first_time 读取 Paper 自身的玩家数据,具有上述的首个会话限制。触发值描述事件:在 block.break 下,{x}、{y} 和 {z} 是该方块坐标。不支持方块查询、玩家计数、全背包或护甲检查。
如果你需要一个带有自己的数据库和 GUI 的行会系统,这不是合适的工具,而且永远都不是。
兼容性承诺
规范声明了 specVersion。它是 1,如果引擎遇到其未知的 specVersion,会直接拒绝运行,而不是只运行其中的一部分。今天编写的规范可以在后续相同 specVersion 的引擎上继续运行。这正是冻结语法的全部意义所在。
支持哪些 Paper 版本
Paper 1.21.4 或更高版本,需使用 Java 21 或更高版本。已声明:1.21.4, 1.21.6, 1.21.7, 1.21.8, 1.21.10, 1.21.11, 26.1.2, 26.2。
低于 1.21.4 的版本中引擎拒绝加载,这是刻意为之:两个目录中的动作在那里没有可绑定的目标(player.give_effect 需要 Registry.MOB_EFFECT,该内容出现在 1.21.4 中;player.heal 需要 Attribute.MAX_HEALTH,该内容出现在 1.21.3 中)。一个启动时安静加载但在规则触发时抛出异常的插件,比在启动时就拒绝加载的插件更糟糕,因此 api-version 设为 1.21.4,由 Paper 本身进行拒绝。
版本 1.2.0 已在连接客户端环境下于 Paper 1.21.4 和 26.1.2 上进行了测试。 位置检查和主手检查使用了空手和镐子,在地表和 Y=0 以下进行了验证。早期的兼容性测试覆盖了其他已声明的版本;那些早期运行结果并非针对 1.2.0 的新测试。
1.21.5 和 1.21.9 未在此处声明。 在 1.0.1 的兼容性审查期间,PaperMC 并未提供这两个版本的稳定构建。请使用上述列出的版本之一。
安装方法
- 将 jar 文件放入
plugins/ 目录。
- 启动服务器一次。它将创建
plugins/NimBlock/specs/ 目录。
- 在该文件夹中放入一个
.json 规范文件。
/nimblock reload 可在不重启的情况下重新读取规范。/nimblock list 显示已加载的内容。
规范创建的命令仅在重启后才会出现:Paper 仅在启动期间接受新的命令名称。但命令的内容在重载时会立即生效。
规范是整体被接受或拒绝,而非逐条判断:若保护插件缺少关键的保护规则,其在游戏中将完全不可见。拒绝记录会在控制台中显示为一条红线。
网络使用
无需联网。无遥测、无统计数据、无许可证检查、无任何出站连接。唯一的编译依赖项是 paper-api。
规范的来源
你可以直接对照模式(schema)手动编写规范,也可以访问 上的可视化编辑器进行构建:两者使用相同的语法和文件格式。该编辑器仅为便捷工具,并非必需:引擎仅读取你放置于服务器中的文件。
需要 Paper 1.21.4 或更高版本,以及 Java 21 或更高版本。非官方 Minecraft 服务。未经 Mojang 或 Microsoft 批准,亦与其无关。
NimBlock runs plugins that are written as JSON rules instead of compiled Java.
You drop one jar on your server. Your plugins are .json files in plugins/NimBlock/specs/. The engine reads them and executes them: when this happens, if these conditions hold, then do that.
What a plugin looks like
Diamond ore below Y=16 is reserved to players with a permission. That is the whole file, nothing omitted:
{
"specVersion": 1,
"name": "Diamond guard",
"rules": [
{
"name": "Diamond ore below Y=16 is permission-only",
"trigger": { "type": "block.break" },
"conditions": [
{ "type": "text.equals", "params": { "text": "{block}", "value": "DIAMOND_ORE" } },
{ "type": "number.compare", "params": { "left": "{y}", "operator": "<", "right": "16" } },
{ "type": "player.has_permission", "params": { "permission": "mine.diamond" }, "not": true }
],
"actions": [
{ "type": "cancel_event" },
{ "type": "player.send_actionbar", "params": { "message": "&cThat ore is reserved." } }
]
}
]
}
Save it as plugins/NimBlock/specs/diamond-guard.json, run /nimblock reload, and it is live. No build, no restart, no jar of your own.
The one everybody asks for first
When a player joins for the first time, give them a diamond and welcome them. Since 1.1.0 that is a rule, and this is the whole file:
{
"specVersion": 1,
"name": "Welcome gift",
"rules": [
{
"name": "First visit",
"trigger": { "type": "player.join" },
"conditions": [
{ "type": "player.first_time" }
],
"actions": [
{ "type": "player.give_item", "params": { "material": "DIAMOND", "amount": 1 } },
{ "type": "player.send_message", "params": { "message": "&bFirst time here. Take this to get started." } }
]
}
]
}
player.first_time invents no storage of its own: it asks Paper whether the server has ever saved that player. So it is true for their whole first session, until the first save, and under player.join that is their first join.
Why this isn't a code generator
Nothing generates Java anywhere. There is no compilation step, no jar to rebuild, nothing to recompile when the server updates. Your rules are data; the engine is the only thing that ever needs to change.
The consequence that actually matters: when a new Minecraft version lands, it isn't your plugin that breaks, it's the engine that takes the hit once, for everyone.
What it can do, exactly
The grammar is closed and published: 9 triggers, 11 conditions, 14 actions. Every one of them, with its parameters, is on a public page before you download anything:
Anything outside that catalogue is impossible, not "on the roadmap". Three limits worth knowing before you spend an evening on it:
- Conditions don't nest.
all / any, plus a not per condition. No boolean tree.
- The engine keeps no memory of its own. It reacts to what just happened and stores nothing: no counters, no "how many times has this player done that", no cumulative anything. The one exception is not its memory but the server's:
player.first_time reads Paper's own player data, so it stays true for a player's whole first session, until the first save.
- Player checks are limited to the published conditions. A rule can read permission, op status, current world, current health, the current position of the player's feet (
player.position) and the material in their main hand (player.holding, AIR for an empty hand). player.first_time reads Paper's own player data, with the first-session limit described above. Trigger values describe the event: under block.break, {x}, {y} and {z} are the block's coordinates. No block lookups, player counts, full-inventory or armor checks.
If you need a guild system with its own database and GUI, this is the wrong tool and it always will be.
Compatibility promise
Specs declare specVersion. It is 1, and the engine refuses outright a spec whose specVersion it doesn't know, rather than running half of it. A spec written today keeps running on later engines of the same specVersion. That is the whole point of freezing the grammar.
Which Paper versions
Paper 1.21.4 or newer, on Java 21 or newer. Declared: 1.21.4, 1.21.6, 1.21.7, 1.21.8, 1.21.10, 1.21.11, 26.1.2, 26.2.
Below 1.21.4 the engine refuses to load, and that is deliberate: two catalogue actions have nothing to bind to there (player.give_effect needs Registry.MOB_EFFECT, which lands in 1.21.4, and player.heal needs Attribute.MAX_HEALTH, which lands in 1.21.3). A plugin that loads quietly and throws the day a rule fires is worse than one that refuses on startup, so api-version is 1.21.4 and Paper does the refusing itself.
Version 1.2.0 was tested with a connected client on Paper 1.21.4 and 26.1.2. The position and main-hand checks were exercised with an empty hand and a pickaxe, at the surface and below Y=0. Earlier compatibility tests covered the other declared versions; those earlier runs are not new tests of 1.2.0.
1.21.5 and 1.21.9 are not declared here. At the compatibility review for 1.0.1, PaperMC offered no stable build for either version. Use one of the versions listed above.
Installing
- Drop the jar in
plugins/.
- Start the server once. It creates
plugins/NimBlock/specs/.
- Put a
.json spec in that folder.
/nimblock reload re-reads specs without a restart. /nimblock list shows what's loaded.
A command created by a spec only appears after a restart: Paper only accepts new command names during startup. The contents of a command reload live.
A spec is accepted or rejected as a whole, never rule by rule: a protection plugin missing the rule that protects would be invisible in game. Rejections are one red line in the console.
Network use
None. No telemetry, no stats, no license check, no outbound connection of any kind. The only compile dependency is paper-api.
Where the specs come from
You can write them by hand against the schema, or build them in a visual editor at : same grammar, same file. The editor is a convenience, not a requirement: the engine only ever reads the file you put on your server.
Requires Paper 1.21.4 or newer, on Java 21 or newer. Not an official Minecraft service. Not approved by or associated with Mojang or Microsoft.
评论 0
登录后参与评分
还没有评论,来抢沙发吧