BMNpcForceReload

!(https://img.shields.io/bstats/servers/30359?style=for-the-badge&label=Servers) !(https://img.shields.io/bstats/players/30359?style=for-the-badge&label=Players)

# 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

- (https://www.spigotmc.org/resources/placeholderapi. 6245/)

## 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.

```text /bmnpc sync ```

This command scans Citizens and imports detected BetterModel models without replacing existing BMNpcForceReload entries.

To update entries that are already present, use:

```text /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:

```text /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

```text /bmnpc gui ```

Opens the administration GUI.

```text /bmnpc reload ```

Reloads the plugin configuration.

```text /bmnpc all ```

Reloads all configured NPC models.

```text /bmnpc npc ```

Reloads a specific Citizens NPC.

```text /bmnpc sync ```

Imports models already configured in Citizens.

```text /bmnpc sync overwrite ```

Imports Citizens models and updates existing entries.

```text /bmnpc add ```

Adds a new NPC to the plugin configuration.

```text /bmnpc remove ```

Removes an NPC from the plugin configuration.

```text /bmnpc setmodel ```

Changes the configured model of an NPC.

```text /bmnpc enable ```

Enables automatic repairs for an NPC.

```text /bmnpc disable ```

Disables automatic repairs for an NPC.

```text /bmnpc status ```

Displays the general plugin status.

```text /bmnpc list ```

Displays all configured NPCs.

```text /bmnpc inspect ```

Displays detailed information about an NPC.

```text /bmnpc history ```

Displays the reload history of an NPC.

```text /bmnpc validate ```

Validates the plugin configuration and configured NPCs.

```text /bmnpc update ```

Checks Modrinth for a compatible update.

```text /bmnpc update download ```

Downloads the latest compatible update.

## Permissions

```text bmnpcforcereload.admin ```