FancyNpcs – Minecraft Java Edition 1.19.4–1.21.x

Creating interactive non-player characters (NPCs) on Minecraft servers has traditionally come with significant hardware costs. Legacy solutions register NPCs as full-fledged server entities (Entity), forcing the core to process their artificial intelligence, physical collisions, pathfinding, and chunk loading. This leads to a critical drop in the TPS (Ticks Per Second) metric as the number of characters grows. The FancyNpcs plugin offers an alternative, packet-based method of rendering virtual characters, allowing hundreds of interactive figures to be maintained without any impact on server thread performance.

Packet architecture and Folia compatibility

The main technical feature of FancyNpcs is that the characters it creates exist solely in the plugin's memory and on the side of connected clients. The server does not add them to the world database and does not process them in the general entity update cycle.

When a player approaches the specified coordinates, the plugin intercepts the network traffic and sends the client ClientboundAddPlayerPacket packets (for human models) or ClientboundAddEntityPacket (for other creatures). Subsequent behavior, equipment, and display status are updated using ClientboundSetEntityDataPacket (metadata) and ClientboundSetEquipmentPacket (equipment) packets. For the server, these characters do not exist — they are "virtual projections" for end users.

This approach makes FancyNpcs an ideal choice for multithreaded servers based on Folia. Since Folia divides the world into separate regions, each running in its own thread, traditional NPC plugins often cause deadlocks and critical errors due to attempts at interaction between threads of different regions. FancyNpcs processes data asynchronously and sends packets to players directly, completely avoiding conflicts with the Folia task scheduler.

Appearance customization options

The plugin supports a wide range of entity types and visual effects. Players can create NPCs in the form of any vanilla mobs (Player, Cow, Zombie, Skeleton, Villager, Pig, etc.) and fine-tune their appearance.

Skin management (for human models)

For characters of the player type, several texture loading sources are available:

• @mirror: the NPC's skin dynamically copies the skin of the player currently looking at it.

• Name or UUID of a licensed account: the plugin automatically sends a request to Mojang's session servers to load the corresponding texture.

• Direct link to a web resource (URL): the ability to load any third-party .png file from a web server.

• Local files: images placed in advance in the /plugins/FancyNpcs/skins/ folder.

• The --slim: flag activates the use of the slim arm model (Alex style) for skins loaded via links.

Visual effects and attributes

• Glowing: adds a colored outline around the character. The color is tied to vanilla team colors.

• Equipment: characters can be given any items in their left or right hand, as well as wear a helmet, chestplate, leggings, and boots.

• Poses: specific display states are supported, such as sitting, lying down (imitating sleeping in a bed), swimming, and crawling.

• Scale: in newer versions of the plugin, support for entity scaling (changing the physical size of the model) has been implemented.

Command system and syntax

Characters are managed exclusively using commands in the in-game chat or the server console. The table below contains a description of the basic syntax:

For global administration of the plugin, platform commands are used:

• /fancynpcs reload — reloads the system configurations.

• /fancynpcs save — forcibly writes the current state of all NPCs to disk in the database file.

Interactive actions system (Actions)

FancyNpcs contains a built-in scripting action mechanism that is triggered when a player interacts with a character. Actions can be configured for different click types (LEFT_CLICK, RIGHT_CLICK, ANY_CLICK).

The plugin offers the following types of actions to execute:

• message: sending a message to the player. Supports MiniMessage (Hex colors) and PlaceholdersAPI variables.

• player_command: executing a command on behalf of the player.

• player_command_as_op: executing a command on behalf of the player with temporary granting of operator privileges (to activate commands that an ordinary player cannot use).

• console_command: executing a command by the server console. The {player} variable is automatically replaced with the player's name.

• send_to_server: instantly transferring the player to another server on the BungeeCord or Velocity network.

• wait: creates a pause between actions (delay in server ticks).

• block_until_done: prevents repeated clicks on the NPC until the current action sequence is complete.

• execute_random_action: randomly selects one of the following actions in the list.

Example of creating a complex interactive scenario for an NPC named Bob:

1. Adding a welcome message:
   /npc action Bob RIGHT_CLICK add message <yellow>Welcome to our server, %player_name%!</yellow>

2. Adding a pause of 40 ticks (2 seconds):
   /npc action Bob RIGHT_CLICK add wait 40

3. Teleporting the player to spawn via the console:
   /npc action Bob RIGHT_CLICK add console_command teleport {player} 0 100 0

Thanks to the ability to add several sequential steps and adjust the queue using add_before, add_after and move_up/move_down, administrators can build full-fledged dialogue trees or complex mechanics for transitions between lobby servers without installing additional plugins such as Denizen or MyCommand.

Configuration file structure

All data is stored in the plugins/FancyNpcs/ directory. The plugin's operation is based on two files:

1. config.yml

This file defines the global behavior of the plugin and contains the following settings:

• turn_to_player_distance (default 5): the radius in blocks within which the character turns its head toward players. Lowering this parameter optimizes the transmission of network packets in loaded areas.

• visibility_distance (default 20): the distance in blocks at which NPC spawn packets are sent to the client. Reducing it helps hide characters behind walls or render fog to save players' FPS.

• enable_autosave: automatic periodic writing of changes to disk.

2. npcs.yml

In this file, the plugin stores the database of created NPCs. Each character is described by a separate data block:

YAML

Conclusion

The FancyNpcs plugin is a modern and high-performance solution for creating decorative and interactive characters on Minecraft Java Edition servers. It eliminates the main problem of older tools — the consumption of server CPU time on servicing entities.

The plugin's main limitation is the complete absence of artificial intelligence. Since the characters are virtual client-side projections, they cannot move around the world on their own, interact with blocks, or attack other mobs.

Compared to the classic Citizens plugin, which supports complex movement mechanics (waypoint navigation) and integration with combat systems (the Sentinel mod), FancyNpcs falls short in artificial intelligence flexibility. However, Citizens creates a colossal load on the server's main thread and is practically unsuitable for use on Folia. FancyNpcs offers an ideal alternative for lobby servers, Velocity hubs, and large SMP projects, where characters are required only to have a static presence, a good appearance, and fast command execution on click.