Azentials - 服务器基础插件

Azentials - 服务器基础插件

适用于 NeoForge 1.21.1 的现代、可配置基础功能模组,包含家园、传送点、传送、实用工具、礼包、管理工具以及可选的客户端增强功能。

管理

-- 你知道吗?我们有一个 Discord?https://discord.gg/J6h8NzdgCK --

🧰 Azentials

面向 NeoForge 服务器的现代化、可配置基础功能

Minecraft 1.21.1 · NeoForge · Java 21

服务器优先 · 客户端可选

通过一个一致的服务器优先系统,提供家、传送点、传送、玩家实用工具、套件、管理工具等更多功能。

Azentials 是 Arctic's Essentials 的全新继任者,围绕共享基础设施、更安全的持久化、可配置权限以及可预测的服务器权威行为进行了重建。


⚠️ 强烈鼓励提交 Bug 报告

Azentials 会与许多服务器系统交互,包括传送、物品栏、持久化、权限、消息和玩家状态。

我只有一名开发者,无法测试所有可能的服务器配置或边界情况,因此如果你遇到 Bug 或兼容性问题,请加入 Discord 并报告。


🚀 功能

  • 🏠 家 - 创建和管理持久化的个人传送位置
  • 🌍 服务器传送点 - 由管理员管理、可供玩家使用的目的地
  • 📍 出生点和返回 - 可配置的服务器出生点,并持久记录上一个位置和死亡历史
  • 🤝 传送请求 - /tpa 和 /tpahere,带有可点击的接受和拒绝控件
  • 🎲 随机传送 - 有界异步 RTP,支持可配置的搜索限制和冷却时间
  • ⏱️ 共享传送生命周期 - 一致的预热、冷却、取消规则和目的地验证
  • 🛡️ 安全传送验证 - 检查世界边界、站立空间、支撑、流体、危险方块和维度访问权限
  • 😴 AFK 和玩家状态 - 手动或自动 AFK、/seen 以及持久化游戏时长
  • 💬 私密消息 - /msg、/reply、忽略控件以及工作人员求助请求
  • 📜 服务器信息 - 可配置的 /rules 和 /motd
  • 🧰 便携实用工具 - 工作台、末影箱、垃圾桶菜单和可配置套件
  • ❤️ 管理工具 - 治疗、喂食、飞行、无敌模式、修复、广播和实时物品栏编辑
  • 🔐 感知权限的命令 - NeoForge 权限节点,可选支持外部权限提供者
  • 💾 经过验证的持久化 - 损坏或不支持的数据会被阻止,而不是被静默覆盖
  • 🌐 服务器优先设计 - 普通玩家无需在客户端安装 Azentials
  • 🖥️ 可选的增强客户端 UI - 安装了 Azentials 的玩家会获得精致的物品栏编辑器,而原版客户端仍保留完整功能

🏠 家

玩家可以创建和管理命名的家:

  • /sethome [name]
  • /home [name]
  • /delhome [name]
  • /homes

家支持可配置的数量限制、传送预热、冷却时间以及共享的 Azentials 传送安全系统。

默认限制为每位玩家 3 个家。


🌍 传送点

Azentials 提供持久化的服务器范围传送点:

  • /warp [name]
  • /setwarp <name>
  • /delwarp <name>
  • /warps

传送点的创建和删除默认仅限管理员,普通玩家可以使用已配置的目的地。


📍 出生点和返回

出生点

  • /spawn
  • /setspawn
  • /delspawn

在管理员创建自定义 Azentials 出生点之前,/spawn 会回退到原版主世界出生点。

返回

  • /back

Azentials 会在每次成功的 Azentials 传送之前记录玩家离开的位置。

默认情况下,玩家最近的死亡位置也会被记录。

使用 /back 成功后会记录离开的位置,使玩家可以在两个最近位置之间往返。


🤝 传送请求

