NPCs Fabric

NPCs Fabric

Put NPCs anywhere on your server: players, villagers, cows, armor stands, anything. They wear what you give them, glow, look at players, and run commands, messages and sounds when someone clicks them. Plus floating holograms for your spawn, shops and rules.

📥 Moving from Paper? Import your FancyNpcs or Citizens NPCs with one command. See how.

Works on Minecraft 1.21 to 1.21.11 and 26.1 to 26.3. There are two jars: pick the one for your version (see Requirements).

⭐ Follow NPCs Fabric to get notified about new updates.

🎮 No client mod. Your players join vanilla.

NPCs Fabric is 100% server-side. It goes in your server's mods/ folder next to Fabric API and that's it: no modpack, no launcher setup, nothing for players to install.

Every NPC and hologram is made only of packets. Nothing is added to your world: NPCs don't tick, don't take up entity slots, can't be pushed, killed, lured or despawned, and never end up in a chunk file. Remove the mod and they're gone without a trace.

🧍 Any Entity, Any Skin

• Any entity type. Players, villagers, cows, foxes, armor stands, minecarts… everything in the game. /npc type <npc> <type> changes it on the spot.
• Skins from anywhere. A player name, a UUID, an image URL, or a PNG file you put in config/npcsfabric/skins/ (both through MineSkin). --slim for Alex-style arms.
• Mirror skins. @mirror shows every player their own skin on the NPC.
• Your skin by default. A new player NPC wears the skin of whoever made it.

A skin from your own PNG file: put knight.png (64x64, or the old 64x32) in config/npcsfabric/skins/, set your free MineSkin key as mineskinApiKey in the config, then:

/npc skin guard file:knight --slim

It's uploaded once and stored with the NPC; the same image is never uploaded twice.

🐱 Every Mob, Every Look

Make the NPC exactly the mob you picture, with /npc attribute <npc> set:

• profession — Librarian, armorer, cleric… any villager job. Works on zombie villagers too.
• villager_type — Desert, snow, jungle, swamp, savanna, taiga, plains.
• variant — Siamese cats, snowy wolves, cold frogs, snow foxes, brown mooshrooms, and the 1.21.5 warm and cold pigs, cows and chickens.
• baby — Baby animals, baby villagers, baby zombies.
• color — Any sheep or shulker colour.
• size — Tiny or giant slimes, magma cubes and phantoms.
• powered — A charged creeper.
• sitting — A sitting cat, wolf or parrot (or use the sitting pose below).

Need something more specific? /npc nbt <npc> {...} takes the same NBT as /summon, so anything vanilla can show, your NPC can show: horse markings, axolotl colours, parrot colours. The NBT is checked by Minecraft itself, so it works the same way on every Minecraft version.

🏷️ Names That Look Good

Display names use MiniMessage:

<gradient:#ff9c00:#ffd000><b>Guide</b></gradient><newline><gray>Right-click me

Gradients, rainbow, hex colours, bold and friends, and as many lines as you want with <newline>. Old & colour codes work too. @none hides the name completely.

✨ Make Them Yours

