Skins

Custom skin parts

Mercenaries that don't roll a preset are built up from four texture layers stacked on top of one another:

skin - base skin tone (face, hands, neutral body).
clothes - outfit, armor visuals, robes, etc.
eyes - overlaid eye texture.
hair - overlaid hair texture.

Each layer is a skin part loaded from a JSON file. At spawn, Magic Realms picks one part of each category, weighted, filtered by the mercenary's gender and entity class.

File location

data/magic_realms/mercenaries/skin_parts/<your_id>.json

The texture itself goes in assets/magic_realms/textures/... (or wherever you point texture to).

Schema

Field	Type	Default	Notes
`texture`	string	-	Required. ResourceLocation of the texture (e.g. `"my_pack:textures/entity/human/skin/dark.png"`).
`category`	string	-	Required. One of `"skin"`, `"clothes"`, `"eyes"`, `"hair"`.
`gender`	string	`"any"`	One of `"any"`, `"male"`, `"female"`.
`entity_class`	string	`"any"`	One of `"any"`, `"common"`, `"mage"`, `"rogue"`, `"warrior"`. `"common"` is also a wildcard (eligible for every class) but is conventionally used to mark "neutral" pieces like plain shirts.
`weight`	int (≥ 1)	`1`	Weight inside its category pool. Higher = more common.

Example: a female-only mage robe

{
  "texture": "my_pack:textures/entity/human/clothes/violet_robes.png",
  "category": "clothes",
  "gender": "female",
  "entity_class": "mage",
  "weight": 2
}

Example: a generic skin tone usable everywhere

{
  "texture": "my_pack:textures/entity/human/skin/freckled.png",
  "category": "skin",
  "weight": 1
}

(Both gender and entity_class default to "any", so they don't need to be listed.)

When the catalog has no matching parts for a given (category, gender, class) combination, the mercenary spawns with that layer missing - Magic Realms logs a warning and continues. So if you're filtering aggressively, make sure each (category, gender, class) triple still has something eligible (or rely on "any" fallbacks).

Custom skin presets

A skin preset is a single complete texture used as-is, instead of compositing the four-layer skin parts. They're meant for handcrafted / iconic looks where you want every pixel to be exactly right.

When a mercenary spawns, there's a chance (configurable via customTextureChance, default ~15%) that a preset is rolled instead of building from parts. If the preset specifies fixed_personality_id, the linked fixed personality is also stamped on the mercenary, so identity (look + behavior) stays welded together.

File location

data/magic_realms/mercenaries/skin_presets/<your_id>.json

Schema

Field	Type	Default	Notes
`texture`	string	-	Required. ResourceLocation of the full preset texture.
`display_name`	string	absent	Optional. If set, the mercenary is named this.
`gender`	string	`"any"`	One of `"any"`, `"male"`, `"female"`. Used to filter the pool by the mercenary's gender.
`weight`	int (≥ 1)	`1`	Weight inside the preset pool.
`fixed_personality_id`	string	absent	Optional. Full ResourceLocation of a fixed personality to lock to this preset (e.g. `"my_pack:vex"`).
`added_to_pool`	boolean	`true`	Optional. When `false`, the preset is loaded but excluded from the random roll pool. Useful for future bandit profiles.

If both display_name and the linked fixed personality's override_entity_name are present, the preset's display_name wins. If only the personality has an override name, that override is used as the mercenary's display name.

Example: a generic preset

A finely-detailed female ranger that can roll on any random mercenary:

{
  "texture": "my_pack:textures/entity/human/preset/ranger_alia.png",
  "display_name": "Alia",
  "gender": "female",
  "weight": 3
}

Example: an identity-locked preset

A preset for the named character "Vex" defined earlier - appearing only when this preset rolls, and bringing their full personality with them:

{
  "texture": "my_pack:textures/entity/human/preset/vex.png",
  "gender": "female",
  "weight": 1,
  "fixed_personality_id": "my_pack:vex"
}

Notice we don't need display_name here - the override name comes from the linked fixed personality.

Skins

On this page