Custom Dynamic NPC

Minecraft 1.20.1 · Fabric · Server-Authoritative

A complete system for dynamic NPCs and customizable hostile mobs with Blockbench models, procedural animations, a WYSIWYG visual editor, and spawn zone management — all fully controlled from the server.

✨ Key Features

🧑‍🤝‍🧑 Dynamic NPC System

Server-authoritative: all logic runs on the server; the client only renders.
States: IDLE, TALKING, WALKING, ANIMATING, WORKING, SLEEPING, CUSTOM.
Configurable AI brain (NpcBrain): automatic state transitions, timers, wandering.
Custom skins: assign any skin to each NPC.
Blockbench models (.bbmodel): upload custom 3D models directly in-game.
Configurable hitbox: adjust collision width and height per NPC.
Model rotation: rotate the NPC model to any angle.
Invulnerable by default: NPCs cannot be damaged (configurable).
Path system: define waypoints so NPCs can walk in loops.
Full persistence: all NPCs are automatically saved and survive restarts.

⚔️ Zone-Based Hostile Mob System

Spawn zones (MobZone): define rectangular areas where hostile mobs spawn automatically.
Configurable variants: each zone can have multiple mob variants with:
- 📛 Custom name
- ⚔️ Damage, ⚡ Speed, ❤️ Health, 🎯 Tracking range
- 🧱 Hitbox (width × height)
- 🎨 Skin and Model (PlayerModel, Blockbench, or vanilla mob)
- 🚶 Walk animation: none, bob, sway, bounce
- 👊 Attack animation: none, lean, pulse, shake
Configurable drops: define death loot with min/max amounts and probability.
Controlled spawning: spawn delay, max alive mobs, enable/disable per zone.
Multi-dimension support: each zone remembers its dimension.
Triple rendering system:
- 🟣 Blockbench models with imported textures and procedural animations.
- 🟢 Vanilla mob proxy (e.g., minecraft:turtle, minecraft:zombie): renders native appearance and animations.
- 🔵 PlayerModel fallback.

🎬 Procedural Animations (Blockbench Models)

Imported Blockbench models support automatic animations without separate animation files:

Type	Name	Effect
🚶 Walk	`bob`	Smooth vertical bounce while walking
🚶 Walk	`sway`	Side-to-side sway while walking
🚶 Walk	`bounce`	Pulsing squash & stretch
👊 Attack	`lean`	Forward lean on attack
👊 Attack	`pulse`	Brief scale pulse on attack
👊 Attack	`shake`	Rapid vibration on attack

Animations trigger based on real entity movement and swing/damage state.

🖥️ Full Visual GUIs

📋 Staff Panel (`/dnpc panel`)

Main control panel for operators:

NPC list with search and selection.
3D preview of the selected NPC with model and skin.
Model gallery with scrollable cards and 3D previews.
.bbmodel upload directly from local files.
Visual hitbox controls with sliders.
Inline editing of name, skin, model, state, wandering.

🎨 WYSIWYG GUI Editor (`GuiNodeEditorScreen`)

Drag & drop visual editor to create NPC interfaces:

Resizable grid canvas.
Draggable nodes: buttons, panels, labels, separators, images, items.
Properties panel with tabs: Preset, Style, Actions, Advanced.
Available actions: run_command, close_gui, open_url, send_message, play_sound, change_state, open_preset, give_item, open_dialogue, teleport_player, show_title, npc_anim, set_score, open_inventory, consume_item, check_inventory.
Conditions: has_permission, npc_state, has_item, score_gte.
Savable presets: shop, dialogue, custom JSON.

🗺️ Zone Panel (`/dnpc zone panel`)

Visual panel to manage hostile spawn zones:

