Guard Villager Skins

Your guards, wearing real player skins. Drop ordinary Minecraft skin PNGs into a folder and every Guard Villagers guard puts one on. No resource pack, no server install, no restart loop. Each guard picks a skin that looks random but never changes — the scarred veteran at the north gate is still the scarred veteran at the north gate tomorrow, next week, and after you reinstall the pack.

Although the mod may currently do little more than what one could reasonably do with a resource pack, I fully intend to expand on it further in the near future.

Minecraft 1.20.1 · Forge 47.x · Java 17 Client-side only. Free and open source, GPL-3.0-only. Requires Guard Villagers.

What it actually does

• Reads a folder, not a resource pack. Skins live in config/guard_skins/. The folder is created for you on first launch with a _README.txt in it. Put PNGs in, press <kbd>F3</kbd>+<kbd>T</kbd>, done. Subfolders work and are purely for your own organisation — sort by region, by author, by whatever you like.
• Every guard is a different person. With eight skins in the folder, a village of twenty guards is twenty guards with eight faces spread across them, not twenty copies of one texture. That is the whole point: a resource pack can only give Guard Villagers one shared skin.
• The same guard keeps the same face. Assignment is computed from the guard's UUID rather than remembered, so it survives chunk unloads, world reloads, game restarts, and reinstalls — with no database file to corrupt or migrate. Convert a villager into a guard and it gets its face immediately; summon one with a spawn egg and so does it.
• Adding a skin does not reshuffle the village. This is the part most implementations get wrong. Drop a ninth skin in and only the guards that skin actually wins change; everybody else keeps the face you already know them by. Delete a skin and only the guards who were wearing it move. Repaint a PNG in place without renaming it and it changes how that skin looks while moving nobody at all.
• Slim and classic arms, both. A _slim or _classic suffix in the filename, or a slim/ or classic/ subfolder, settles it outright. Otherwise the mod inspects the arm pixels — a slim skin leaves the texels a wider arm would cover transparent — and works it out. Slim guards get a proper three-pixel-arm model, not a stretched classic one.
• Reload without restarting. <kbd>F3</kbd>+<kbd>T</kbd> reloads the folder alongside your resource packs. /guardskins reload does the same on demand. Scanning and decoding happen off the render thread, so a folder of hundreds of skins does not freeze the game.
• It tells you why nothing happened. /guardskins status reports whether the add-on is enabled, whether Guard Villagers is actually using its player model right now, the folder path, how many skins loaded split by arm type, and every file that was rejected with the reason — "expected 64x64, found 128x128", not a silent shrug.
• Bad files fail one at a time. A corrupt PNG costs you that PNG. Wrong-sized images, legacy 64×32 skins, empty files, and text files somebody renamed to .png are all named and skipped while their neighbours load normally. An empty folder is not an error either — guards simply look exactly as Guard Villagers draws them.
• Keeps the skin you chose visible. Guard Villagers paints a regional uniform across the whole guard, which would cover a custom skin entirely. While a custom skin is in use, that overlay is skipped. Guards on the upstream texture keep theirs, and applyBiomeVariantOverlay = true puts it back if you want the uniform on top.

Armour renders over the skin as normal. Hat, jacket, sleeve and trouser overlay layers all animate with the body. Bows, crossbows, shields, eating and the guard kick animation are untouched — the mod changes one texture and, for slim skins, one model, and leaves everything else to Guard Villagers.

Why bother

Guard Villagers ships a "use the Steve model" option and a single guard_steve.png. If you want your guards to look like anything else, your options today are: make a resource pack, or live with every guard in the world being identical.

This mod turns that into a folder you drag files into. And because assignment is stable and minimally disruptive, curating that folder is actually pleasant — you can add a skin mid-playthrough without the entire village swapping faces, which is what makes it worth building a roster over time rather than setting it once and never touching it.

For modpack authors: ship the same config/guard_skins contents and the same selectionSeed to every client and everyone sees the same guards in the same places, without a single byte crossing the network.

Screenshots

Placeholder — add screenshots before publishing:

• A village gate with four or five visibly different guards standing together.
• A slim-armed guard beside a classic-armed one, close up on the arms.
• A guard in full armour, showing armour rendering over a custom skin.
• /guardskins status output in chat, including a rejected file.

Only use skins you own or have permission to show.

Requirements

• Minecraft 1.20.1 with Forge 47.x (built and tested against 47.4.22).
• Guard Villagers 1.6.19 — mandatory, client side.
• Guard Villagers' player model option turned on (see Installation).

Guard Villagers is declared a hard client-side dependency, so a client without it refuses to load with a clear message rather than crashing later.

Installation

