✅ What is ModeledNPCs?
ModeledNPCs is a full NPC framework that lets you create real, persistent, interactive NPCs with:

• ModelEngine models + animation control
• MythicMobs NPC support (optional workflow)
• Quest dialogs with choices, commands, escort triggers
• Trader system (simple trades OR full offers GUI with stock/limits)
• Effects system (looping particles + on-interact particles/potions/sounds)
• NPC AI routing (patrol + multi-route + escort routes)
• Powerful in-game management GUI (rename, commands, animations, effects, routes, delete safely)

This plugin is designed to be production-ready for serious servers.

⚡ Core Highlights
✅ Supports ModelEngine NPCs and/or MythicMobs NPCs
✅ Full animation control (looped / interact / escort)
✅ NPC AI Routes (multi-route system stored in SQLite)
✅ Escort Mode connected to dialog options
✅ Trader system with Offers GUI, stock, restock, purchase limits
✅ Effects system (loop + on-interact) + click triggers configuration
✅ Commands on interact with player: / console: / sudo: / bungee:
✅ NPC Hide (permission-based visibility)
✅ Reload tools (NPCs, names, effects, animations, traders)
✅ Debug tools (orphan NPCs, chunk issues, entity consistency)
✅ Developer friendly API + clean storage + predictable lifecycle
✅ SqLite Storage (NPCs, names, effects, animations, traders)

Create NPCs Instantly
Create NPCs in one command:

NPCs are saved with:

• ID
• type (modelengine / mythicmobs)
• internalUUID (prevents duplication)
• entityUUID (live entity binding)
• location (world/x/y/z/yaw/pitch)
• commands
• name + hologram height

Command System (Interactions)
Bind command chains to NPCs, executed on interaction:

Executors

• player: runs as the player
• console: runs as console
• sudo: runs as player with temporary OP (safe reset)
• bungee: sends player to another BungeeCord server (plugin messaging)

Examples:
Effects System (Particles, Potions, Sounds)
Bring your NPCs to life with ambient + interactive effects.

✅ Looping particles
✅ On-interact particle bursts
✅ On-interact potion effects (applied to the clicking player)
✅ On-interact sounds

Commands:
Short “colon form” is also supported:
Click trigger config (left/right click support):
NPC AI Routes (Patrol • Multi-Route • Escort)
ModeledNPCs includes a powerful NPC routing system designed for performance and stability.
All routes are stored in SQLite, making them safe for large RPG worlds and long-running servers.
Multiple Routes per NPC
Each NPC can own multiple independent routes.
You can freely switch or trigger them via dialogs, commands, or scripts.
Examples:

• default
• church
• mayor
• any custom routeId

This allows a single NPC to behave differently depending on quests, time, or progression.
Patrol Mode (Ping-Pong)

• NPC walks between route points
• Automatically returns to the first point
• Smooth tick-based movement (no teleport jitter)
• Ideal for guards, villagers, sentries

Escort Mode (Dialog Driven)
Escort routes are fully integrated with the dialog system.

• NPC follows the route once
• Used as a quest escort objective
• Optional message when destination is reached
• NPC automatically returns to its original location
• Dialog bindings are safely reset after escort

Perfect for:

• Quest companions
• Guided tours
• Story-driven NPC movement

️ Dialog System + Quest Integration
ModeledNPCs works perfectly with quest dialogs:

• chat-based branching dialogs
• per-player sessions
• numbered choice selection
• built-in cancel/help
• command execution per option
• special action: escort start

Dialog flow supports:
✅ START
✅ CANCEL
✅ COMMAND
✅ DIALOG (continue)

Example:
Trader System (Legacy or Full Offers GUI)
ModeledNPCs contains a full Trader framework:

✅ Legacy simple trade mode (one-click)
✅ Offers GUI mode (SmartInvs paginated menu)
✅ Stock + timed restock
✅ Per-player limits with timed reset
✅ Costs: Vault money, XP levels, items
✅ Rewards: items, money, commands
✅ Confirmation GUI optional
✅ PlaceholderAPI support
✅ Custom ItemBuilder (model data, enchants, attributes, PDC, unbreakable, lore)

Trader config: trader.yml
Runtime persistence: trader_runtime.yml

(Your giant example config fits here perfectly — keep it in your description below this section.)

ModelEngine Animations (Loop / Interact / Escort)
This is where ModeledNPCs becomes insane:

✅ You can run a full NPC system using ModelEngine only — no MythicMobs needed.
✅ The plugin automatically collects animations and lets you assign them live.

Animation modes:

• Looped animation (idle)
• Interact animation (played when clicking NPC)
• Escort walk animation (played on escort clone while walking routes)

Commands + GUI support:

• choose animations from the model
• set interact cooldown
• save persistently
• clear each animation independently

Manage Menu GUI (In-Game Editor)
ModeledNPCs includes a full management GUI:

Manager Menu lets you:
✅ Open Effects Editor GUI
✅ Open ModelEngine Animation GUI
✅ Rename NPC (chat input + optional hologram height)
✅ Bind interact commands (player/console/bungee)
✅ Nametag Manager (hide/show/reset)
✅ Delete NPC safely (clears AI routes + stops effects + removes entity + deletes data)
✅ Reset AI route
✅ Configure escort speed per NPC (saved to SQLite + NPCData)

This means admins can manage NPCs without touching files.

NPC Hide (Permission Visibility)
Create VIP-only or quest-only NPCs:

Players without permission:

• will not see the NPC
• no restart required
• dynamic updates

Reload & Debug Tools
Reload without restarting your server:

Debug checks:

• orphan NPC entities
• chunk loading issues
• entityUUID mismatch
• internalUUID identity protection

Config Files Overview
data.yml — stores NPCs (id/type/uuid/location/commands)
namedata.yml — custom NPC names + hologram height
lookdata.yml — AutoLook state per NPC
npceffects.yml — effects per NPC
meganimation.yml — animation mapping per NPC
trader.yml — trader logic (offers, stock, limits, etc.)
trader_runtime.yml — runtime stock + per-player counters
SQLite — route storage + escort speed storage (performance)

Full Command List
NPC Core
NPC Interaction & Behavior
Commands on Interaction
Effects
AI Routes
GUI & Management
Reload & Debug

Dependencies
Required

• ModelEngine
• MythicMobs
• Vault (economy)
• PlaceholderAPI

Optional (recommended)

• BetonQuest / Quests / QuestDialogs integrations

Documentation & Support
Docs (GitBook): https://docs.oreo-studio.shop/modellednpcs
Discord Support: https://discord.gg/xYeuK9dhfy

Developer API (JavaDocs): Developer API | ModelledNpcs

(If you give me the exact JavaDocs URL you want, I’ll drop it cleanly in the right place.)