Guard Villager Skins

A client-only Forge 1.20.1 add-on for Guard Villagers. Drop ordinary Minecraft player skins into config/guard_skins, and every Guard in the world puts one on — random-looking, but the same Guard keeps the same face across chunk reloads and restarts.

No resource pack. No server install. Nothing is uploaded or downloaded, ever.

Setup

1. Install Forge 1.20.1, Guard Villagers, and this mod on the client.

2. Launch once. config/guard_skins/ is created for you, with a _README.txt inside.

3. Turn on Guard Villagers' player model. In config/guardvillagers-client.toml:

   "Have guards use the steve model?" = true

   Then restart the game — Guard Villagers chooses its model once, at startup, so changing this while playing does nothing until the next launch.

4. Put 64×64 player-skin PNGs in config/guard_skins/. Subfolders are fine.

5. Press F3+T, or run /guardskins reload.

What counts as a skin

Format	PNG, exactly 64×64
Arm layouts	Classic (4px) and slim / Alex (3px), both
Overlay layers	Hat, jacket, sleeves and trousers all render
Legacy 64×32	Rejected — convert it to 64×64 first
Anything else	Rejected, and named in /guardskins status

Bad files fail one at a time. A corrupt PNG in the folder costs you that PNG, not the rest.

Classic or slim

Nothing inside a PNG records which arm width it was drawn for, so this mod looks at the arm pixels: a slim skin leaves the texels a wider arm would use transparent. That guess is right for most skins and wrong for a few — a slim skin exported with those texels painted in reads as classic.

To be certain, 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 here is slim
└── regional/
    └── desert_sentinel.png     guessed from the pixels

_slim, -slim and .slim all work, as do their classic equivalents. A filename marker beats a folder marker.

Set armModelDetection in the config to classic or slim to skip the guessing entirely for unmarked skins.

Commands

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

Command	What it does
/guardskins	Same as status
/guardskins reload	Rescan the folder and report what loaded
/guardskins status	Enabled state, whether the Steve model is actually active, folder path, counts, seed, and any rejected files
/guardskins list [page]	Every loaded skin with its arm model
/guardskins folder	The absolute path skins are read from
/guardskins explain	Why the Guard under your crosshair is wearing what it is wearing
/guardskins rules validate	Check the optional rulebook and name anything wrong with it
/guardskins rules list [page]	Rules with their priorities and pools
/guardskins pools [page]	Named pools and how many skins are in each
/guardskins pools show <pool>	The exact contents of one pool, with weights

F3+T reloads the folder too, alongside your resource packs. The server's /reload command does not — it has nothing to do with files on your machine.

Which Guard gets which skin

Selection is deterministic: the same Guard, the same folder and the same seed always produce the same skin. It survives a restart because it is recomputed rather than remembered, so there is no database to corrupt or migrate.

It also degrades gracefully when the folder changes. Adding a skin only moves the Guards that skin wins outright; removing one only moves the Guards that were wearing it. Everybody else keeps the face you already know them by. Repainting a PNG without renaming it changes how that skin looks and moves nobody.

Two things do reshuffle Guards, both deliberately: changing selectionSeed, and renaming a file.

Advanced: contextual skins

By default nothing changes — drop skins in the folder and the mod chooses from all of them. Everything in this section is optional and off unless you turn it on.

If you want desert guards to look different from snowy ones, or archers different from swordsmen, set selectionMode = "rules" in the config and edit config/guardvillagerskins-rules.toml, which is created for you with worked examples commented out inside it. You can then divide your skins into named pools and choose a pool from the Guard's region, the biome it is standing in, the weapon in its hands, or a combination with explicit priority.

[pools.desert]
	include = ["biome/desert/**/*.png"]

[[rules]]
	id = "desert_guards"
	priority = 100
	pools = ["desert", "common"]

	[rules.when]
	guardVariants = ["desert"]

Switching the mode on without editing the rulebook changes nothing at all: the generated file holds one pool containing every loaded skin, so every Guard keeps the face it already had. Look at a Guard and run /guardskins explain to see which rule chose its skin.

Full guide: docs/skin-rules.md. Annotated template: docs/examples/guardvillagerskins-rules.toml.

Multiplayer

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

You have the mod, the server does not	Works. This is the normal case.
Another player does not have the mod	They see ordinary Guards. Nothing breaks.
Two players with different folders	They see different Guards. This is expected.
Two players with identical folders and the same selectionSeed	They see identical Guards.
The mod installed on a dedicated server by accident	It loads, does nothing, and gets in nobody's way.

Configuration

config/guardvillagerskins-client.toml:

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

[models]
	armModelDetection = "auto"

[selection]
	selectionMode = "flat"
	contextChangeDelayTicks = 0

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

[cache]
	maxGuardAssignments = 8192

applyBiomeVariantOverlay is the one worth knowing about. Guard Villagers draws a regional uniform across the whole Guard, which would paint over the skin you chose — so with a custom skin in place, it is skipped. Set this to true to put the uniform back on top. Guards with no custom skin always keep theirs.

selectionMode stays flat unless you want the optional rules layer described above. contextChangeDelayTicks only applies in rules mode: it is how long a Guard's new situation must hold before its skin follows, in ticks, which stops a Guard flickering while it walks along a biome border. Zero is immediate.

When nothing happens

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

• "Guard Villagers Steve model: no" — set it in guardvillagers-client.toml and restart.
• "Loaded: 0 skins" — check the rejection list underneath. Wrong size is the usual culprit.
• Skins load but Guards look unchanged — the Steve-model setting was changed without a restart.
• 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 and tested against Guard Villagers 1.6.19 on Forge 47.4.22, Minecraft 1.20.1. The declared range is [1.20.1-1.6.19,1.20.1-1.7), but only 1.6.19 has actually been run.

This mod reaches into Guard Villagers' renderer with four narrow Mixin injections across two classes and no overwrites, so it inherits upstream changes to models, poses, animations, armour and scaling for free. It does not replace the entity renderer, so it should coexist with other rendering mods — though if another mod also changes the Guard's base texture, which one wins depends on injection order.

Not in this release

• Fetching a skin by username, UUID or URL. Local files only.
• 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.
• Nested boolean expressions in rules. Priority plus several small rules covers the same ground and stays explainable.
• Remembering the biome a Guard originally spawned in. Use guardVariants, which Guard Villagers already stores and keeps stable.

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.

Building

./gradlew build

Needs libs/guardvillagers-1.20.1-1.6.19.jar — see docs/dependencies.md. That jar is not committed, because Guard Villagers' assets are All Rights Reserved.

Licence

GPL-3.0-only.

Guard Villagers is a separate project with its own terms: MIT for its code, All Rights Reserved for its assets. MIT is GPL-compatible, so this mod may link against it; no Guard Villagers asset is copied into this mod, and its jar is not redistributed here.