Recruits Skins

0.2.0 — September 1, 2026

Added

• Optional skin rules. You can now create rules that choose Recruit skins based on their type, faction, region, biome, dimension, equipment, and more.

• Named skin pools. Group existing skins into custom pools without moving, copying, or renaming the skin files. A skin can belong to multiple pools.

• Context-based skins. Rules can react to things like:

  • Recruit type
  • Region and original face
  • Faction and faction color
  • Current biome and dimension
  • Items being held
  • Weapon type
  • Shield usage
  • Any of the above in reverse/negated form

• Weapon categories. Rules can recognize swords, axes, bows, crossbows, tridents, shields, melee weapons, ranged weapons, and more. Modpacks can also create their own categories for custom weapons.

• Clothing layer controls. Rules can independently show or hide Recruits' team, biome, and companion clothing layers.

• Flexible skin pools. Pools can be combined using union, intersection, or first-available selection.

• Skin weights and exclusions. You can make certain skins more or less common, add them to specific pools, or prevent them from being selected without removing the skin file.

• Mod-friendly rules. Rules can safely reference optional mods, tags, and custom items. Missing mods simply result in those rules not matching.

• Rule diagnostics. Added commands for inspecting and troubleshooting skin rules:

  • /recruitsskins explain
  • /recruitsskins rules validate
  • /recruitsskins rules list
  • /recruitsskins pools
  • /recruitsskins pools show <pool>
  • /recruitsskins status

• Context change delay. Added an optional delay to prevent skins from rapidly changing when a Recruit crosses a biome border, switches weapons, or changes factions. The default is immediate changes.

Changed

• Existing behavior is unchanged by default. selectionMode remains flat, so players upgrading from 0.1.0 will keep the same skin-selection behavior and existing Recruit skins.
• Added an optional selection configuration section for enabling the new rule system.
• Skin assignments are now updated more reliably when relevant server data changes.
• Improved handling of configuration errors. If a rule file is temporarily broken or cannot be read, the last working version is kept instead of crashing or disabling the skin system.
• The skin configuration README now includes information about the optional rule system.

Compatibility

• No existing skin files need to be changed. Stable skin keys, texture locations, model markers, and the config/recruits_skins folder remain compatible with 0.1.0.
• The new rules system is completely optional.
• Using selectionMode = "flat" preserves the original 0.1.0 skin-selection behavior.
• A broken or unreadable rule file will not crash the game. The last known working rules are used when available.
• Existing mods and integrations do not require changes.

Known Limitations

• Rules cannot currently use complex nested conditions.
• Rules cannot react to a Recruit's level, kills, morale, hunger, orders, owner, or mount.
• Promoting a Recruit can change its skin because Recruits replaces the entity during promotion.
• Weapon durability, stack count, enchantments, custom names, and NBT do not affect skin selection.
• Skin weights are relative weights, not percentages. For example, 0.15 does not mean a 15% chance.
• Some complex combinations of rules and live gameplay still require manual testing.