VoidReturn 虚空回溯

轻量 Paper 插件：记住玩家的「落点」，掉入虚空时自动送回；附带一条独立的随机传送指令。 Lightweight Paper plugin: remembers a player's landing point and sends them back when they fall into the void, plus a standalone random-teleport command.

版本适用 / Version Compatibility

项目 / Item	值 / Value
兼容范围 / Compatibility	Paper 1.17.x – 26.x（理论兼容；仅 26.2 实测）/ Theoretical 1.17–26.x, verified on 26.2
API 版本 / api-version	'1.17'
Java	17（字节码目标；26.x 服以 Java 25 运行）/ 17 bytecode target (26.x servers run it on Java 25)
必需依赖 / Required	无 / None
可选依赖 / Optional	Vault（/vrtp 收费）、PlaceholderAPI（占位符）— 未安装时自动降级 / Vault (charging) and PlaceholderAPI (placeholders); both degrade silently when absent
构建产物 / Artifact	build/libs/VoidReturn-2.5.0.jar

功能 / Features

• 落点机制：玩家在指定世界（landing-worlds）里跨世界传送离开、或在该世界内死亡时，记录当下位置；掉入虚空时送回该位置 / Records a player's position when they leave one of the configured landing-worlds or die inside one; a void fall sends them back there
• 首次自动随机：没有落点记录时，no-landing-action 决定用固定坐标还是随机生成一个落点（并记住）/ When no record exists, no-landing-action picks either a fixed spot or a freshly generated random one (and remembers it)
• 异步安全落点：未加载的区块通过 getChunkAtAsync 加载，绝不阻塞主线程；落点检测排除传送门方块，避免落地即被末地/地狱门再次传送 / Unloaded chunks are fetched via getChunkAtAsync, never blocking the main thread; portal blocks are excluded so a landing spot never drops the player into a portal again
• 落点持久化到 data.yml，重启后保留 / Landing records persist to data.yml, surviving restarts
• 仅在 config.yml 启用的世界触发虚空检测 / Void detection only in worlds listed in config.yml
• 可配置倒计时传送：掉虚空后按 TITLE/SUBTITLE/ACTION_BAR/CHAT/BOSS_BAR 多形式消息倒计时 / Configurable countdown using TITLE/SUBTITLE/ACTION_BAR/CHAT/BOSS_BAR
• /vrtp 随机传送：在当前或指定世界随机传送，支持冷却、经济收费、世界黑名单 / /vrtp random teleport with cooldown, economy charge and world blacklist
• PlaceholderAPI 占位符：%voidreturn_*% 暴露落点、冷却与价格，方便接入菜单 / %voidreturn_*% exposes landing, cooldown and cost for menus

两种典型用法 / Two Common Setups

① 通用虚空安全网（默认配置，行为与旧版一致） 任何世界跨世界传送后掉虚空，送回传送前的位置。保持默认即可。 Works out of the box: any cross-world teleport origin becomes the landing point.

② 「主城跳虚空去探索世界」玩法 把主城作为唯一启用世界、把探索世界作为落点世界，掉虚空时首次随机落地、之后回到自己在探索世界的位置。 Configure the hub as the only enabled world and the exploration world as the landing world:

landing-worlds: [ overworld ]
no-landing-action: random
random:
  world: overworld
enabled-worlds:
  zc: { void-threshold: -64, cooldown-secs: 3, delay-secs: 3, ... }
random-teleport:
  blacklist-worlds: [ zc ]

使用文档 / Documentation

完整指令与配置说明（中英双语）见 USAGE.md。 Full command and configuration guide (bilingual) is in USAGE.md.

许可证 / License

GNU General Public License v3.0

多版本适配 / Multi-version Support

单个 jar 兼容 Paper 1.17.x – 26.x：按最低支持线（1.17.1）编译、api-version: '1.17'、Java 17 字节码。核心逻辑只使用跨版本稳定的 Bukkit/Paper API。 注意：1.17 – 1.21 为理论兼容（未逐一实测），仅 26.2 在本机实测过。 A single jar targets Paper 1.17.x – 26.x: compiled against the lowest supported line (1.17.1), api-version: '1.17', Java 17 bytecode. All logic uses only stable cross-version Bukkit/Paper APIs. Note: 1.17–1.21 is theoretical (not individually tested); only 26.2 is verified locally.

归属声明 / Attribution

本插件的「安全落点搜索」逻辑参考自 NoVoidX（Apache License 2.0），已在相关源文件头保留其版权声明。 The "safe landing spot search" logic references NoVoidX (Apache License 2.0); its copyright notice is retained in the relevant source file header.