Overview & Getting Started

ModelEngineNPC brings your server to life by combining ModelEngine 4 models and standard Minecraft player NPCs with an advanced management system.

Requirements

• Java 21 or newer. The plugin is compiled for Java 21.
• Paper 1.21.11, 26.1.2, or 26.2 (or compatible forks). Experimental targets are not officially supported.

Dependencies

Required

Provides rendering capabilities for custom 3D model entities. model-type NPCs require it.

Intercepts and handles packets directly for the normal-type NPCs. This plugin must be installed alongside ModelEngineNPC; it is not shaded inside our JAR.

Optional

Provides text holograms above NPCs. If absent, the plugin will run normally but hologram features will be disabled.

Compatibility

Installation

1. Stop your Minecraft server completely. Do not use /reload.
2. Place the ModelEngineNPC-<version>.jar into your server's plugins/ directory.
3. Start your server.
4. Verify the plugin has loaded successfully.

Verify Installation

Run the /plugins command or check your console log.

[ModelEngineNPC] ModelEngineNPC enabled!

If you see errors, refer to the Troubleshooting guide.

Quick Start

Creating a Model NPC

To spawn a ModelEngine NPC, you need the ModelEngine ID of an existing model loaded on your server.

/menpc create guard model my_guard_model

This spawns a new NPC named guard at your current location using my_guard_model.

Creating a Normal NPC

To spawn a normal player NPC (a Steve), you can provide a player name or a skin URL.

/menpc create shopkeeper normal Notch

This spawns a normal NPC named shopkeeper with the skin of the player Notch.

Next Steps

You should see the NPC appear exactly where you were standing. If it fails, the console or chat will display an error message. Use /menpc list to verify it was registered.

Updating to v2.0.1

1. Stop your server. Do not use Plugman or /reload.
2. Take a backup of the plugins/ModelEngineNPC directory.
3. Replace the old JAR with the new ModelEngineNPC-v2.0.1.jar.
4. Ensure your dependencies (PacketEvents, ModelEngine) meet the new version requirements.
5. Start the server.

No manual config or NPC storage migration is required from v2.0.0 or v1.3.2.

Ensure NPCs spawn correctly and skins are applied without console errors. Check interaction commands to verify they execute normally.

If you encounter issues, stop the server, restore the ModelEngineNPC folder backup, and downgrade the JAR back to the previous version.