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

• Citizens
• BetterModel

Optional

• PlaceholderAPI

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:

https://modrinth.com/plugin/bmnpcforcereload

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.