NPC Management

NPC Types

ModelEngineNPC supports two NPC types:

• Model NPC uses a ModelEngine model ID and requires ModelEngine.
• Normal NPC uses a player-style entity and skin input. PacketEvents handles packet integration.

Choose model for custom 3D models. Choose normal for a player-style NPC with a player name or skin URL.

Model NPCs

Model NPCs reference models already loaded by ModelEngine. ModelEngine must be installed and the model ID must exist before creation.

/menpc create guard model my_guard_model

Change model with:

/menpc setmodel guard my_other_model

Animations are configured separately. If model does not render, confirm ModelEngine loaded model ID and inspect server logs.

Normal NPCs

Normal NPCs use player-style appearance. Provide player name or supported skin URL when creating or updating skin.

/menpc create shopkeeper normal Notch

/menpc setskin shopkeeper Notch

Skin resolution is asynchronous for remote inputs. A skin can appear after fetch completes and should be cached for later spawn.

Create an NPC

Create a model NPC with a loaded ModelEngine model, or a normal NPC with player-style skin input:

/menpc create guard model my_guard_model
/menpc create shopkeeper normal Notch

Run /menpc list after creation. Expected result: NPC appears at your current location and is registered in storage.

Edit an NPC

Use focused commands to change model, skin, name, visibility, rotation, LookClose, or animation:

/menpc setmodel guard my_other_model
/menpc setname guard Town Guard
/menpc name guard true
/menpc rotate guard 90 0

Verify changes in-world and after a clean restart.

Copy an NPC

Clone an existing definition to your location:

/menpc copy guard guard-copy

Expected result: guard-copy is registered as a separate NPC. Confirm with /menpc list.

Convert an NPC

Change between model and normal types with the type-specific syntax:

/menpc setnpctype shopkeeper model my_guard_model
/menpc setnpctype guard normal

Verify appearance, skin/model state, and interactions before using the converted NPC in production.

Delete an NPC

Remove an NPC by ID:

/menpc remove guard

Run /menpc list and confirm entity removal. Restore a storage backup if an unintended deletion requires recovery.

GUI Editor

Open editor with:

/menpc editor

Use editor controls to inspect NPC settings and apply supported changes. Permission checks still apply. Verify saved changes with /menpc list and by observing NPC after a clean restart.

Lifecycle and Persistence

NPC definitions persist in YAML storage and load during plugin startup. The repository owns persistence; avoid editing files while server is running.

The current configuration exposes an auto-save interval and an option to despawn NPCs when chunks unload. Stop server before backups or manual edits. Restart cleanly after changes, then verify NPC list and spawn state.

Storage Overview

Active NPC definitions reside in plugins/ModelEngineNPC/npcs.yml. See Storage Reference for schema and backup guidance.