# Totk Bumii Character

> Build Tears of the Kingdom UMii NPC actor mods from BOTW UMii `.bumii` exports. Use when the user points to a `.bumii` file, BOTW UMii GUI export, Mii-to-UMii character file, or asks to create a TOTK character/NPC actor pack from those files, including optional RSDB and Banc placement output.

- Skill: `cargocult-mods/totk-bumii-character` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add cargocult-mods/totk-bumii-character`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cargocult-mods/totk-bumii-character/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cargocult-mods (https://skillmd.com/u/cargocult-mods)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cargocult-mods/totk-bumii-character

---


# TOTK BUMii Character

## Vanilla RomFS Rule

Use a vanilla TOTK `romfs` path already supplied in the current turn or registered project guidance. Otherwise ask the user for it before inspecting game files. Treat the path as read-only; do not search unrelated folders or guess a location.

Use this skill when a character appearance should come from a BOTW UMii `.bumii` export and become a testable TOTK UMii actor.

Pair this skill with `totk-local-operator`, `totk-toolkit`, and `totk-actor-cloner` for file inspection, dictionary handling, actor pack validation, and placement work.

## Inputs

Collect or confirm:

- Vanilla TOTK `romfs` folder, unless the current turn or project guidance already provides it. Treat it as read-only.
- Source `.bumii` file. Do not edit it.
- Output mod folder. Build a fresh standalone overlay unless the user explicitly requests appending to an existing mod.
- New actor name, for example `CC_Blacksmith_Hylian_01`.
- Source UMii-compatible TOTK actor to clone. Default to a known standing Hylian UMii NPC such as `Npc_BaseCamp006` when the user only needs a visual test.
- Optional placement Banc path and coordinates. If the user gives a plain-English location, resolve Banc/location first instead of guessing.

Never bake user-specific project paths into this skill. If a conversation gives a preferred destination for a specific character or project, use it only for that task.

## Fast Build Script

Use the bundled script when the request is a straightforward `.bumii` to one TOTK actor overlay:

```powershell
python scripts\build_totk_actor_from_bumii.py `
  --romfs "<vanilla romfs>" `
  --bumii "<character.bumii>" `
  --output "<new output mod folder>" `
  --actor "<NewActorName>" `
  --source-actor "Npc_BaseCamp006"
```

For the established Lookout Landing UMii research test position:

```powershell
python scripts\build_totk_actor_from_bumii.py `
  --romfs "<vanilla romfs>" `
  --bumii "<character.bumii>" `
  --output "<new output mod folder>" `
  --actor "<NewActorName>" `
  --source-actor "Npc_BaseCamp006" `
  --lookout-research-placement
```

For custom placement:

```powershell
python scripts\build_totk_actor_from_bumii.py `
  --romfs "<vanilla romfs>" `
  --bumii "<character.bumii>" `
  --output "<new output mod folder>" `
  --actor "<NewActorName>" `
  --source-actor "Npc_BaseCamp006" `
  --banc "Banc/MainField/E-4_Dynamic.bcett.byml.zs" `
  --translate -265 125.25 -135 `
  --rotate 0 0 0
```

The script writes:

- `romfs/Pack/Actor/<NewActor>.pack.zs`
- `romfs/Component/AIScheduleParam/<NewActor>.game__component__AIScheduleParam.bgyml`
- patched `romfs/RSDB/ActorInfo...rstbl.byml.zs`
- patched `romfs/RSDB/GameActorInfo...rstbl.byml.zs`
- optional patched Banc
- `Codex_Working/build_manifest.json`, converted UMii patch, source AAMP text, and a test card

## Conversion Notes

BOTW `.bumii` exports are AAMP files. Parse with `oead.aamp.ParameterIO.from_binary(...)`, convert to text with `.to_text()`, then load the tagged YAML using constructors for `!io`, `!list`, `!obj`, and `!vec3`.

The main object path is `param_root.objects`. Expected objects include `ffsd`, `body`, `personal`, `common`, `shape`, `hair`, `eye`, `eye_ctrl`, `eyebrow`, `nose`, `mouth`, `beard`, and `glass`.

Core observed mapping:

