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.

Works on every Minecraft 1.21 release, from 1.21 to 1.21.11, with one jar.

⭐ 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, or an image URL (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.

🐱 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 1.21 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).
• 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}, {player_uuid}, {player_world}, {npc}, 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.

💬 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.

📋 Commands

Manage

• /npc create <name> [type] — Make an NPC where you stand.
• /npc remove <npc> · /npc copy <npc> <new_name> · /npc rename <npc> <new_name>
• /npc list [type] — Every NPC, in every world.
• /npc nearby [radius] — 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> [--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.
• 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.

🔑 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	OP
npc.command.hologram	/hologram, /holo	OP

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

• Minecraft 1.21.x (1.21 to 1.21.11, one jar)
• Fabric Loader 0.16.0+
• Fabric API
• Java 21
• Optional: LuckPerms, Text Placeholder API, a MineSkin API key for skins from image URLs

---

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