📖 AdventureLectern

一、简介

AdventureLectern —— 一款读经台保护与交互式书本 GUI 插件

AdventureLectern 允许服务器管理员将读经台标记为"受保护"状态，放上成书后自动持久化。玩家右键读经台可直接打开书本GUI阅读，而书本和读经台均受到完整保护，无法被任何人（包括创造模式）破坏。适用于服务器规则公告板、NPC 对话展示台、主城告示牌、活动说明等场景。

AdventureLectern 支持 Paper / Purpur 1.21.4+ 服务器（Java 21），并且会第一时间支持未来版本。

AdventureLectern

完整保护 > 受保护的读经台无法被任何人破坏，只能通过命令移除
书本 GUI > 玩家右键即可打开书本界面阅读，使用 Paper openBook API
全息文字 > Display Entity API 显示 MiniMessage 格式提示文字
数据持久化 > 书本自动序列化保存，重启后自动恢复
爆炸/活塞防护 > 防止 TNT、苦力怕、活塞等间接破坏
交互冷却 > 可配置的右键冷却防止刷屏
粒子效果 > 保护读经台上方显示可配置粒子特效
MiniMessage > 全息文字支持 MiniMessage 富文本格式
轻量无依赖 > 无需任何前置插件即可运行

二、插件前置说明

都是非必须

无前置依赖 — 本插件为纯独立插件，无需任何前置

下一篇安装部署 →

📥 安装部署

环境要求

项目	要求
服务端	Paper / Purpur 1.21.4+
Java	Java 21+
依赖	无（纯 Paper API）

安装步骤

将 AdventureLectern-1.1.0.jar 放入服务器 plugins/ 目录
重启服务器
编辑 plugins/AdventureLectern/config.yml 按需调整
执行 /al reload 重载配置

⚠️ 注意

不支持 Spigot，仅支持 Paper / Purpur（依赖 Paper 专属 API）。

文件结构

plugins/AdventureLectern/
├── config.yml          # 主配置
└── lecterns.yml        # 受保护读经台数据

上一篇← 插件总览

下一篇使用流程 →

📋 使用流程

管理员操作流程

在地图上放置一个读经台方块
面对读经台，执行 /al create — 读经台被标记为受保护，全息文字和粒子效果出现
手持成书（WRITTEN_BOOK），右键读经台 — 书本自动放入并保存到文件
完成！玩家现在可以右键阅读

玩家使用

右键受保护的读经台 → 直接打开书本界面阅读
无法取走书本、无法破坏读经台

移除保护

面对受保护的读经台，执行 /al remove
保护标记、全息文字将被移除
读经台恢复为普通方块

💡 提示

/al remove 是解除保护的唯一方式，即使管理员也无法直接破坏受保护的读经台。

上一篇← 安装部署

下一篇保护机制 →

🛡️ 保护机制

保护范围

威胁	保护方式
玩家手动破坏	`BlockBreakEvent` 取消，无权限绕过
创造模式破坏	同上，创造模式也被拦截
TNT / 苦力怕爆炸	`EntityExplodeEvent` 从爆炸列表移除
方块爆炸（床/重生锚）	`BlockExplodeEvent` 从爆炸列表移除
活塞推动/拉动	`BlockPistonExtend/RetractEvent` 取消
取走书本（按钮）	`PlayerTakeLecternBookEvent` 取消
取走书本（物品栏点击）	`InventoryClickEvent` 取消

上一篇← 使用流程

下一篇全息文字 →

✨ 全息文字

技术实现

使用 Paper 原生 Display Entity API（TextDisplay），无需额外依赖。

支持 MiniMessage 格式（如 <yellow>、<gradient:red:blue>）
自动面向玩家（Billboard.CENTER）
可配置缩放、阴影、背景色、可见距离
实体标记为非持久化（persistent=false），插件禁用时自动清除
插件启用时自动重建所有全息文字

配置

hologram:
  enabled: true
  text: "<yellow>右键查看规则"    # MiniMessage 格式
  y-offset: 1.2                    # Y轴偏移
  visibility-distance: 16          # 可见距离（格）
  text-shadow: false
  scale: 1.0
  background-color: "40000000"     # ARGB十六进制

上一篇← 保护机制

下一篇config.yml →

⚙️ config.yml 完整配置

完整参考

# AdventureLectern v1.1.0 主配置

# 读经台保护设置
protection:
  protect-lectern: true    # 是否保护读经台不被破坏
  protect-book: true       # 是否禁止取走书本

# 全息文字设置
hologram:
  enabled: true
  text: "<yellow>右键查看规则"
  y-offset: 1.2
  visibility-distance: 16
  text-shadow: false
  scale: 1.0
  background-color: "40000000"

# 粒子效果设置
glow:
  enabled: true
  particle-type: ENCHANT    # ENCHANT / END_ROD / FLAME
  particle-count: 3
  particle-interval: 20     # tick

# 书本GUI设置
book-gui:
  cooldown: 200    # 毫秒

# 消息设置（支持 & 颜色代码）
messages:
  prefix: "&8[&6读经台&8] "
  # ... 各类消息可自定义

上一篇← 全息文字

下一篇数据存储 →

🗄️ 数据存储

lecterns.yml

所有受保护的读经台数据存储在 plugins/AdventureLectern/lecterns.yml：

lecterns:
  world;100;64;200:
    world: world
    x: 100
    y: 64
    z: 200
    created-at: 1712000000000
    book-data: "rO0ABXNyA..."    # Base64 序列化的书本

管理员放书后自动保存 book-data 字段
服务器重启后自动从 book-data 恢复书本到读经台
使用 Bukkit 序列化（BukkitObjectOutputStream）确保完整保留书本的所有数据

上一篇← config.yml

下一篇命令列表 →

⌨️ 命令列表

主命令：/adventurelectern，别名：/alectern、/al

命令	说明	权限
`/al create`	将面前的读经台标记为受保护	`adventurelectern.create`
`/al remove`	移除面前读经台的保护（唯一解除方式）	`adventurelectern.destroy`
`/al list`	列出所有受保护的读经台坐标	`adventurelectern.admin`
`/al reload`	重载插件配置	`adventurelectern.reload`

上一篇← 数据存储

下一篇权限节点 →

🔐 权限节点

权限	说明	默认
`adventurelectern.admin`	管理员权限（包含所有子权限）	OP
`adventurelectern.create`	创建保护 + 放置书本	OP
`adventurelectern.destroy`	移除保护（仅通过命令）	OP
`adventurelectern.reload`	重载配置	OP

上一篇← 命令列表

下一篇更新日志 →

📝 更新日志

v1.1.0 LATEST

FIX 管理员放书 — 手持成书可以放置到受保护的空读经台
FIX 完全保护 — 受保护的读经台任何人都无法破坏（移除权限绕过）
NEW 书本持久化 — 放书后自动保存到 lecterns.yml，重启自动恢复
NEW 爆炸/活塞防护 — TNT、苦力怕、活塞等间接破坏全面防护

v1.0.0

NEW 初始版本 — 读经台保护、全息文字、粒子效果、书本GUI、管理命令

上一篇← 权限节点