- `ffsd.no_use_ffsd` -> `Ffsd.NoUseFfsd`
- `ffsd.type`: `0 -> Mii`, `1 -> Random`
- `body.race`: `0 -> Hylia` (other race labels are provisional unless validated)
- `personal.sex_age`: `1 -> M`, `4 -> W`
- `body.type`: `0 -> C`, provisional `1 -> N`, `2 -> O`, `3 -> S`, `4 -> T`, `5 -> U`, `6 -> SB`, `7 -> SK`
- `body.number`: `n -> Number<n>`
- `body.weight`: `0 -> Thin`, `1 -> Standard`, `2 -> Thick`
- `body.height`: `0 -> Standard`, `1 -> high`
- `common.backpack`: `-1 -> TypeNone`, otherwise `Type<n>`
- `common.hat`: `-1 -> None`, otherwise `Type<n>`
- `common.body_correct` and `common.rot_*`: write both `Common.*` and mirrored top-level `BodyCorrect.*`; vanilla records commonly duplicate these values.
- `personal.fav_color`: `n -> Color<n>`
- `personal.sub_color_1/2`: `-1 -> SubColorNone`, otherwise zero-padded `SubColorNN`
- `head_fav_color`, `shoulder_fav_color`, `shoulder_sub_color_1`: `-1 -> ColorNone`, otherwise `Color<n>`
- `personal.personality`: remove underscores where needed, for example `Man_Normal -> ManNormal`
- Face detail sections map directly to TOTK dotted fields: `Shape.*`, `Hair.*`, `Eye.*`, `EyeCtrl.*`, `Eyebrow.*`, `Nose.*`, `Mouth.*`, `Beard.*`, and `Glass.*`

BOTW `personal.voice_type` is parsed and recorded, but do not write it into fixed TOTK UMiiParam unless a live TOTK voice route is confirmed. Current successful builds inherit voice behavior from the source actor.

## Body Build Findings

`Body.Weight` has only three observed TOTK values: `Thin`, `Standard`, and `Thick`. Do not expect a separate `Muscular` or `Strong` weight enum.

For Hylian-style adults, muscular or worker-like silhouettes are mainly from `Body.Type` plus `Body.Number`, with `Common/BodyCorrect` rotations as posture/proportion correction:

- Green/cream suspender outfit seen in blacksmith tests: `Body.Type=C`, `Body.Number=Number6`.
- Blue apron worker/muscular body seen in blacksmith tests: `Body.Type=C`, `Body.Number=Number10`, usually with `Body.Weight=Thick`, `Body.Height=high`, `BodyCorrect=Original`, `RotCravicle=-14`, `RotArm=17`, `RotCrotch=1`, `RotLeg=-2`.
- Broad/stocky Hylian male preset: `Body.Type=T`, `Body.Number=Number5`, `Body.Weight=Thick`, `BodyCorrect=Original`, `RotCravicle=-5`, `RotArm=12`, `RotCrotch=1`, `RotLeg=-2`.

Test result to preserve: cloning from a worker source actor such as `Npc_CafeHylia004` but forcing `Body.Type=C` and `Body.Number=Number6` produced no visible difference from a normal source actor with the same `C/Number6` fields and worker correction. That suggests the source actor family does not contribute hidden muscular silhouette once `Body.Type/Body.Number` are fixed. If a user wants the `Number10` worker body in the `Number6` outfit, UMii parameters alone are probably insufficient; it likely needs model/costume editing.

## Actor Build Rules

The actor pack conversion is:

1. Clone a TOTK UMii-compatible source actor pack.
2. Replace exact source actor strings with the new actor name inside the source `ActorParam`.
3. Set `ActorParam.Components.UMiiRef` to `?Component/UMiiParam/<NewActor>.game__component__UMiiParam.bgyml`.
4. Set `ActorParam.Components.AIScheduleRef` to `?Component/AIScheduleParam/<NewActor>.game__component__AIScheduleParam.bgyml`.
5. Create a new custom UMiiParam member by copying the source UMiiParam and applying converted `.bumii` fields.
6. Write a simple idle AISchedule unless the task needs real schedule behavior.
7. Clone source rows into `ActorInfo` and `GameActorInfo`, replacing the source actor name and setting `ActorInfo.ActorName` to the new actor.
8. Patch a Banc only if placement was requested.

## Placement Rules

Banc `Translate` is `X, Y, Z`:

- `X`: east-west.
- `Y`: altitude/elevation. Validate against nearby surface actors or props; a tolerance around 0.5 m may still visibly float.
- `Z`: north-south. In the HUD compass coordinate display, the middle value is north-south and maps to Banc `Z`, not `Y`.

For the proven Lookout Landing research row near the stairs, use `Banc/MainField/E-4_Dynamic.bcett.byml.zs`, `Translate [-265.0, 125.25, -135.0]`, `Rotate [0, 0, 0]`, facing south. This should be treated as a test position, not a general location resolver.

## Validation

Before reporting success, validate by reopening generated files:

- Actor pack decompresses with `pack.zsdic`.
- New actor member exists and points to the custom UMiiParam and AISchedule refs.
- Custom UMiiParam contains all converted fields.
- AISchedule parses and contains `DefaultSchedule`.
- `ActorInfo` and `GameActorInfo` rows exist for the new actor.
- Optional Banc contains exactly one placement for the new actor with expected coordinates.

For TKMM or stacked overlays, inspect the final merged output if the actor does not spawn. Shared RSDB and Banc files are common collision points.