Humanoid and NPC presets

Player presets store a reusable appearance. NPC presets store a base character and selectable outfit overlays. They share appearance fields but have different application and unlock rules.

Where the files live

These are server data-pack resources. Models and textures are separate client resources. A file is a complete definition, not a patch to another preset.

Player titles use humanoid_preset.<namespace>.<path>, descriptions add .desc, and outfit titles use npc_outfit.<namespace>.<preset_path>.<outfit_id>. Slashes in preset paths become dots.

Minimal example

A player gallery entry at data/example/humanoid_presets/simple.json, using bundled parts:

{
  "gender": "female",
  "parts": {
    "body": "isekaiexpansion:body/feminine",
    "eyes": "isekaiexpansion:eyes/default"
  },
  "sort": 1000
}

For the bundled citizen wardrobe, save this at data/isekaiexpansion/npc_presets/citizen.json. It leaves citizen appearance generation in place and adds an explicitly rewarded overlay:

{
  "outfits": [
    { "id": "default", "default": true },
    {
      "id": "without_hair",
      "category": "hair",
      "unlock": { "type": "granted" },
      "parts": { "hair": "none" }
    }
  ]
}

The reward record is per player and keyed by preset ID plus outfit ID, so it applies to every NPC sharing that preset.

Fields

Shared root and preset metadata

A player preset can load as an empty object, but it then contains the default profile with no explicit parts. Applying the whole preset replaces build, face, palette and parts, changes gender, and preserves the player’s age, character name and origin. Applying selected part kinds overlays only those slots; body selection also copies build, face selection copies face, and every partial application copies the entire palette.

For NPCs, the presence of any profile field marks the preset authored, even an empty parts object. Base NPCs use that authored profile. Citizens override initial profile resolution with generated appearances; their presets chiefly supply wardrobes. See NPC assets for generation and entity wiring.

Body shape

Height and all multipliers except chest_size require a positive finite value: zero, negative and nonfinite values reset to the default; other values clamp to the stated range. chest_size, chest_lift and chest_spread clamp finite values, with nonfinite values resetting to their defaults. Wrong JSON types can fail the whole file.

Face shape

Signed face values clamp to -1–1 and nonfinite values become 0. Eye scale requires a positive finite value; otherwise it becomes 1. These values adjust the shared rig, so a part must use the matching bones to show the adjustment.

Palette

Colours accept integers or hexadecimal strings with optional # or 0x; even an unprefixed string is hexadecimal. Only the low 24 bits are kept; alpha is discarded. A missing channel keeps the table default, while explicit null or invalid hexadecimal text becomes #FFFFFF. Arrays or objects in a colour field can fail parsing.

Part slots and overlays

Slot names are trimmed and case-insensitive. Unknown slots are ignored. A reference can be an identifier string or an object with part and optional style. Preset JSON does not import custom paint data.

In the base profile, null, a blank string, none, or an invalid part ID leaves that slot empty. In an outfit overlay, an absent slot, null or an invalid ID inherits the base; the explicit string none clears the slot. This applies to every slot, including body. Changing outfits restores whatever the underlying profile supplies.

Some parts are chained: one garment spread across several slots, such as the default male briefs isekaiexpansion:underwear_top/default_male and isekaiexpansion:underwear_bottom/default_male. An outfit that names one member wears the whole chain, and none on one member clears all of it. A player preset that names only one member receives the rest when the profile is validated, provided their slots are empty; otherwise the chain is dropped. See part chains.

A valid identifier does not prove a part, model or texture exists. An unavailable style falls back only to default; if that is unavailable too, the renderer skips the part.

NPC outfits

The initial outfit is the first retained default, otherwise the first always outfit, otherwise the first outfit whose rule is not locked, otherwise the first entry. This fallback does not evaluate a particular player’s progress. An empty list supplies the fallback default outfit.

Repeated IDs keep the last definition but retain the first insertion position. Only the first declared default keeps its flag; later declared defaults have already been made always before their flags are removed. Use unique IDs and a single explicit default to avoid these interactions.

Attribute bonuses require the NPC to expose the target attribute. Missing attributes are skipped with a warning. Use each attribute only once in an outfit: the modifier identity includes preset, outfit and attribute, but not operation, so repeated entries are not independent stackable bonuses. Lowering maximum health clamps current health to the new maximum.

Unlock rules

The following keys live inside player unlock or NPC outfits[].unlock:

Omitting an NPC outfit’s rule means always, not granted. An outfit marked default: true also forces always, regardless of its supplied rule.

The current player preset gallery does not evaluate a preset’s unlock rule: all loaded presets get selectable cards. Submission contains a profile rather than a preset ID, and the server validates the resulting parts individually. A preset rule therefore does not restrict access to that template; part rules and NPC outfit rules have their own checks.

Validation

Unknown keys are ignored. A malformed field that throws during conversion rejects the entire preset, including all of its outfits. The loader logs that file and replaces the catalogue with the successful files; a failed definition does not retain its previous version. Missing optional fields use the defaults above. Identifier syntax is checked separately from whether the referenced content exists.

Player-preset tags longer than 48 characters, unlock nodes longer than 64 characters and outfit IDs longer than 128 characters can load but exceed their network writers. These bounds are not enforced by the JSON loaders.

The current NPC exporter omits explicit granted unlock rules, while the reader treats omission as always. Restore that rule after exporting a rewarded outfit before using the output in a pack. Profile export also omits paint, writes nondefault shape values rounded to 3 decimal places and emits colours as hexadecimal RGB.

Reloading

After a successful server data-pack reload, online players receive the part catalogue and player preset gallery, their profiles are revalidated, and loaded NPCs refresh from their presets. This is separate from reloading client models and textures.

Player presets are templates: changing one does not reapply it to every player who previously selected it. Revalidation checks their saved profiles against the current part catalogue and unlocks. Authored NPCs reread their initial profiles; generated citizens still run their generation override. Removed outfit IDs fall back to the current default selection.

There is a current attribute-cleanup limitation: refresh removes modifiers described by the new outfit catalogue. Deleting an old outfit or attribute declaration can therefore leave its temporary modifier on an already loaded NPC. Verify existing NPC attributes as well as newly spawned NPCs when editing these definitions.

Related

NPC asset authoring, NPC runtime and Identity.