Guide Masking Cleanup

Guide: Clean up holes and poke-through with masking

Goal: finished item sprites with no holes cut by the body, no body showing through the item, and the item correctly hidden where the body is in front of it (a far bracer behind the torso, a backpack behind the chest).

Reference: Fit Lab, Blender Build Pipeline, and the design note body occlusion.

How masking works

Two separate things decide what the body does to an item sprite:

	What it does	Where you set it
Holdout (occlusion)	The complete, animated, invisible body hides any item pixel it is in front of. The body never appears in the item image.	Body masking in a correction: Clothing (default), Attachment, or No body masking
Hide body under clothes	Removes body faces that sit just under the item from the fitting body, so they can't poke through. The invisible holdout body stays complete.	Hide body under this slot, Outward, Inward on the Fit tab

The occlusion modes:

Mode (saved value)	Use for	Behaviour
Clothing: limbs/head (clothing)	garments, armour, gloves, boots, helms	the item may sit a little inside its own body region (up to the slot's Inward distance) without being cut; any other region (torso, the opposite limb) still hides it
Attachment: whole body (body)	back items, quivers (their default), anything that must never sink into the body	only the renderer's normal depth margin; no allowance
No body masking (none)	debugging, or items that must always draw on top	no body masking at all

Left and right stay distinct: a left bracer gets no allowance from the right arm.

Prerequisites

• The slot open in Fit Lab, as in Fit a slot in Fit Lab.
• A first Blender render of the item (Render tab or the Blender render pane) so you can compare.

Steps

1. See the problem

Under Slot previews turn on Poke pixels. Magenta pixels are body pixels showing through the item. Switch Base to Item only to see just the item's cutout, as the sprite will be exported. In the Blender render pane, switch off UO body to look at the rendered item layer alone.

Typical symptoms:

Symptom	Likely cause
Magenta spots on the item in the preview	body faces under the item poke through; hiding is off or too tight
Holes or bites in the rendered item	the body is in front of the item there: the item sits too deep
Skin visible at wrists, neck or ankles where it should be covered	Outward is too small, or the item is too loose
Gaps where the body should show (neck, wrists)	hiding too much: Outward or Inward too large
A back item or far limb drawn over the torso	body masking is off, or the item is offset forward into the body

2. Hide the body under the slot

On the Fit tab, under Hide body under clothes, turn on Hide body under this slot (on by default for garments and the CC0 starters). Then tune:

• Outward (0–8 cm): body faces up to this far outside the item are hidden. Raise it when skin pokes through a loose garment.
• Inward (0–5 cm): body faces up to this far inside the item are hidden. It is also the allowance that clothing occlusion gives the item in its own body region.

Turn on Hidden faces to see the hidden faces in red; use 2×2 to check front, side and back together. The counter next to the timeline shows how many body faces are hidden in the current pose.

3. Measure

On the Measure tab, tick the animations to check and click Measure slot. Compare with your baseline: the counts should fall. They run high by design (the renderer's 1 cm holdout margin and 6 mm push-out aren't modelled), so compare runs rather than reading them as absolutes.

4. Pick the occlusion mode, only where needed

Most slots are right with the default. To change it, open Corrections, choose Apply to (item, slot, group or pack) and When (all poses, one animation, one direction, or both), then set Body masking. Inherit keeps the slot's mode. Examples:

• A cape that must stay behind the torso in every facing: slot, all poses, Attachment.
• A shield that clips into the forearm in one swing: item, that animation, Clothing, plus a small offset.

5. Fix deep penetration with fit, not masking

If the item is cut in the render, the body really is in front of it. More hiding won't help; the holdout body is always complete. Move the item out: Offset, Front/back depth for torso shells, or a scoped correction for the one pose that fails.

6. Confirm in the render

Click Render animation (or Rebuild changed blocks on the Render tab). Check the frames, with UO body off, for holes, then the Sprite sheet for every facing. Old renders keep the masking they were built with; new rules need a fresh build.

Expected output

• The slot's hide_body (enabled, outward, inward) and any occlusion corrections saved in lab-adjustments.json.
• Fewer poke pixels on the Measure tab than the baseline.
• Rendered frames with no holes, the far limb hidden behind the torso, and the near limb in front.

Common mistakes

• Using No body masking to make holes go away. It also lets the item draw over the torso and far limbs. Fix the fit.
• Raising Inward until the holes close. Inward is a small tolerance (5 cm at most), not a fix for an item sunk into the body.
• Expecting Hide body to change the holdout. It changes the fitting body only; the invisible body that masks the render is always complete.
• Trusting the preview mask. The live preview approximates the holdout (1 cm margin, no push-out, no edge correction). The Blender render is the final word.
• Mixing old and new masking. Renderer fingerprints include the occlusion code; a rebuild refuses to mix them. Build fresh.

Region masks are a different thing

games/ultima-online/region-masks holds a research experiment that labels body regions on the original client sprites. It needs your own client data, stays in the ignored workspace, and is not used by the render masking above.