Guard Villager Skins

[0.2.0] — August 29th, 2026

A major customization update adding optional contextual skin rules for Guard Villagers.

By default, nothing changes. selectionMode remains flat, which preserves the exact 0.1.0 skin-selection behavior and keeps existing Guards on their current skins.

Contextual Skin Rules

Added an optional:

config/guardvillagerskins-rules.toml

This file lets modpack authors divide existing skins into named pools and choose which skins Guards can use based on their current context.

Rules can match things such as:

• Guard Villagers regional variant.
• Current biome.
• Dimension.
• Main-hand or off-hand item.
• Weapon type.
• Shield usage.
• Negated versions of those conditions.

Rules are evaluated by priority, with the first valid match deciding which skin pool is used.

Named Skin Pools

Existing skins can now be grouped into reusable named pools using path patterns.

• Supports *, ?, and ** wildcards.
• Subfolders can be matched.
• Matching is case-insensitive and cross-platform.
• One skin can belong to multiple pools.
• No files need to be copied, moved, or renamed.

Weapon-Based Skins

Added built-in weapon categories:

• empty
• sword
• axe
• bow
• crossbow
• trident
• shield
• melee
• ranged
• other
• weaponless

Modpacks can also define their own categories through [[weaponOverrides]].

Custom categories can match items by:

• Exact item ID.
• Item tag.
• Wildcard.

This allows rules for things such as firearms, staffs, spears, or weapons from other mods without requiring custom compatibility code.

Pool Combination

Rules can combine multiple pools using:

• union
• intersection
• first_non_empty

If a skin belongs to several selected pools, it is still treated as one skin rather than receiving accidental duplicate weighting.

Weighted Skin Selection

Added [[skinOverrides]] for fine-grained control over individual skins.

You can:

• Change a skin's relative selection weight.
• Change its weight within a specific pool.
• Add it to additional pools.
• Remove it from pools.
• Exclude it from selection entirely without deleting the PNG.

Weights are relative rather than percentages.

Optional-Mod-Friendly Rules

Rules can safely reference items and tags from mods that are not installed.

A missing optional mod simply produces no match instead of causing an error, allowing one rulebook to work across several modpack configurations.

Per-Guard Biome Overlay Control

Rules can now override the global biome-uniform setting for individual Guards.

This allows, for example, one skin pool to retain Guard Villagers' regional uniform while another uses the custom skin by itself.

Context Change Delay

Added:

contextChangeDelayTicks

This controls how quickly a Guard changes skins after its context changes, such as:

• Crossing a biome boundary.
• Switching weapons.
• Equipping or removing a shield.

Default: 0 — changes happen immediately.

A Guard being seen for the first time is always assigned immediately.

New Diagnostic Commands

Added:

• /guardskins explain
• /guardskins rules validate
• /guardskins rules list
• /guardskins pools
• /guardskins pools show <pool>

/guardskins explain shows why the Guard under your crosshair received its current skin, including:

• Current context.
• Matching rule.
• Selected pool.
• Number of eligible skins.
• Chosen skin.
• Biome-overlay behavior.
• Higher-priority rules that were skipped and why.

/guardskins status now also shows rule-selection information and warns when the rulebook could not be loaded.

New Selection Settings

The client config now includes a new [selection] section.

Existing settings keep their previous names, meanings, and defaults.

Safe Rule Reloading

Broken or half-edited rule files will not crash the client.

If the current rulebook fails to load:

• The last successfully loaded version remains active.
• Newly changed skin PNGs can still reload.
• If no valid rulebook has ever loaded, the mod safely falls back to the full skin catalog.
• /guardskins status clearly reports the problem.

Flat Mode Remains Unchanged

selectionMode = "flat"

continues to use the exact original 0.1.0 selection behavior.

Flat mode does not inspect:

• Biomes.
• Dimensions.
• Equipment.
• Weapons.
• Context rules.

Switching to rules mode with the default untouched rulebook also produces the same skin choices as flat mode.

Compatibility

• Existing Guard skin assignments remain stable.
• Existing skin paths and folders are unchanged.
• Classic/slim detection is unchanged.
• Texture locations are unchanged.
• No new packets.
• No entity data.
• No capabilities.
• No world-save data.
• No additional Mixins.

The update remains entirely client-side.

Testing & Reliability

The rule system is extensively covered by automated tests for:

• Globs and selectors.
• Pool membership.
• Rule priority.
• Weapon classification.
• Weighted selection.
• Invalid configurations.
• Context changes.
• Compatibility fallbacks.

The automated test suite has grown from 44 to 200 tests.

Known Limitations

• Rules currently use simple priority-based conditions rather than nested boolean expressions.
• The mod does not remember which biome a Guard originally spawned in.
• Item stack size, durability, enchantments, custom names, and NBT do not affect weapon matching.
• Skin weights are relative values, not percentages.
• Live-world biome and weapon switching still receive manual in-game testing in addition to the automated suite.