Kyokalith

# Kyokalith

[繁體中文](https://github.com/TinyYana/Kyokalith/blob/main/README.zh-TW.md)

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:

1. 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. 2. 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. 3. 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. 4. 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. 5. 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

1. Drop `Kyokalith-.jar` into `plugins/` and start the server. 2. A default `config.yml` is generated with all 11 ore types (including nether ores) enabled — it works out of the box. 3. 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 co