Azentials 包含轻量级的玩家对玩家传送请求:

  • /tpa <player>
  • /tpahere <player>
  • /tpaccept
  • /tpdeny
  • /tpcancel
  • /tptoggle

收到的请求包含可点击的接受和拒绝聊天控件。

每个按钮都绑定到创建它的那个具体请求,因此旧按钮无法意外接受或拒绝更新的请求。

玩家可以通过 /tptoggle 持久禁用收到的传送邀请。

每位玩家可以有一个发出的请求,每个目标可以有一个收到的请求。请求会自动过期,并在任一玩家离开时被移除。


🎲 随机传送

/rtp 会在世界共享出生点周围的可配置环带内搜索。

Azentials 不会同步等待地形生成。

相反,RTP 会:

  • 使用公平的服务器范围队列
  • 一次最多请求一个候选区块
  • 在后续服务器 tick 中检查区块是否就绪
  • 限制候选频率
  • 限制区块加载量和总搜索时间
  • 支持通过 /tpcancel 取消
  • 在取消或搜索失败后应用重试冷却
  • 在配置的传送预热期间保持成功目的地处于加载状态

默认 RTP 范围为 500 到 5,000 格,最多尝试 24 次。


⏱️ 共享传送系统

家、传送点、出生点、返回、TPA 和 RTP 都使用同一个共享传送生命周期。

这使各功能之间的行为保持一致。

玩家同一时间只能有一个活动传送或 RTP 搜索。

活动传送可以通过以下方式取消:

  • 死亡
  • 重生
  • 登出
  • 维度变更
  • 预热期间移动
  • 配置允许时的受伤

待处理的 TPA 邀请与活动传送操作保持独立。

每个传送功能都可以有自己的预热和冷却设置。


🛡️ 传送安全

在移动玩家之前,Azentials 会立即验证目的地。

检查包括:

  • 世界边界
  • 站立空间
  • 玩家脚下的支撑
  • 流体
  • 已知危险方块
  • 维度可用性

台阶、楼梯和地毯可以提供有效支撑。

不安全的目的地会被拒绝,而不是将玩家移动到猜测的附近位置。

安全检查失败不会消耗成功传送的冷却时间,也不会修改 /back。


😴 AFK、Seen 和游戏时长

AFK

/afk [reason]

玩家可以手动切换 AFK 状态,并可选提供原因。

活动会自动清除 AFK。

自动空闲检测默认值为 5 分钟,可以禁用。

Seen

/seen <player>

显示玩家是在线、AFK,还是已离线多长时间。

支持此前记录的用户名和 UUID 进行离线查询。

游戏时长

/playtime [player]

显示累计游戏时长,包括 AFK 时间。

新的 Azentials 配置文件会从 Minecraft 现有的游戏时长统计中初始化。

查询其他玩家的游戏时长需要额外权限。


💬 消息

Azentials 提供玩家私密消息:

  • /msg <player> <message>
  • /tell <player> <message>
  • /w <player> <message>
  • /reply <message>
  • /r <message>
  • /ignore <player>

私密消息保留 Minecraft 正常的签名消息传递和过滤机制。

/reply 会以玩家最近的私密对话为目标。

回复目标会在玩家登出时清除。

被忽略的玩家之间无法互相发送私密消息或 TPA 请求。

忽略不会过滤公共聊天。


🆘 工作人员求助

/helpop <message>

玩家可以向拥有接收权限的在线工作人员和服务器控制台发送消息。

请求之间的默认冷却时间为 30 秒。


📜 规则和 MOTD

  • /rules
  • /motd

两条命令都会显示由服务器所有者定义的可配置纯文本行。


📡 延迟

/ping [player]

显示玩家的延迟(毫秒)。

默认情况下,玩家可以查看自己的延迟。

查询其他玩家的延迟需要额外权限。


🧰 玩家实用工具

垃圾桶

/trash

打开一个原版风格的丢弃菜单。

留在菜单中的物品会在菜单关闭时被删除。

光标上的物品会正常返还。