Zone list with ON/OFF state, size, variants, drops, active mobs.
Quick creation with auto-filled coordinates.
Three tabs per zone:
- ⚙️ Settings: editable bounds (6 coordinates), spawn delay, max mobs, state.
- ⚔️ Variants: cards with stats, model, animations. Button opens Mob Picker.
- 💎 Drops: cards with item, amount, probability. Button opens Item Picker.
Visualization toggle (◉ Vis): enables/disables in-world zone boundary rendering.

🦎 Mob Picker (`GuiMobPickerScreen`)

Visual browser for selecting mobs/models when creating variants:

Source list by mod namespace (minecraft, modded, ⚡ models).
Visual grid with spawn eggs and custom model icons.
Search by name and ID.
Stat fields: name, damage, speed, health, tracking, hitbox W/H.
Animation selector: cycle walk/attack animations with buttons.

🎒 Item Picker (`GuiItemPickerScreen`)

Visual browser to add drops:

Item grid with real rendered icons.
Filter by mod namespace.
Fields: minimum amount, maximum amount, probability.

🌐 Zone Boundary Rendering (`ZoneBoundaryRenderer`)

Wireframe + translucent fill for each zone, visible in-world.
Unique colors per zone (red, blue, green, yellow, purple, orange, cyan).
Selected zone is highlighted with a bright pulse + floating label showing name and size.
Toggle from the Zone Panel GUI.

📡 Networking & Performance

GZIP-compressed packets to minimize network usage.
Duplex channels: 10+ dedicated S2C and C2S channels.
Model manifest sync: on join, the server sends a model manifest; the client downloads only what it needs.
Client model cache with dynamic textures.
Proxy entity cache for vanilla rendering (reuses dummy entities).

📜 Commands

All commands use /dnpc (requires OP level 2):

NPCs

Command	Description
`/dnpc panel`	Opens the staff visual panel
`/dnpc spawn <name> [pos]`	Creates an NPC
`/dnpc remove <name\|uuid\|nearest>`	Removes an NPC
`/dnpc list`	Lists all NPCs
`/dnpc tp <id> <pos>`	Teleports an NPC
`/dnpc state <id> <state>`	Changes the state
`/dnpc skin <id> <skin>`	Changes the skin
`/dnpc model <id> <modelId>`	Assigns a Blockbench model
`/dnpc anim <id> <animation>`	Plays an animation
`/dnpc wander <id> <true\|false>`	Enables/disables wandering
`/dnpc rename <id> <new_name>`	Renames an NPC
`/dnpc path add/clear/loop <id>`	Path system
`/dnpc gui open <id> [player]`	Opens the NPC GUI
`/dnpc gui set <id> shop\|dialogue\|json`	Assigns a GUI preset
`/dnpc models list`	Lists Blockbench models
`/dnpc models reload`	Reloads models from disk
`/dnpc reload`	Reloads NPCs
`/dnpc save`	Saves everything

Hostile Zones

Command	Description
`/dnpc zone panel`	Opens the zone visual panel
`/dnpc zone create <id> <pos1> <pos2>`	Creates a zone
`/dnpc zone remove <id>`	Removes a zone and kills its mobs
`/dnpc zone list`	Lists all zones
`/dnpc zone info <id>`	Zone details
`/dnpc zone enable/disable <id>`	Enables/disables
`/dnpc zone set <id> delay/maxmobs <value>`	Configures spawning
`/dnpc zone variant add/remove/list/set`	Manages variants
`/dnpc zone drop add/remove/list`	Manages drops
`/dnpc zone save/reload`	Saves/reloads zones

📦 Installation

Install Fabric Loader ≥ 0.16.9 and Fabric API ≥ 0.92.2+1.20.1.
Place customdynamicnpc-1.0.5.jar into the server and client mods/ folder.
Restart Minecraft.
Use /dnpc panel to start creating NPCs or /dnpc zone panel to manage hostile zones.

🔧 Requirements

Requirement	Version
Minecraft	1.20.1
Fabric Loader	≥ 0.16.9
Fabric API	≥ 0.92.2+1.20.1
Java	JDK 17+