• Equipment: weapons, armor, anything in any slot, even with enchantments and components (/npc equipment <npc> set mainhand hand takes the item you're holding).
• Glowing in any of the 16 vanilla colours.
• Scale from tiny (0.0625) to giant (16x).
• Poses: standing, crouching, sleeping, swimming and sitting (see below).
• Invisible or on fire, for floating names and dramatic effect.
• Turn to player: the NPC follows nearby players with its head and turns back when they leave. Set the distance per NPC.
• Show in tab, with its MiniMessage name, or keep it hidden (the default).
• Visibility distance per NPC, so a busy spawn doesn't send far-away NPCs to everyone.

🪑 Poses, Even Sitting

/npc attribute <npc> set pose <standing | crouching | sleeping | swimming | sitting>

• Sitting player NPCs on vanilla clients. The NPC sits on an invisible seat that, like the NPC, is only packets. Put it on a stair and you have a shopkeeper behind the counter or a guard on a bench.
• Sitting works on players, zombies, skeletons, piglins and illagers (on a seat), cats, wolves, parrots and foxes (their own sitting), and camels (their real sitting pose).
• Sleeping NPCs lie flat and still, and the whole lying body can be clicked, not just the tiny box vanilla gives a sleeper.
• Clicks, cooldowns and turn_to_player keep working in every pose, and the pose is saved with the NPC.

/npc create bartender
/npc attribute bartender set pose sitting
/npc turn_to_player bartender true

🖱️ Interactions

Every NPC has four action lists: right click, left click, any click, and custom (run from a command). Each list runs top to bottom:

• message — Send a MiniMessage line to the player.
• player_command — Run a command as the player.
• player_command_as_op — Run a command as the player, with op rights for that one command.
• console_command — Run a command from the console.
• play_sound — Play any sound, with volume and pitch.
• wait — Pause for some seconds before the next action.
• need_permission — Stop here unless the player has a permission (or !permission to require not having it).
• send_to_server — Send the player to another server of your Velocity or BungeeCord network: send_to_server survival.
• need_item — Stop here unless the player carries enough of an item: need_item diamond 5. Inventory, hotbar and offhand count. It only checks and never takes anything, so pair it with a console_command like clear {player} diamond 5. !diamond means the player must not have it.
• execute_random_action — Pick one of the actions below it at random. Loot NPCs, random quotes, fortune tellers.
• block_until_done — The player can't start the list again until it has finished.

Placeholders: {player} (or {player_name}), {player_uuid}, {player_world}, {npc} (or {npc_name}), and with Text Placeholder API installed, all of its placeholders too (see below).

⏱️ Interaction cooldown: set a per-player cooldown on any NPC so nobody spams your free-kit villager. The player sees how long they have left.

/npc create guide
/npc displayname guide <gradient:#ff9c00:#ffd000><b>Guide</b></gradient><newline><gray>Right-click me
/npc turn_to_player guide true
/npc action guide right_click add message <yellow>Welcome, {player}!
/npc action guide right_click add wait 1
/npc action guide right_click add console_command give {player} bread 3

A trader that wants 5 diamonds:

/npc create jeweller villager
/npc action jeweller right_click add need_item diamond 5
/npc action jeweller right_click add console_command clear {player} diamond 5
/npc action jeweller right_click add console_command give {player} diamond_sword
/npc action jeweller right_click add message <green>Pleasure doing business!

Without 5 diamonds the player gets the noItemMessage from the config ("You need 5x Diamond for that.") and nothing else runs.

🌐 Lobby NPCs (Velocity / BungeeCord)

/npc create survival_portal
/npc displayname survival_portal <green><b>Survival</b><newline><gray>Click to play
/npc action survival_portal right_click add send_to_server survival

send_to_server uses the standard BungeeCord plugin message ("Connect"), so the proxy has to allow it: on Velocity set bungee-plugin-message-channel = true in velocity.toml (it is by default), and use a Fabric proxy mod such as FabricProxy-Lite for player forwarding. On a server without a proxy the action simply does nothing.

💬 Holograms

Floating text anywhere, for welcome signs, shop prices, rules or leaderboards: /hologram, or /holo for short.

• MiniMessage lines, as many as you like. Add, set, insert and remove lines without retyping the rest.
• Placeholders, per player: {player} shows each player their own name. {online}, {max_players} and {world} too, refreshed on a timer you choose.
• Billboard: always face the player (center), stay fixed like a sign (fixed), or turn on one axis (vertical, horizontal).
• Scale, background (default, transparent, any colour, with transparency), text shadow, see through blocks, left, centre or right alignment, and line width.
• Visibility distance per hologram, just like NPCs.
• Link it to an NPC with /holo link <hologram> <npc>: the hologram floats right above the NPC's head (taking its scale, pose and name into account), follows it when it moves, and appears and disappears with it. That's how you give an NPC a name with as many styled lines as you want. Renaming the NPC keeps the link; removing it leaves the hologram where it was.

/holo create welcome <gradient:#ff9c00:#ffd000><b>Welcome to the server!</b></gradient>
/holo text welcome add <gray>Hello, {player}. There are {online} players online.
/holo update_interval welcome 5
/holo background welcome transparent

A three-line name above an NPC:

/npc displayname jeweller @none
/holo create jeweller_sign <gold><b>Jeweller</b>
/holo text jeweller_sign add <gray>5 diamonds for a sword
/holo text jeweller_sign add <green>Right-click to trade
/holo link jeweller_sign jeweller

🔣 Placeholders (Text Placeholder API)

Install Text Placeholder API next to NPCs Fabric and its placeholders work everywhere, for each player:

• NPC names — <gold>Hi %player:name% shows every player their own name.
• Hologram lines, refreshed with /holo update_interval: %server:online%, %server:tps%, and anything other mods add.
• Actions — message, player_command, player_command_as_op and console_command, filled in for the player who clicked.

/npc action guide right_click add message <yellow>Welcome to the server, %player:name%!

It's optional: without it nothing changes, and the built-in {player}, {npc} and friends always work.

⚠️ In console_command, only use {player} or placeholders players can't change themselves (not nicknames), because the text is put straight into the command.

Import from FancyNpcs and Citizens

Moving a server from Paper to Fabric? Bring your NPCs along:

/npc import fancynpcs --dry-run
/npc import fancynpcs
/npc import citizens

• It reads plugins/FancyNpcs/npcs.yml or plugins/Citizens/saves.yml in your server folder, or any file you copy into config/npcsfabric/import/ (/npc import citizens old-saves.yml).
• --dry-run shows what would be imported, skipped and left out, without changing anything. Run it first.
• Existing NPCs are never overwritten. A name that's already taken is skipped, or with --rename imported as guide_2.
• From FancyNpcs: name, type, place, display name (MiniMessage, as is), skin (texture, player name or mirror, slim arms), equipment, glowing and colour, show in tab, collidable, turn to player and its distance, scale, visibility distance, interaction cooldown, attributes (pose, baby, variants…) and every action list (the action names are the same).
• From Citizens: name (its & colours become the display name), type, place, skin, equipment, look close (turn to player), glowing, the Commands trait as actions (player, op and console commands, per click, in order) and hologram lines as a linked hologram.
• world, world_nether and world_the_end become the overworld, nether and end; other worlds are matched by name. NPCs in worlds this server doesn't have are reported and skipped.
• At the end you get a summary: what was imported, what was skipped and why, and every field or action that couldn't be taken over. It's also written to the server log, and everything is saved right away.

📋 Commands

Manage

• /npc create <name> [--type <type>] [--position <x y z>] [--world <world>] — Make an NPC where you stand, or anywhere (also from the console).
• /npc remove <npc> · /npc copy <npc> <new_name> · /npc rename <npc> <new_name>
• /npc list [--type <type>] [--sort name | type | distance | created] — Every NPC, in every world.
• /npc nearby [--radius <blocks>] [--type <type>] [--sort ...] — NPCs around you, closest first.
• /npc info <npc> — Everything about one NPC.

Customize

• /npc type <npc> <type>
• /npc displayname <npc> <@none | text>
• /npc skin <npc> <@none | @mirror | name | uuid | url | file:<name>> [--slim]
• /npc equipment <npc> set <slot> <hand | air | item> · clear · list
• /npc glowing <npc> [disabled | colour]
• /npc scale <npc> <factor>
• /npc attribute <npc> set <attribute> <value> · remove · list — pose, invisible, on_fire, profession, villager_type, variant, baby, color, size, powered, sitting
• /npc attribute <npc> set pose <standing | crouching | sleeping | swimming | sitting>
• /npc nbt <npc> <@none | nbt> — Any looks /summon NBT can give.
• /npc show_in_tab · /npc collidable · /npc turn_to_player · /npc mirror_skin <npc> [true | false]
• /npc turn_to_player_distance <npc> <blocks> · /npc visibility_distance <npc> <blocks>

Move

• /npc move_here <npc> · /npc move_to <npc> <x y z> [world] · /npc rotate <npc> <yaw> <pitch>
• /npc center <npc> — Snap to the middle of its block.
• /npc teleport <npc> — Teleport yourself to it.

Interactions

• /npc action <npc> <trigger> add <type> [value]
• /npc action <npc> <trigger> add need_item [!]<item> [amount] — Item ids tab-complete.
• /npc action <npc> <trigger> add send_to_server <server>
• add_before · add_after · set <number> <type> [value], remove · move_up · move_down <number>, clear, list, execute
• /npc interaction_cooldown <npc> <disabled | seconds>

Holograms (/hologram or /holo)

• /holo create <name> [text] · remove · copy · rename · list · nearby · info
• /holo text <hologram> add <text> · set <line> <text> · insert <line> <text> · remove <line> · clear
• /holo billboard <hologram> <center | fixed | vertical | horizontal>
• /holo scale · background · shadow · see_through · alignment · line_width · visibility_distance · update_interval
• /holo move_here · move_to <x y z> [world] · rotate <yaw> [pitch] · center · teleport
• /holo link <hologram> <npc> · /holo unlink <hologram> — Float above an NPC and follow it.

Admin

• /npc version · /npc save · /npc reload — Re-read the config, every NPC and every hologram from disk, no restart.
• /npc import <fancynpcs | citizens> [file] [--dry-run] [--rename] — Bring NPCs over from Paper.

🔑 LuckPerms Support

Works with LuckPerms or any mod using the Fabric Permissions API. No permissions mod? Everything just needs OP.

Permission	Command	Default without LuckPerms
npc.command	/npc	OP
npc.command.admin	/npc save, /npc reload, /npc import	OP
npc.command.hologram	/hologram, /holo	OP
npc.command.action.<type>	adding or setting an action of that type	harmless types: anyone who can use /npc; console_command, player_command_as_op, send_to_server: OP
npc.command.action.*	adding every action type	as above

Who may add which actions. With LuckPerms, everyone with npc.command can add the harmless actions (message, play_sound, wait, need_permission, need_item, execute_random_action, block_until_done, player_command) by default. console_command, player_command_as_op and send_to_server need their node given explicitly, even for ops, so builders can make NPCs without running commands as the console:

/lp group builder permission set npc.command true
/lp group admin permission set npc.command.action.* true

Builders now make NPCs that talk, play sounds and run commands as the player who clicks; only admins can add console commands. Removing, moving and listing actions only need npc.command.

⚠️ With LuckPerms, give admins npc.command.action.* (or *) so they can add console commands; being OP is not enough when LuckPerms is installed. Without LuckPerms, OPs can add every action type as before.

need_permission actions check any node you like, such as server.vip, so NPCs can be locked to ranks.

⚙️ Configuration

config/npcsfabric/config.json is written with defaults on first run: the default visibility and turn distances, how close players must be to click an NPC (maxInteractDistance, 6 blocks), the click debounce, the autosave interval, your MineSkin API key, and the no-permission, missing-item (noItemMessage, hasItemMessage) and cooldown messages (MiniMessage). Edit it and run /npc reload.

Every NPC lives in config/npcsfabric/npcs.json and every hologram in config/npcsfabric/holograms.json, saved after every change and on shutdown. Running click cooldowns are kept in config/npcsfabric/cooldowns.json, so logging out or restarting never resets a daily reward. Skins are stored with the NPC, so they are never fetched twice and keep working if Mojang's API is down.

🛡️ Your NPCs are safe. If a save file ever gets damaged, it is kept as a .broken copy and never replaced by an empty one.

Requirements

Two jars, the same mod: pick the one for your Minecraft version.

Minecraft	Download	Java	Fabric Loader	Also needs
1.21 to 1.21.11	NPCs-Fabric-<version>.jar	21	0.16.0+	Fabric API
26.1 to 26.3	NPCs-Fabric-<version>+26.x.jar	25	0.18.4+ (0.19.3+ on 26.3)	Fabric API

Both have the same commands, permissions, config and features. Upgrading your server from 1.21.x to 26.x? Swap the jar: your NPCs, holograms, skins, cooldowns and settings in config/npcsfabric/ carry over as they are.

Optional: LuckPerms, Text Placeholder API, a MineSkin API key for skins from image URLs and PNG files.

Minecraft 26.2 only: on a Peaceful server, 26.2 players don't see monster NPCs (zombies, creepers, slimes…), because the 26.2 game drops every monster on Peaceful. 26.1, 26.3 and 26.2 on Easy or higher are fine.

---

Contact me in my discord server if you need porting to other versions or to adjust the mod to your server