1. Install Forge for 1.20.1.
2. Drop both jars into your mods/ folder:
   • guardvillagers-1.20.1-1.6.19.jar
   • guardvillagerskins-0.1.0.jar (this mod)
3. Launch once. This creates config/guard_skins/ and config/guardvillagerskins-client.toml.
4. Turn on Guard Villagers' player model. Open config/guardvillagers-client.toml and set:

   "Have guards use the steve model?" = true

Then restart the game. Guard Villagers picks its model once, at startup — changing this setting while playing does nothing until the next launch. This trips up nearly everyone, so /guardskins status reports the live state explicitly.

1. Put 64×64 player-skin PNGs into config/guard_skins/.
2. Press <kbd>F3</kbd>+<kbd>T</kbd> or run /guardskins reload.

Only install it on the client. A dedicated server does not need it, does not benefit from it, and if it ends up there by accident it loads and does nothing.

What counts as a skin

Any skin from any skin site works, as long as it is the modern 64×64 layout. Your own Minecraft skin works. So does a skin you drew yourself.

Telling the mod about slim skins

Nothing inside a PNG records which arm width it was drawn for, so the mod looks at the arm pixels and works it out. That is right for most skins and wrong for a few — a slim skin exported with those unused texels painted in reads as classic.

If the arms look a pixel off, say so in the name or the folder:

config/guard_skins/
├── royal_guard_slim.png        forced slim
├── city_watch_classic.png      forced classic
├── slim/
│   └── forest_ranger.png       everything in this folder is slim
└── regional/
    └── desert_sentinel.png     worked out from the pixels

_slim, -slim and .slim all work, as do their classic equivalents, and a filename marker beats a folder marker. Or set armModelDetection to classic or slim in the config to skip the guessing entirely.

Renaming a file changes which guards wear it. Repainting one in place does not.

Commands

Every command is client-side, so they work on any server — including one that has never heard of this mod.

<kbd>F3</kbd>+<kbd>T</kbd> reloads the folder too. The server's /reload does not — it has nothing to do with files on your machine.

Configuration

config/guardvillagerskins-client.toml:

[general]
    enabled = true
    applyBiomeVariantOverlay = false
    selectionSeed = 0

[models]
    armModelDetection = "auto"

[loading]
    recursive = true
    maxScanDepth = 8
    maxSkinCount = 512
    maxFileSizeKiB = 1024
    showReloadSummary = true

[cache]
    maxGuardAssignments = 8192

Three settings are worth knowing about:

• selectionSeed — change it to reroll every guard in the world at once. Modpacks that want every player to see identical guards must ship the same seed.
• applyBiomeVariantOverlay — set it to true to put Guard Villagers' regional uniform back on top of your skins.
• armModelDetection — auto, classic or slim, for skins with no filename marker.

Everything else is bounds and logging.

Multiplayer

Your skins are yours alone. The server is never told about them and does not need the mod.

The mod never uploads, downloads, or fetches a skin by username, UUID or URL. It reads files on your disk and nothing else.

When nothing happens

Run /guardskins status first — it answers most of this.

• "Guard Villagers Steve model: no" — set the option in guardvillagers-client.toml and restart. Easily the most common cause.
• "Loaded: 0 skins" — read the rejection list underneath. Wrong image size is usually it.
• Skins load but guards look unchanged — the model setting was changed without restarting.
• Arms look a pixel out — the slim guess went the wrong way. Rename the file with a _slim or _classic suffix.

With no usable skins, guards render exactly as Guard Villagers draws them. That is the intended fallback, not a failure.

Compatibility

Built with three narrow Mixin injections and no overwrites, so it inherits Guard Villagers' models, poses, animations, armour and scaling rather than duplicating them. It does not replace the entity renderer, so it should coexist with other rendering mods. If another mod also changes the guard's base texture, which one wins depends on injection order — report it and it will be documented.

Only Guard Villagers 1.6.19 has been tested. The declared range accepts 1.6.x point releases, but if a future Guard Villagers changes its renderer, this mod fails loudly at load with a Mixin error rather than silently doing nothing.

Not in this release

• Fetching a skin by username, UUID or URL. Local files only, deliberately.
• Server-enforced or synchronised skin assignments.
• Capes, elytra textures, animated PNGs, or HD skin layouts.
• Pinning a specific skin to a specific guard by hand.

Skin rights

Skins in your own folder are your business. If you ship a modpack with skin artwork in it, make sure you have permission to distribute that artwork. Player skins are made by people, and a lot of them are not free to redistribute.

Licence and credits

GPL-3.0-only. Source at github.com/otectus/GuardsSkins.

Guard Villagers by TallestEgg is a separate project with its own terms — MIT for its code, All Rights Reserved for its assets. No Guard Villagers asset is copied into this mod, and its jar is not redistributed with it.