工作台

  • /workbench
  • /craft

打开一个便携的原版工作台。

未使用的合成材料会在菜单关闭时返还。

末影箱

  • /enderchest
  • /ec

打开玩家真正的末影箱物品栏。


🎁 套件

  • /kit [name]
  • /kits

服务器可以配置可重复使用的物品套件,并带有持久化冷却时间。

套件支持:

  • 自定义名称
  • 可配置冷却时间
  • 每个套件最多 36 个物品堆叠
  • 最多配置 256 个套件
  • 持久化冷却跟踪
  • 发放前进行完整物品栏空间验证

只有当整个套件都能放入时才会发放。

领取失败不会消耗套件冷却时间。

套件数据从以下位置加载:

config/azentials-kits.json

Azentials 不会通过套件执行任意命令或加载任意物品数据。


❤️ 管理员命令

Azentials 包含专注的管理实用工具:

  • /heal [player]
  • /feed [player]
  • /fly [player] [on|off]
  • /god [player] [on|off]
  • /repair [player]
  • /invsee <player>
  • /broadcast <message>

这些命令默认需要管理员等级 2。

对其他玩家使用治疗、喂食、飞行、无敌或修复时,还需要相应的 .others 权限。


🎒 物品栏编辑器

/invsee <player>

Azentials 为在线玩家提供实时物品栏编辑器。

当客户端和服务器都安装了当前版本的 Azentials 时,/invsee 会使用 Minecraft 正常的容器纹理打开自定义界面。

布局包括:

  • 目标物品栏和快捷栏
  • 目标盔甲槽
  • 目标副手槽
  • 你自己的物品栏和快捷栏
  • 与目标玩家实时同步

物品可以正常拖动或在物品栏之间转移。

按住 Shift 点击可以在玩家之间转移物品。

盔甲槽只接受有效装备,并且只能放置一件物品。

更改会立即应用到真实物品栏。

可选客户端增强

自定义物品栏界面完全是可选的。

未安装 Azentials 的客户端,或安装了没有自定义界面的旧版本客户端,会收到可用的原版六行物品栏界面。

使用 /invsee 不需要客户端模组或资源包。

这使服务器所有者可以完全将 Azentials 保持在服务器端,同时仍为安装了客户端模组的玩家提供更整洁的界面。


🌐 服务器优先设计

Azentials 主要设计为服务器模组。

玩家无需在本地安装 Azentials 即可连接。

核心命令、传送、实用工具、权限、持久化、套件和管理系统仍由服务器权威控制。

在客户端安装 Azentials 可以启用可选的客户端改进,例如增强的物品栏编辑器界面。

单人游戏会自动使用增强界面,因为客户端和集成服务器都安装了 Azentials。


🔐 权限

Azentials 与 NeoForge 的 Permission API 集成。

不需要单独的权限提供者。

如果没有,Azentials 会使用其内置默认值。

大多数玩家命令默认允许使用。

管理命令通常需要管理员等级 2。

示例包括:

  • azentials.command.home
  • azentials.command.sethome
  • azentials.command.warp
  • azentials.command.spawn
  • azentials.command.back
  • azentials.command.tpa
  • azentials.command.rtp
  • azentials.command.msg
  • azentials.command.afk
  • azentials.command.kit
  • azentials.command.invsee
  • azentials.command.broadcast

其他权限节点控制诸如以其他玩家为目标等操作。

支持整数值的权限提供者还可以覆盖最大家数量、传送计时等值。


⚙️ 配置

Azentials 按用途分离配置。

主要传送和服务器设置存储在:

config/azentials-common.toml

玩家实用工具设置存储在:

config/azentials-utilities.toml

套件存储在:

config/azentials-kits.json

家、传送点、出生点、返回、TPA 和 RTP 系统各有自己的启用开关。

更改功能启用开关需要重启服务器。

已禁用的功能不会注册其命令。

其他兼容的配置值可以通过 NeoForge 重新加载。


