BMNpcForceReload
BMNpcForceReload 是一款专为使用 Citizens 和 BetterModel 的 Paper 及 Folia 服务器设计的完整模型管理与自动修复插件。
Citizens NPC 在服务器重启、插件重载、世界加载、区块加载或单纯经过一段时间后,有时会出现 BetterModel 外观丢失的情况。
BMNpcForceReload 能够自动检测这些 NPC 并重新应用其配置的模型,确保它们正确显示,无需管理员手动进行修复。
功能特性
- 自动将 BetterModel 模型重新应用到 Citizens NPC
- 服务器启动时自动修复
- Citizens 或 BetterModel 重载后自动修复
- 世界或包含 NPC 的区块加载时自动修复
- 智能区块监控与冷却保护机制
- 当模型无法立即应用时自动重试
- 重载队列防止重复或重叠操作
- BetterModel API 检测与命令回退机制
- 自动同步 Citizens 中已配置的模型
- 从 Citizens traits 和
saves.yml 检测模型
- 管理界面 (GUI)
- 完整的 NPC 管理命令
- SQLite 历史记录与状态存储
- PlaceholderAPI 支持
- 供其他插件使用的公共 Java API
- 自定义 Bukkit 事件
- 安全的 Modrinth 更新检查器与下载器
- SHA-512 和 SHA-1 更新验证
- 旧版配置自动迁移
- 法语和英语语言文件
- 支持 Paper 和 Folia
- 支持 Minecraft 1.21.x 和 26.x
- 可配置的使用统计信息
依赖项
必需
可选
自动模型修复
BMNpcForceReload 会检查已配置的 Citizens NPC,并在需要时重新应用其 BetterModel 模型。
触发修复的场景包括:
- 服务器启动时;
- 按可配置的时间间隔;
- Citizens 重载后;
- BetterModel 重载后;
- NPC 所在的世界加载时;
- 包含已配置 NPC 的区块加载时;
- 通过命令手动触发;
- 通过管理界面 (GUI) 触发;
- 通过公共 Java API 触发。
该插件使用队列来防止多个重载操作同时运行。
当模型无法立即应用时,BMNpcForceReload 可以在可配置的延迟后自动重试。
Citizens 同步
BMNpcForceReload 可以自动导入已在 Citizens NPC 上配置的模型。
/bmnpc sync
此命令扫描 Citizens 并导入检测到的 BetterModel 模型,而不会替换现有的 BMNpcForceReload 条目。
要更新已存在的条目,请使用:
/bmnpc sync overwrite
同步系统可以从以下来源检测模型:
- 已加载的 Citizens traits;
- Citizens NPC 元数据;
- 持久化的 Citizens 数据;
plugins/Citizens/saves.yml;
- BetterModel 相关的模型字段;
- BetterModel 蓝图字段。
同步完成后,导入的 NPC 将立即被添加到修复队列中。
管理界面 (GUI)
使用以下命令打开管理菜单:
/bmnpc gui
该 GUI 允许管理员执行以下操作:
- 查看所有已配置的 NPC;
- 查看 Citizens NPC ID;
- 查看已配置的 BetterModel 模型;
- 检查 NPC 是否启用;
- 查看最近的修复状态;
- 重载特定 NPC;
- 启用或禁用 NPC;
- 修复所有已配置的 NPC;
- 重载插件配置。
命令
/bmnpc gui
打开管理界面。
/bmnpc reload
重载插件配置。
/bmnpc all
重载所有已配置的 NPC 模型。
/bmnpc npc <id>
重载特定的 Citizens NPC。
/bmnpc sync
导入 Citizens 中已配置的模型。
/bmnpc sync overwrite
导入 Citizens 模型并更新现有条目。
/bmnpc add <id> <model> [name]
向插件配置中添加新 NPC。
/bmnpc remove <id>
从插件配置中移除 NPC。
/bmnpc setmodel <id> <model>
更改 NPC 的已配置模型。
/bmnpc enable <id>
启用对 NPC 的自动修复。
/bmnpc disable <id>
禁用对 NPC 的自动修复。
/bmnpc status
显示插件的一般状态。
/bmnpc list
显示所有已配置的 NPC。
/bmnpc inspect <id>
显示关于某个 NPC 的详细信息。
/bmnpc history <id>
显示某个 NPC 的重载历史。
/bmnpc validate
验证插件配置及已配置的 NPC。
/bmnpc update
检查 Modrinth 是否有兼容的更新版本。
/bmnpc update download
下载最新的兼容更新版本。
权限
bmnpcforcereload.admin
授予访问所有 BMNpcForceReload 命令的权限。
bmnpcforcereload.reload.all
bmnpcforcereload.reload.single
bmnpcforcereload.gui
bmnpcforcereload.sync
bmnpcforcereload.manage
bmnpcforcereload.status
bmnpcforcereload.list
bmnpcforcereload.inspect
bmnpcforcereload.history
bmnpcforcereload.validate
bmnpcforcereload.update
bmnpcforcereload.config.reload
PlaceholderAPI
当安装 PlaceholderAPI 时,BMNpcForceReload 会自动注册其内置扩展。
可用的占位符:
%bmnpc_total%
%bmnpc_queue%
%bmnpc_running%
%bmnpc_status_<id>%
%bmnpc_model_<id>%
%bmnpc_failures_<id>%
示例:
%bmnpc_status_50%
%bmnpc_model_50%
%bmnpc_failures_50%
SQLite 存储
BMNpcForceReload 将 NPC 状态和修复历史存储在以下位置:
plugins/BMNpcForceReload/data.db
存储的信息包括:
- 上次修复尝试;
- 上次成功修复;
- 最新错误;
- 总成功修复次数;
- 总失败修复次数;
- 修复触发器;
- 使用的 BetterModel 适配器;
- 完整的重载历史记录。
公共 Java API
其他插件可以通过其公共 API 与 BMNpcForceReload 进行交互。
BMNpcAPI.reloadNpc(50);
BMNpcAPI.reloadAll();
BMNpcAPI.getNpcStatus(50);
自定义事件
BMNpcForceReload 提供了自定义的 Bukkit 事件:
BMNpcReloadStartEvent
BMNpcReloadSuccessEvent
BMNpcReloadFailureEvent
这些事件允许其他插件在 NPC 修复开始、成功或失败时做出反应。
安全的 Modrinth 更新
BMNpcForceReload 包含一个连接到官方 Modrinth 项目的完整更新系统:
更新器可以:
- 检测最新的插件版本;
- 选择与当前 Minecraft 版本兼容的版本;
- 支持 Paper 和 Folia 加载器;
- 过滤稳定版、测试版(beta)和开发版(alpha)发布内容;
- 自动下载更新;
- 使用 SHA-512 验证下载的文件;
- 以 SHA-1 作为备用方案;
- 在下一次重启后安全地安装更新。
示例:
updates:
enabled: true
auto-download: false
channel: stable
check-interval-hours: 12
initial-delay-seconds: 30
verify-hash: true
可用的频道:
stable
beta
alpha
下载的更新文件会放置在服务器更新目录中,并在下一次重启后应用。
统计信息
BMNpcForceReload 包含可配置的用法统计功能。
统计功能默认启用:
stats: true
可以随时禁用它们:
stats: false
统计系统会发送基本技术信息,例如:
- 插件名称和版本;
- Minecraft 版本;
- 服务器软件;
- 服务器端口;
- 在线玩家数量;
- 最大玩家数量;
- 匿名安装标识符。
无需 API 密钥。
语言
BMNpcForceReload 包含以下语言:
French
English
在 config.yml 中选择语言:
language: en
法语设置如下:
language: fr
配置迁移
旧版本的 BMNpcForceReload 配置文件会自动迁移到最新格式。
在修改旧配置文件之前,插件会创建备份,例如:
config-v1-backup.yml
config-v2-backup.yml
这使得现有安装可以在无需手动重建每个 NPC 条目的情况下进行更新。
配置示例
language: en
# 启用匿名的插件和服务器使用情况统计。
stats: true
settings:
enabled: true
startup-delay-seconds: 15
interval-seconds: 7200
delay-between-npcs-ticks: 10
debug: false
bettermodel:
# 可用模式:auto, api, command
mode: auto
# 如果 BetterModel API 不可用,则使用命令执行。
fallback-to-command: true
command-template: "npc select %npc_id% && npc model %model%"
queue:
prevent-overlapping: true
merge-duplicate-requests: true
chunk-monitor:
enabled: true
delay-ticks: 20
cooldown-seconds: 10
only-configured-npc-chunks: true
require-spawned-npc: true
updates:
enabled: true
auto-download: false
channel: stable
check-interval-hours: 12
initial-delay-seconds: 30
verify-hash: true
npcs:
navigator:
npc-id: 50
model: "adventure_npc"
enabled: true
reload:
on-startup: true
on-world-load: true
on-chunk-load: true
retry:
attempts: 3
delay-ticks: 40
evil-cube:
npc-id: 43
model: "cubee_evil"
enabled: true
reload:
on-startup: true
on-world-load: true
on-chunk-load: true
retry:
attempts: 3
delay-ticks: 40
seller:
npc-id: 25
model: "seller"
enabled: true
reload:
on-startup: true
on-world-load: true
on-chunk-load: true
retry:
attempts: 3
delay-ticks: 40
为什么使用 BMNpcForceReload?
附加到 Citizens NPC 上的 BetterModel 模型有时会消失或无法正确加载。
如果没有 BMNpcForceReload,管理员可能需要手动选择每个 NPC 并重新应用其模型。
BMNpcForceReload 充当自动安全系统,通过监控配置的 NPC、检测加载事件、重试失败的操作以及在必要时恢复模型来发挥作用。
它特别适用于:
- 生存服务器;
- RPG 服务器;
- 大厅服务器;
- 冒险服务器;
- 使用大量自定义 NPC 的网络;
- 频繁重载 Citizens 或 BetterModel 的服务器;
- 使用自定义 BetterModel 角色的服务器。
兼容性
BMNpcForceReload 专为以下环境设计:
- Paper 1.21.x
- Paper 26.x
- 兼容 Folia 的版本
- Citizens
- BetterModel
注意事项
- BMNpcForceReload 不会替代 Citizens。
- BMNpcForceReload 不会替代 BetterModel。
/bmnpc sync 不会覆盖现有条目。
- 使用
/bmnpc sync overwrite 来更新现有条目。
- 在同步过程中,没有检测到 BetterModel 配置的 NPC 将被忽略。
- 自动更新下载默认处于禁用状态。
- 下载的更新将在下一次服务器重启后应用。
- 可以使用
stats: false 禁用统计信息。
BMNpcForceReload
BMNpcForceReload is a complete model management and automatic repair plugin for Paper and Folia servers using Citizens and BetterModel.
Citizens NPCs can sometimes lose their BetterModel appearance after a server restart, plugin reload, world load, chunk load, or simply over time.
BMNpcForceReload automatically detects these NPCs and reapplies their configured models, keeping them correctly displayed without requiring administrators to repair them manually.
Features
- Automatically reapplies BetterModel models to Citizens NPCs
- Automatic repair when the server starts
- Automatic repair after Citizens or BetterModel reloads
- Automatic repair when a world or NPC chunk is loaded
- Intelligent chunk monitoring with cooldown protection
- Automatic retries when a model cannot be applied immediately
- Reload queue preventing duplicate or overlapping operations
- BetterModel API detection with command fallback
- Automatic synchronization of models already configured in Citizens
- Model detection from Citizens traits and
saves.yml
- Administration GUI
- Complete NPC management commands
- SQLite history and state storage
- PlaceholderAPI support
- Public Java API for other plugins
- Custom Bukkit events
- Secure Modrinth update checker and downloader
- SHA-512 and SHA-1 update verification
- Automatic migration from older configurations
- French and English language files
- Paper and Folia support
- Minecraft 1.21.x and 26.x support
- Configurable usage statistics
Dependencies
Required
Optional
Automatic model repair
BMNpcForceReload checks the configured Citizens NPCs and reapplies their BetterModel model when needed.
Repairs can be triggered:
- when the server starts;
- at a configurable interval;
- after Citizens reloads;
- after BetterModel reloads;
- when an NPC world loads;
- when a chunk containing a configured NPC loads;
- manually using a command;
- from the administration GUI;
- through the public Java API.
The plugin uses a queue to prevent multiple reload operations from running at the same time.
When a model cannot be applied immediately, BMNpcForceReload can automatically retry after a configurable delay.
Citizens synchronization
BMNpcForceReload can automatically import models that are already configured on Citizens NPCs.
/bmnpc sync
This command scans Citizens and imports detected BetterModel models without replacing existing BMNpcForceReload entries.
To update entries that are already present, use:
/bmnpc sync overwrite
The synchronization system can detect models from:
- loaded Citizens traits;
- Citizens NPC metadata;
- persistent Citizens data;
plugins/Citizens/saves.yml;
- BetterModel-related model fields;
- BetterModel blueprint fields.
After synchronization, imported NPCs are immediately added to the repair queue.
Administration GUI
Open the administration menu with:
/bmnpc gui
The GUI allows administrators to:
- view all configured NPCs;
- see the Citizens NPC ID;
- see the configured BetterModel model;
- check whether an NPC is enabled;
- check the latest repair status;
- reload a specific NPC;
- enable or disable an NPC;
- repair all configured NPCs;
- reload the plugin configuration.
Commands
/bmnpc gui
Opens the administration GUI.
/bmnpc reload
Reloads the plugin configuration.
/bmnpc all
Reloads all configured NPC models.
/bmnpc npc <id>
Reloads a specific Citizens NPC.
/bmnpc sync
Imports models already configured in Citizens.
/bmnpc sync overwrite
Imports Citizens models and updates existing entries.
/bmnpc add <id> <model> [name]
Adds a new NPC to the plugin configuration.
/bmnpc remove <id>
Removes an NPC from the plugin configuration.
/bmnpc setmodel <id> <model>
Changes the configured model of an NPC.
/bmnpc enable <id>
Enables automatic repairs for an NPC.
/bmnpc disable <id>
Disables automatic repairs for an NPC.
/bmnpc status
Displays the general plugin status.
/bmnpc list
Displays all configured NPCs.
/bmnpc inspect <id>
Displays detailed information about an NPC.
/bmnpc history <id>
Displays the reload history of an NPC.
/bmnpc validate
Validates the plugin configuration and configured NPCs.
/bmnpc update
Checks Modrinth for a compatible update.
/bmnpc update download
Downloads the latest compatible update.
Permissions
bmnpcforcereload.admin
Grants access to every BMNpcForceReload command.
bmnpcforcereload.reload.all
bmnpcforcereload.reload.single
bmnpcforcereload.gui
bmnpcforcereload.sync
bmnpcforcereload.manage
bmnpcforcereload.status
bmnpcforcereload.list
bmnpcforcereload.inspect
bmnpcforcereload.history
bmnpcforcereload.validate
bmnpcforcereload.update
bmnpcforcereload.config.reload
PlaceholderAPI
When PlaceholderAPI is installed, BMNpcForceReload automatically registers its internal expansion.
Available placeholders:
%bmnpc_total%
%bmnpc_queue%
%bmnpc_running%
%bmnpc_status_<id>%
%bmnpc_model_<id>%
%bmnpc_failures_<id>%
Examples:
%bmnpc_status_50%
%bmnpc_model_50%
%bmnpc_failures_50%
SQLite storage
BMNpcForceReload stores NPC states and repair history inside:
plugins/BMNpcForceReload/data.db
Stored information includes:
- last repair attempt;
- last successful repair;
- latest error;
- total successful repairs;
- total failed repairs;
- repair trigger;
- BetterModel adapter used;
- complete reload history.
Public Java API
Other plugins can interact with BMNpcForceReload through its public API.
BMNpcAPI.reloadNpc(50);
BMNpcAPI.reloadAll();
BMNpcAPI.getNpcStatus(50);
Custom events
BMNpcForceReload provides custom Bukkit events:
BMNpcReloadStartEvent
BMNpcReloadSuccessEvent
BMNpcReloadFailureEvent
These events allow other plugins to react when an NPC repair starts, succeeds, or fails.
Secure Modrinth updates
BMNpcForceReload includes a complete update system connected to the official Modrinth project:
The updater can:
- detect the latest plugin version;
- select a version compatible with the current Minecraft version;
- support Paper and Folia loaders;
- filter stable, beta, and alpha releases;
- download updates automatically;
- verify downloaded files using SHA-512;
- use SHA-1 as a fallback;
- safely install the update after the next restart.
Example:
updates:
enabled: true
auto-download: false
channel: stable
check-interval-hours: 12
initial-delay-seconds: 30
verify-hash: true
Available channels:
stable
beta
alpha
Downloaded updates are placed inside the server update directory and installed after the next restart.
Statistics
BMNpcForceReload includes configurable usage statistics.
Statistics are enabled by default:
stats: true
They can be disabled at any time:
stats: false
The statistics system sends basic technical information such as:
- plugin name and version;
- Minecraft version;
- server software;
- server port;
- online player count;
- maximum player count;
- anonymous installation identifier.
No API key is required.
Languages
BMNpcForceReload includes:
French
English
Select the language in config.yml:
language: en
For French:
language: fr
Configuration migration
Older BMNpcForceReload configurations are automatically migrated to the latest format.
Before modifying an old configuration, the plugin creates a backup such as:
config-v1-backup.yml
config-v2-backup.yml
This allows existing installations to update without manually recreating every NPC entry.
Configuration example
language: en
# Enables anonymous plugin and server usage statistics.
stats: true
settings:
enabled: true
startup-delay-seconds: 15
interval-seconds: 7200
delay-between-npcs-ticks: 10
debug: false
bettermodel:
# Available modes: auto, api, command
mode: auto
# Uses command execution if the BetterModel API is unavailable.
fallback-to-command: true
command-template: "npc select %npc_id% && npc model %model%"
queue:
prevent-overlapping: true
merge-duplicate-requests: true
chunk-monitor:
enabled: true
delay-ticks: 20
cooldown-seconds: 10
only-configured-npc-chunks: true
require-spawned-npc: true
updates:
enabled: true
auto-download: false
channel: stable
check-interval-hours: 12
initial-delay-seconds: 30
verify-hash: true
npcs:
navigator:
npc-id: 50
model: "adventure_npc"
enabled: true
reload:
on-startup: true
on-world-load: true
on-chunk-load: true
retry:
attempts: 3
delay-ticks: 40
evil-cube:
npc-id: 43
model: "cubee_evil"
enabled: true
reload:
on-startup: true
on-world-load: true
on-chunk-load: true
retry:
attempts: 3
delay-ticks: 40
seller:
npc-id: 25
model: "seller"
enabled: true
reload:
on-startup: true
on-world-load: true
on-chunk-load: true
retry:
attempts: 3
delay-ticks: 40
Why use BMNpcForceReload?
BetterModel models attached to Citizens NPCs may occasionally disappear or fail to load correctly.
Without BMNpcForceReload, administrators may need to manually select each NPC and reapply its model.
BMNpcForceReload acts as an automatic safety system by monitoring configured NPCs, detecting load events, retrying failed operations, and restoring models whenever necessary.
It is especially useful for:
- survival servers;
- RPG servers;
- lobby servers;
- adventure servers;
- networks using many custom NPCs;
- servers frequently reloading Citizens or BetterModel;
- servers using custom BetterModel characters.
Compatibility
BMNpcForceReload is designed for:
- Paper 1.21.x
- Paper 26.x
- Folia-compatible versions
- Citizens
- BetterModel
Notes
- BMNpcForceReload does not replace Citizens.
- BMNpcForceReload does not replace BetterModel.
/bmnpc sync does not overwrite existing entries.
- Use
/bmnpc sync overwrite to update existing entries.
- NPCs without a detectable BetterModel configuration are ignored during synchronization.
- Automatic update downloads are disabled by default.
- Downloaded updates are applied after the next server restart.
- Statistics can be disabled using
stats: false.
评论 0
登录后参与评分
还没有评论,来抢沙发吧