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:

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:

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:

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.