👥 Retinue — Manage and Deploy Your Dynamic NPC Follower Crews

⚠️ CRITICAL WARNING: EARLY PREVIEW BUILD

This is an early preview build of Retinue. It is currently known to cause world crashes and data corruption under certain conditions. It is strongly recommended that you only use this plugin on an isolated testing or development server. Do NOT run this on a live production server, and ensure you have frequent, automated world backups.

Retinue is a powerful, data-driven NPC follower, roster, and task management framework designed specifically for Hytale servers. It allows server administrators to define completely custom NPC companions, and gives players the power to recruit, roster, and deploy them on immersive tasks.

While the framework is engineered to support a wide variety of future helper systems, progressive structure building is the first fully implemented module—allowing your followers to physically construct prefabs block-by-block using materials supplied by the player.

🌟 Key Features

👥 Fully Dynamic NPC Roster & Recruitment

Manage a follower lineup that is completely customized by your server. Retinue uses a dynamic, data-driven catalog with absolutely zero hardcoded NPCs.

Custom NPCs: Recruit and roster unique companions loaded directly from your server's database (npcs.json and prefabs.csv).
Unlockable Slots: Players start with a baseline slot count and can purchase or unlock additional roster slots using your server's in-game currency.
Custom Skins & Portraits: The plugin automatically captures, caches, and pre-renders high-quality 2D headshot portraits directly from your custom NPC skins for a premium UI feel.

🧱 Immersive "Drip-Feed" Building (Initial Module)

Instead of instantly pasting massive structures and ruining the survival immersion, players can assign building tasks to their active retinue:

Progressive Construction: Watch your retinue physically construct prefabs block-by-block in real-time.
Server-Friendly Performance: Computations are highly optimized and drip-fed across ticks, preventing server lag or crashes during massive base builds.
Material Management: Access your follower's persistent builder pouch/inventory to supply the required blocks for their construction queue.
Task Persistence: Server restart? No problem. Building tasks survive restarts and resume exactly where they left off.

📐 Real-Time 3D Prefab Previews

Orbital Freecam View: Toggle a specialized camera mode to perfectly align, rotate, elevate, or depth-adjust structures before confirming the build order.
Adventure-Safe (FAKE_BLOCKS): Utilizes an advanced rendering technique that lets players preview blueprints safely in Adventure mode without placing actual block entities or risking duplication exploits.

🎒 The Retinue Tool

Hand your players the custom Retinue Tool (a book item). Right-clicking or left-clicking instantly brings up the custom Retinue Hub UI—no magic casting times, no awkward animations, and absolutely no command typing required.

🛠️ Commands & Permissions

Retinue features a clean, lightweight permission structure that works seamlessly alongside any standard Hytale permissions plugin (like LuckPerms).

Command	Alias	Permission	Description
`/retinue`	`/ret`	`retinue.admin`	Opens the master Admin Catalog to add, delete, or manage prefabs and companions.

💡 Player Access Note: Players do not need any commands! Access is handled entirely via gameplay through the Retinue Tool item, which safely opens the player-facing Hub page.

🚀 Quick Start Guide

Open the Hub: Left or right-click the Retinue Tool to open your custom follower Hub.
Roster a Follower: Recruit a custom companion to your active roster and assign them to an open slot.
Feed the Pouch: Open your follower's pouch and deposit the required building blocks directly into their inventory.
Deploy Blueprints: Unlock prefab blueprint recipes at the workbench, position them flawlessly using the orbital camera view, and assign your retinue to get to work!

🔌 Compatibility & Integration

Retinue is built to feel like a native part of the game. It features out-of-the-box compatibility with:

Ecotale Economy (or your server's custom currency system)
Hytale's native Custom UI page system
Custom server HUDs