PerfectNPC

Custom NPCs with multi-page dialogues, quests, shops, equipment, face-me rotation, and a full in-game admin UI. Bring your server world to life.

Buy on BuiltByBit

Installation

1. Download PerfectNPC-2.5.jar
2. Place it in your server's UserData/Mods/ folder
3. Start the server
4. Use /pnpc to open the admin panel

NPC Types

All NPCs support:

• Custom model with rescale (Model.createScaledModel)
• Nameplate display (single line)
• Frozen / idle animations
• Chunk-based spawning (auto-spawn when chunks load)
• Equipment (helmet, chest, leggings, gloves, main hand, off hand)
• JSON persistence

Dialogue System

NPCs can run multi-page dialogues with branching choices, conditions, and command execution.

• Up to 6 answer choices per page
• Multiline content: press Enter in the editor to add a new line
• Typewriter animation: text appears character by character at a configurable speed
• Per-page conditions to gate visibility
• Per-answer commands (server console or player permission bypass)
• Navigation buttons (Previous, Next, Custom)
• Variable substitution: {player}, {npc}, custom variables

Quest System

Create quests with objectives and rewards. Players interact with Quest Giver NPCs to accept, track, and complete quests.

Objective types tracked live:

• KILL_ENTITY: kill N entities matching a role name
• COLLECT_ITEM: pick up N items by item ID
• BREAK_BLOCK: break N blocks of a given type
• PLACE_BLOCK: place N blocks of a given type

• Item and XP rewards on completion
• Per-player progress tracked, persisted across restarts
• Quest log UI for players
• Daily / weekly variables and tags for soft state

Shops

Shopkeeper NPCs open a trade UI where players can buy and sell items.

• Configurable item list, prices, and stock
• Buy and sell in the same UI
• Category tabs for large shops
• Daily reset option (per-player stock)

Equipment

Dress your NPCs with armor and weapons via the Equipment tab in the admin UI.

• Helmet, Chest, Leggings, Gloves
• Main hand and off hand
• Visible in-world after spawn

Face-Me Rotation

NPCs can rotate to face the nearest player. Due to Hytale limitations, this works via despawn / respawn:

• Calculates yaw: atan2(dx, dz) + PI (in radians)
• Despawns and respawns the NPC entity with the new rotation
• Re-applies interactions after 500ms delay

Commands

Changelog

v2.5 - Quality of Life update

• Multiline dialog content (Enter creates a new line in the editor)
• All four quest objective types now fully tracked: KILL, COLLECT, BREAK, PLACE (previously only KILL was wired up)
• Typewriter animation now actually renders character by character at the configured speed (was UI-only before)
• Fixed client crash when navigating between admin tabs after saving

v2.4

• V2 admin UI: tab-based layout (Info, Dialog, Shop, Quest, Equip, Advanced)
• Equipment section to dress NPCs with armor and weapons
• Quest item collection check tick

v2.1

• Multi-page dialogues with up to 6 answers per page
• Quest system with objectives and rewards
• Shop with category tabs

FAQ

NPC nameplate doesn't support line breaks

This is a Hytale limitation. All nameplate text must be on a single line.

NPC doesn't rotate smoothly

Face-me uses despawn / respawn which causes a brief flicker. This is the only reliable method in the current Hytale API.

Player skin NPCs (humanoid characters)

Not currently supported. NPCs use Hytale's built-in entity roles. Custom player-like NPCs would require Hytale to expose a player-model API, which is not yet available.

Daily / weekly quests, quest tree, multi-reward choice

Planned for the v3.0 quest rework. Available now: variables and tags can be used to build manual daily-reset logic via dialogue conditions.