⏱️ 默认传送设置

功能 预热 冷却 其他默认值
家 3 秒 10 秒 每位玩家 3 个家
传送点 3 秒 10 秒 跨维度旅行
出生点 3 秒 10 秒 跨维度旅行
返回 3 秒 10 秒 记录死亡位置
TPA 3 秒 10 秒 请求在 60 秒后过期
RTP 0 秒 60 秒 500 到 5,000 格半径,24 次尝试

传送计时使用服务器 tick。

如果服务器运行明显滞后,配置的预热和冷却在实际时间上可能会更长。


💾 持久化数据

Azentials 将持久化服务器数据存储在主世界的 data 目录中。

当前文件包括:

  • azentials_homes.dat
  • azentials_warps.dat
  • azentials_spawn.dat
  • azentials_back.dat
  • azentials_players.dat

玩家数据包括以下信息:

  • 最后在线时间
  • 游戏时长
  • 传送偏好
  • 被忽略的玩家
  • 套件冷却

🛡️ 数据安全

当持久化数据看起来已损坏或不兼容时,Azentials 会有意保持保守。

损坏的文件、无效记录、重复记录或不支持的架构会阻止该存储,而不是静默替换或裁剪它。

发生这种情况时:

  • 命令会报告受影响的存储系统不可用
  • 服务器日志会标明受影响的存储和原因
  • 原始文件会受到保护,禁止写入

这避免了静默销毁可恢复的服务器数据。

进行备份时,请包含 Azentials 数据文件、两个 TOML 配置文件和套件 JSON 文件。

在复制或恢复持久化数据之前,请停止服务器。


🧠 命令命名空间

所有主要的 Azentials 命令也可在 /azentials 下使用。

例如:

/home

也可以用作:

/azentials home

这使服务器可以避免与其他模组或插件的根命令冲突。

/azentials 和 /azentials help [page] 会显示当前玩家有权限使用的已启用命令。


📦 安装

  1. 下载 Azentials JAR
  2. 将其放入服务器的 mods 文件夹
  3. 启动服务器
  4. 通过生成的配置文件配置 Azentials

如需增强客户端界面,请在客户端安装相同版本的 Azentials。

客户端安装是可选的。


📋 要求

  • Minecraft: 1.21.1
  • 加载器: NeoForge 21.1.235 或兼容的后续 21.1.x
  • Java: Java 21
  • 客户端模组: 可选

🔄 Arctic's Essentials 的继任者

Azentials 是 Arctic's Essentials 的全新继任者。

该项目保留了提供实用服务器工具而不必不必要臃肿的原始目标,但其内部架构已围绕更新的系统重建,用于:

  • 传送生命周期协调
  • 权限处理
  • 持久化存储
  • 目的地安全
  • 客户端兼容性
  • 物品栏同步
  • 自动化测试
  • 服务器管理

Azentials 是新实现,而不是原始 Arctic's Essentials 代码库的延续。


🧪 可靠性与测试

Azentials 包含自动化单元测试和 Minecraft GameTests,覆盖核心行为,例如:

  • 传送到达安全
  • 取消的维度旅行
  • 共享传送生命周期行为
  • 权限回退
  • 配置
  • 持久化
  • 物品栏检查行为

开发构建还会使用无头服务器环境和协议级冒烟测试进行测试。

冒烟测试系统可以连接没有 Azentials 客户端模组的原版协议测试客户端,以验证仅服务器端兼容性。


🔐 许可证与权限

保留所有权利 (ARR)

你可以:

  • ✔ 在服务器上使用此模组
  • ✔ 将此模组包含在整合包中
  • ✔ 作为整合包的一部分原样分发此模组

你不得:

  • ❌ 在其他网站重新上传此模组
  • ❌ 分发修改版本
  • ❌ 声称此模组、代码或资源为你所有

如需在整合包之外进行再分发,请联系作者。


由 Azora Development 开发和维护。