Kyokalith
繁體中文
永不触碰世界生成的反 X-Ray 作弊手段。 原版矿物的生成方式与以往完全一致——无需混淆数据包,无需擦除并重新生成矿物,无需扫描区块。任何被实心方块完全包裹的矿物都被视为诱饵:X-Ray、自由视角(freecam)和种子地图工具都能看到它们,但该方块是否真实只有在首次通过挖掘暴露时才会被判定。
作弊者会径直挖向他们透过墙壁看到的矿物——并击中其基岩块;而诚实玩家在洞穴壁上看到的矿物,始终是真实的。
专为 Lycohinya 生存服务器构建(并在该服务器上经过实战测试)。反 X-Ray 核心完全通用——任何 Spigot/Paper 26.2 服务器均可独立运行 Kyokalith。第二个功能(通过 OreCheckTriggerEvent 提供符合条件的矿物检查令牌)是供其他插件集成的可选接口;若未安装监听器,它将保持静默。
实际工作原理
传统的反 X-Ray 方案通常走两条路之一,各有代价:数据包混淆(会被自由视角击败且消耗 CPU)或擦除矿物并由你自己重新生成(需要扫描区块,严重降低 TPS)。Kyokalith 选择了第三条路:
- 世界生成不受影响。 原版矿物保留在生成时的位置。在生成时已经暴露的矿物(如洞穴壁、峡谷面)是真实的,永远不会被修改。
- 完全埋藏的矿物是诱饵。 它们存在于世界文件中,X-Ray 也能看到它们,但它们无法透露矿物的实际位置。
- 唯一的触发条件是“一个方块消失了”。 玩家挖掘、爆炸、火焰、活塞等事件发生后,在一刻钟后,Kyokalith 会检查每个被移除方块的六个面邻居。
- 仅处理首次暴露的邻居。 如果一个方块此前已有其他开放面(即已被看见),则它不会被处理。这条规则同时避免了两种失败模式:玩家在墙上盯着看的矿物绝不会凭空出现,且玩家已经看过的真实矿物也绝不会消失。
- 判定真实性。 确定性函数
f(salt, world, epoch, x, y, z, base block, dimension) 决定结果:命中 → 诱饵变为真实矿物(或普通基岩块变成矿物);未命中 → 诱饵恢复为基岩块(石头 / 深板岩 / 下界岩)。由于该方块尚未发送给任何客户端,诚实玩家根本看不到任何变化。
每次事件的开销由常数界定:移除的方块数 × 6。无扫描、无计划扫描任务、无 ChunkLoadEvent 工作。
当前的诱饵模型取代了早期基于扫描的方法(v1.0 之前的 "v0.3" 版本),后者通过数据包擦除矿物并通过扫描区块重新生成——强制加载 121 个区块导致 TPS 降至 18.9。删除整个扫描管线将其恢复至 20.1。任何“顺便扫描几个区块”的想法在此插件中都是绝对的红线。
被覆盖的矿物永远不会被重新解析
由玩家放置的方块(包括积雪/结冰形成、实体放置以及活塞目标位置)被标记为脏数据(dirty)。脏数据方块永远不会被实体化,且移除脏数据方块不会解析其邻居。
理由:如果有什么东西藏在玩家放置的方块下面,那它在被覆盖前必定已经暴露过。此规则同时阻止了“覆盖诱饵,再挖开以跳过解析”的漏洞,并保证“覆盖真实矿物,稍后挖开,它依然存在”。活塞拉走最后一个覆盖方块也算作移除——你不能用活塞窥探未解析的诱饵。
要求
|
|
| 服务器 |
Spigot 或 Paper 26.2(针对 Spigot API 编译;在生产环境中于 Paper 上运行) |
| Java |
25 |
| 硬依赖 |
无 |
| 软依赖 |
NatureRevive(区块再生桥接,仅在存在时通过反射加载) |
Kotlin 标准库和 SQLite 驱动程序由 Bukkit 库加载器在启动时下载——不打包进 jar 文件。
安装
- 将
Kyokalith-<version>.jar 放入 plugins/ 目录并启动服务器。
- 会自动生成包含所有 11 种矿物类型(包括下界矿物)的默认
config.yml——开箱即用。
- 首次启动会在
plugins/Kyokalith/kyokalith.db 中创建包含随机 salt 的文件。
⚠ 一旦生成,切勿删除数据库或重置 salt。 salt 是将真实矿物位置与世界种子解耦的关键;重置它会重新滚动整个世界中的所有未暴露矿脉。
升级
配置升级是自动的:新键会在启动时合并到现有的 config.yml 中并赋予默认值;你的现有值永远不会被覆盖。值得注意的是,locale 默认为 en——如果你想要其他语言,请设置 locale: zh_TW(或你自己的语言文件)。
命令
/kyokalith(别名 /kyo)。每个子命令都需要 kyokalith.admin 权限。
| 子命令 |
参数 |
功能 |
适用对象 |
stats |
– |
矿物类型计数、符合条件的方块计数、挂起的区块、NatureRevive 桥接状态 |
控制台可用 |
inspect |
<x> <y> <z> [world] |
转储指定坐标的 epoch、方块、脏数据/挂起标志以及矿脉函数结果 |
控制台可用 |
preview |
[radius] 或 <radius> <x> <y> <z> [world] |
暴力扫描立方体区域,报告命中次数及最多 12 个示例坐标 |
仅限玩家 |
sample |
volume [radius] |
同上扫描,仅报告 命中数 / 扫描数 |
仅限玩家 |
resolve |
<x> <y> <z> [world] |
重新运行指定坐标的首次暴露解析(f 是确定性的,可安全重复运行) |
控制台可用 |
suspend |
<cx> <cz> <reason...> |
挂起某区块内的实体化过程 |
仅限玩家 |
resume |
<cx> <cz> |
解除挂起 |
仅限玩家 |
markeligible |
[x y z] |
QA 工具:标记方块为脏数据并为其写入符合条件的令牌 |
仅限玩家 |
giveeligible |
<player> <oreType> <1-64> |
QA 工具:给予携带 PDC 令牌的矿物堆栈 |
控制台可用 |
preview(预览)/ sample(样本)半径被限制在 1..24 之间 —— 这两项是故意设置的暴力计算例外,仅限管理员使用,且永远不会出现在热路径(hot path)中。
权限
| 节点 |
默认值 |
效果 |
kyokalith.admin |
op |
所有 /kyo 子命令 |
kyokalith.bypass |
false |
持有者的挖掘不消耗检查代币,且不触发 OreCheckTriggerEvent。注意:伪装矿石解析仍然会运行 —— 这仅跳过检查路径 |
非生存模式(创造/旁观者/冒险)也永远不会消耗代币。
配置
config.yml 包含三个区块:locale(语言)、database(文件名、脏写回间隔),以及 ores(数据驱动的矿石定义 —— 添加一种矿石类型无需修改代码)。
你最常调整的选项是每个矿石的 cell_chance / density / preferred_y —— 这三个参数 literally 是你服务器经济的“水龙头”。完整的字段参考、命中概率公式以及红线说明请参见 docs/CONFIG.md。
没有 /kyo reload 命令;配置文件仅在 onEnable 时读取一次。
消息 / 语言
管理员命令的输出完全可定制。内置语言包:en、zh_TW。在 config.yml 中设置 locale,然后编辑 plugins/Kyokalith/lang/ 下的文件 —— 你删除的键将回退到内置文本。要添加你自己的语言,请将 lang/en.yml 复制为 lang/<name>.yml,进行翻译,并设置 locale: <name>。
面向开发者
Kyokalith 仅暴露一个集成点:OreCheckTriggerEvent —— 当处于生存模式的玩家挖掘由 Kyokalith 自身生成或追踪的矿石时同步触发。该事件可取消,其 drops 列表可重写。
管理员发放的矿石、WorldEdit 粘贴的矿石以及商店购买的矿石不携带代币,且永远不会触发此事件。精准采集会将代币转移到 ItemStack(PDC)上;放置该方块会将代币存入数据库 —— 因此一块矿石可以被交易、移动并重新挖掘,但会恰好消耗一次检查。
@EventHandler
fun onOreCheck(event: OreCheckTriggerEvent) {
if ((1..20).random() < 15) return // 检查失败:保留掉落物 = 原版掉落
val bonus = event.drops.firstOrNull()?.clone() ?: return
event.drops.add(bonus) // 检查通过:额外增加一件掉落物
}
事件契约、字段、确切的掉落物重写语义,以及反直觉的“取消 ≠ 无掉落”规则详见 docs/API.md。
构建
./gradlew build # 编译 + 单元测试 + jar
./gradlew test # 仅单元测试(矿脉功能、注册表、存储、消息)
./gradlew runServer # 本地 Paper 26.2 测试服务器
plugin.yml 中 libraries: 里的 Kotlin 版本必须与 gradle/libs.versions.toml 匹配,否则你编译时使用的标准库和运行时加载的标准库将是不同的构建版本。
数据
单个 SQLite 文件 plugins/Kyokalith/kyokalith.db(WAL 模式)。存储 salt、每个区块的 epochs、脏位置、已放置的合格矿石以及挂起的区块。架构详情见 docs/API.md。
许可证
TinyYana Universal Software License (TYUSL) 1.0 —— 可免费使用、修改、集成和再分发,包括用于商业服务器;未经书面许可,你不得出售插件本身或将其重新打包为付费产品/服务。
TinyYana · tinyyana.com
Kyokalith
繁體中文
Anti-X-Ray that never touches world generation. Vanilla ores generate exactly as they always have — no packet obfuscation, no wiping-and-regenerating ores, no chunk scanning. Any ore fully enclosed by solid blocks is treated as a decoy: X-Ray, freecam, and seed-map tools all see it, but whether that block is real is only decided the moment it is first exposed by mining.
A cheater tunnels straight toward an ore they can see through the walls — and hits its base block; an honest player looking at an ore in a cave wall is always looking at the real thing.
Built for (and battle-tested on) the Lycohinya survival server. The anti-X-Ray core is fully generic — any Spigot/Paper 26.2 server can run Kyokalith standalone. The second feature (eligible-ore check tokens via OreCheckTriggerEvent) is an optional integration point for other plugins; with no listener installed it simply stays silent.
How it actually works
Traditional anti-X-Ray takes one of two roads, each with a cost: packet obfuscation (defeated by freecam, burns CPU) or wiping ores and regenerating them yourself (requires chunk scanning, kills TPS). Kyokalith takes a third road:
- World generation is untouched. Vanilla ores stay where they generated. Ores that were already exposed at generation time (cave walls, ravine faces) are real and will never be altered.
- Fully buried ores are decoys. They exist in the world file and X-Ray sees them, but they say nothing about where ore actually is.
- The only trigger is "a block disappeared". Player mining, explosions, fire, pistons — one tick after the event, Kyokalith looks at the six face neighbors of each removed block.
- Only neighbors exposed for the first time are processed. A block that already had another open face was already visible — it is never touched. This one rule prevents both failure modes: ore never pops into existence on a wall a player is staring at, and real ore a player has already seen is never wiped.
- Reality is decided. A deterministic function
f(salt, world, epoch, x, y, z, base block, dimension) decides: hit → the decoy becomes real ore (or a plain base block becomes ore); miss → the decoy reverts to its base block (stone / deepslate / netherrack). The block hasn't been sent to any client yet, so honest players see nothing happen at all.
Per-event cost is bounded by a constant: removed blocks × 6. No scanning, no scheduled scan tasks, no ChunkLoadEvent work.
The current decoy model replaced an earlier scan-based approach (pre-v1.0 "v0.3"), which wiped ores via datapack and regenerated them by scanning chunks — 121 force-loaded chunks dragged TPS down to 18.9. Deleting the entire scanning pipeline brought it back to 20.1. Any "let's just scan a few chunks while we're at it" idea is a hard red line in this plugin.
Covered-up ore is never re-resolved
Blocks placed by players (plus snow/ice formation, entity placement, and piston destinations) are marked dirty. Dirty blocks are never materialized, and removing a dirty block does not resolve its neighbors.
Rationale: if something is hiding under a player-placed block, it must have been exposed before it was covered. This rule simultaneously blocks the "cover a decoy, dig it back up to skip resolution" exploit and guarantees "cover real ore, dig it up later, it's still there." A piston pulling away the last covering block counts as removal too — you can't peek at unresolved decoys with pistons.
Requirements
|
|
| Server |
Spigot or Paper 26.2 (compiled against the Spigot API; runs in production on Paper) |
| Java |
25 |
| Hard dependencies |
None |
| Soft dependencies |
NatureRevive (chunk-regeneration bridge, loaded via reflection only if present) |
The Kotlin stdlib and SQLite driver are downloaded at startup by the Bukkit library loader — not shaded into the jar.
Installation
- Drop
Kyokalith-<version>.jar into plugins/ and start the server.
- A default
config.yml is generated with all 11 ore types (including nether ores) enabled — it works out of the box.
- First startup creates
plugins/Kyokalith/kyokalith.db containing a random salt.
⚠ Never delete the DB or reset the salt once generated. The salt is what decouples real ore positions from the world seed; resetting it re-rolls every unexposed vein in the entire world.
Upgrading
Config upgrades are automatic: new keys are merged into your existing config.yml on startup with their default values; your existing values are never overwritten. Notably, locale defaults to en — set locale: zh_TW (or your own lang file) if you want something else.
Commands
/kyokalith (alias /kyo). Every subcommand requires kyokalith.admin.
| Subcommand |
Args |
What it does |
Who |
stats |
– |
Ore type count, eligible block count, suspended chunks, NatureRevive bridge state |
Console OK |
inspect |
<x> <y> <z> [world] |
Dump epoch, block, dirty/suspended flags, and vein-function result for a coordinate |
Console OK |
preview |
[radius] or <radius> <x> <y> <z> [world] |
Brute-force scan a cube, report hits and up to 12 example coordinates |
Short form player-only |
sample |
volume [radius] |
Same scan, reports hits / scanned only |
Player-only |
resolve |
<x> <y> <z> [world] |
Re-run first-exposure resolution for a coordinate (f is deterministic, safe to re-run) |
Console OK |
suspend |
<cx> <cz> <reason...> |
Suspend materialization in a chunk |
Player-only |
resume |
<cx> <cz> |
Lift a suspension |
Player-only |
markeligible |
[x y z] |
QA tool: mark a block dirty and write an eligible token for it |
Player-only |
giveeligible |
<player> <oreType> <1-64> |
QA tool: give a stack of ore blocks carrying PDC tokens |
Console OK |
The preview / sample radius is clamped to 1..24 — these two are deliberate brute-force exceptions, admin-only and never on a hot path.
Permissions
| Node |
Default |
Effect |
kyokalith.admin |
op |
All /kyo subcommands |
kyokalith.bypass |
false |
Holder's mining consumes no check token and fires no OreCheckTriggerEvent. Note: decoy resolution still runs — this only skips the check path |
Non-survival modes (creative/spectator/adventure) never consume tokens either.
Configuration
config.yml has three blocks: locale, database (file name, dirty write-back interval), and ores (data-driven ore definitions — adding an ore type requires no code).
The knobs you'll touch most are each ore's cell_chance / density / preferred_y — these three are literally your server economy's faucet. Full field reference, the hit-probability formula, and the red lines live in docs/CONFIG.md.
There is no /kyo reload; config is read once in onEnable.
Messages / languages
Admin-command output is fully customizable. Bundled locales: en, zh_TW. Set locale in config.yml, then edit the files under plugins/Kyokalith/lang/ — keys you delete fall back to the built-in text. To add your own language, copy lang/en.yml to lang/<name>.yml, translate, and set locale: <name>.
For developers
Kyokalith exposes exactly one integration point: OreCheckTriggerEvent — fired synchronously when a survival-mode player mines an ore that Kyokalith itself produced or tracked. It is cancellable and its drops list is rewritable.
Admin-given ores, WorldEdit-pasted ores, and shop-bought ores carry no token and never fire the event. Silk Touch moves the token onto the ItemStack (PDC); placing the block moves it into the DB — so one ore can be traded, moved, and re-mined, but burns exactly one check.
@EventHandler
fun onOreCheck(event: OreCheckTriggerEvent) {
if ((1..20).random() < 15) return // failed check: leave drops alone = vanilla drops
val bonus = event.drops.firstOrNull()?.clone() ?: return
event.drops.add(bonus) // passed check: one extra drop
}
The event contract, fields, exact drop-rewrite semantics, and the counter-intuitive "cancel ≠ no drops" rule are in docs/API.md.
Building
./gradlew build # compile + unit tests + jar
./gradlew test # unit tests only (vein function, registry, stores, messages)
./gradlew runServer # local Paper 26.2 test server
The Kotlin version in plugin.yml's libraries: must match gradle/libs.versions.toml, otherwise the stdlib you compile against and the one loaded at runtime are different builds.
Data
A single SQLite file, plugins/Kyokalith/kyokalith.db (WAL). Stores the salt, per-chunk epochs, dirty positions, placed eligible ores, and suspended chunks. Schema details in docs/API.md.
License
TinyYana Universal Software License (TYUSL) 1.0 — free to use, modify, integrate, and redistribute, including on commercial servers; you may not sell the plugin itself or repackage it as a paid product/service without written permission.
TinyYana · tinyyana.com
评论 0
登录后参与评分
还没有评论,来抢沙发吧