Body Culling and Mask Painter

Body Culling, Equipment Occlusion Layers, and Mask Painter

This guide explains how Character Creator hides body triangles under equipped clothing, and how equipment items can cull each other using occlusion layers.

What It Does

Body culling hides parts of the body mesh that should not be visible under equipment (dress, armor, suit, etc.).

Equipment occlusion layers let higher-layer equipment auto-hide triangles on lower-layer equipment (e.g. a jacket hides the shirt underneath).

Both features are handled by:

• RuntimeBodyOcclusionCuller at runtime

  • 
• Body Culling Mode on each EquipmentPrefab entry

• Equipment Occlusion Layer on each EquipmentPrefab entry

• optional authored masks via the unified Mask Painter (body culling + equipment culling in one tool)

Culling Modes per Equipment Item

In EquipmentManager -> Equipment Prefabs -> Body Culling Mode, each item can use:

• No Culling

  • this equipment does not hide any body triangles

• Manual Culling

  • only triangles painted in the Body Culling Mask Painter are hidden

• Auto Culling

  • RuntimeBodyOcclusionCuller auto-detects covered body triangles

When an item is set to Manual Culling and no RuntimeBodyOcclusionCuller is found on the character, a warning help box appears in the inspector.

Equipment Occlusion Layer

Each equipment item has an Equipment Occlusion Layer (integer, 0...10):

• 0 = this item is not cullable by other equipment (default)

• 1...10 = this item can be culled by equipment on a higher layer

A higher-layer item automatically hides triangles on lower-layer items that it covers at runtime.

Example layer assignment:

Layer	Equipment
1	Underwear
2	Shirt
3	Jacket
4	Armor

In this setup, the jacket (layer 3) will auto-hide covered triangles on the shirt (layer 2) and underwear (layer 1). The armor (layer 4) will auto-hide all lower layers.

Items on layer 0 are never culled by other equipment. Items on the same layer do not cull each other ... only higher layers cull lower ones.

You can also manually paint equipment culling masks using the Equipment Culling tab in the Mask Painter (see below).

Requirements

1. RuntimeBodyOcclusionCuller must exist on the character root.

2. RuntimeBodyOcclusionCuller.bodyRenderer must reference the character body SkinnedMeshRenderer.

3. The source body mesh must be Read/Write enabled in import settings.

If the body mesh is not readable, runtime culling is skipped and a warning is logged.

One-Click Setup

Use: Tools/Character Creator/Character Creator Setup Wizard

Recommended options:

• Add RuntimeBodyOcclusionCuller = enabled

• Auto Enable Source Mesh Read/Write = enabled

  • 

The wizard auto-configures references for RuntimeBodyOcclusionCuller.

Manual Mask Authoring (Painter)

1. In EquipmentManager, set an equipment entry to Body Culling Mode = Manual Culling.

2. Click Open Body & Equipment Culling Painter.

The painter opens a draggable hotbar in the Scene view (can be repositioned by dragging the title bar).

When the selected equipment item has an Equipment Occlusion Layer > 0, the painter shows two mode tabs at the top: Body Culling and Equipment Culling. When the layer is 0, only the Body Culling tab is shown.

Body Culling Tab ... Hotbar Layout

Row	Element	Description
Title	☰ Body Culling: [Slot] [EquipmentName]	Title bar with ✕ close button
1	Start Painting / Stop Painting	Toggles paint mode (green highlight when active). Saves mask data on stop.
1	Clear Mask	Removes all painted triangles for this item.
1	Triangle Count	Shows current masked triangle count (e.g. 42 tris). Displays * suffix when there are unsaved changes.
2	Target (optional)	Dropdown shown when multiple body renderers exist, to pick which body mesh you paint.
3	Brush	Slider controlling brush radius (0.002...0.2).
4	Symmetry	Toolbar: None, Horizontal, Vertical for axis-synced mirrored painting.
5	Paint Through (Front + Back)	Checkbox. Paints through along the brush ray, not only the front-facing hit.
6	Draw Mask Overlay	Checkbox. Draws painted triangles in Scene view (transparent orange fill + orange edges).
7	Preview Culled Result	Checkbox. Shows a live mesh preview of what the body looks like after culling.
8	Ghost Equipment Preview	Checkbox. Overlays the selected equipment as a semi-transparent preview while painting.
9	Ghost Opacity	Slider (0.05...0.9, default 0.28). Only visible when Ghost Equipment Preview is enabled.
10	Scene Hints	Context hints for current mode (paint, paint through, or preview active).
11	Close Painter	Full-width button to close the painter.

Equipment Culling Tab ... Hotbar Layout

This tab is available when the selected item has Equipment Occlusion Layer > 0. It lets you paint which triangles this item hides on lower-layer equipment.

Row	Element	Description
Title	☰ Equipment Culling: [Slot] [EquipmentName]	Title bar with ✕ close button
1	Mode Tabs	Body Culling | Equipment Culling tab toggle
2	Target	Dropdown to select which lower-layer equipment to paint on. Format: [L#] [Slot] PrefabName. Lists both equipped and configured items on lower layers.
3	Mesh (optional)	Dropdown shown only when the target has multiple SkinnedMeshRenderers.
4	Start Painting / Stop Painting	Toggles paint mode (green highlight when active). Also Clear Mask and triangle count.
5	Brush	Slider controlling brush radius (0.002...0.2).
6	Symmetry	Toolbar: None, Horizontal, Vertical.
7	Paint Through (Front + Back)	Checkbox. Paints through to back-facing triangles along the brush ray.
8	Draw Mask Overlay	Checkbox. Draws painted triangles in Scene view.
9	Preview Culled Result	Checkbox. Shows a live mesh preview of the target with the painted mask applied.
10	Ghost Occluder	Checkbox. Overlays the occluder (this item) as a semi-transparent cyan ghost so you can see through it while painting.
10a	↳ Opacity	Slider (0.05...0.9). Only visible when the ghost is enabled.
11	Ghost Target	Checkbox. Overlays the target (lower-layer item) as a semi-transparent violet ghost.
11a	↳ Opacity	Slider (0.05...0.9). Only visible when the ghost is enabled.
12	Scene Hints	Context hints for current mode.
13	Close Painter	Full-width button to close the painter.

Painting Controls

• LMB drag ... paints masked triangles (green brush disc)

• Shift + LMB drag ... erases masked triangles (red brush disc)

• Brush radius adjustable via the Brush slider

• Symmetry = Horizontal/Vertical mirrors your stroke across the selected axis

• Paint Through (Front + Back) paints through front and back hits along the ray

• Undo/Redo is recorded per brush stroke

• Mask data auto-saves when Stop Painting is clicked (large masks with >3000 triangles save asynchronously)

Preview Culled Result

• Preview Culled Result temporarily shows a generated preview mesh with the current mask applied.

• While preview is enabled, paint interactions are disabled.

• Disabling preview restores normal body mesh display.

• If you were painting before enabling preview, painting mode is restored automatically when preview is turned off.

Auto + Manual Hybrid Workflow

You can combine both:

• keep equipment in Auto Culling

• paint a mask while temporarily in Manual Culling

• switch back to Auto Culling

• keep RuntimeBodyOcclusionCuller.useManualMasksWhenAvailable enabled

Result: authored mask is applied on top of auto detection.

Runtime Tuning (Auto Culling)

Tune these fields in RuntimeBodyOcclusionCuller:

Rebuild Settings

Field	Default	Description
autoRebuildOnEquipmentChanged	true	Rebuild when equipment is equipped/unequipped
autoRebuildOnBodyBlendshapeChanges	true	Rebuild when body blendshapes change
bodyBlendshapePollInterval	0.2	How often (seconds) to poll for blendshape changes (min 0.02)
autoRebuildContinuously	false	Rebuild every frame (performance cost)
continuousRebuildInterval	0.4	Interval (seconds) for continuous rebuild (min 0.05)
rebuildDebounceSeconds	0.05	Debounce delay before rebuild is triggered (min 0)

Occlusion Heuristics

Field	Default	Description
insideDistanceEpsilon	0.0005	Distance epsilon for determining if a vertex is inside equipment
surfaceDistanceThreshold	0.006	Max distance to consider a body vertex "covered"
vertexNormalRaycastDistance	0.035	How far to cast along vertex normal to find equipment surface (min 0.001)
vertexNormalRaycastBackstep	0.003	Backstep before raycasting along normal
vertexCoverageProbeRadius	0.015	Radius for coverage probe sphere (min 0.001)
vertexCoverageProbeCount	8	Number of probes per vertex (4...20)
vertexCoverageHitRatio	0.65	Fraction of probes that must hit equipment to consider vertex covered (0.1...1.0)
requiredOccludedVerticesPerTriangle	2	How many of a triangle's 3 vertices must be occluded to hide it (1...3)
autoRelaxTriangleRequirementWhenNoHits	true	Automatically relaxes the per-triangle requirement when no triangles pass the strict check

Other

Field	Default	Description
useManualMasksWhenAvailable	true	Use authored masks on top of auto detection
ignoredSlots	[Hair, Face]	Slots excluded from culling
logDiagnostics	false	Log debug info during culling

Quick direction:

• if too many triangles are hidden: increase strictness (for example higher requiredOccludedVerticesPerTriangle, higher vertexCoverageHitRatio)

• if clipping remains: relax strictness (for example lower requiredOccludedVerticesPerTriangle, lower vertexCoverageHitRatio, increase surfaceDistanceThreshold)

Performance Notes

• Manual Culling is usually cheaper than Auto Culling.

• Auto Culling can rebuild on:

  • equipment change

  • body blendshape change

  • optional continuous rebuild

• Use rebuildDebounceSeconds and bodyBlendshapePollInterval to avoid unnecessary rebuilds.

• Use ignoredSlots to skip categories like Hair and Face.

Troubleshooting

Problem	Likely Cause	Fix
Nothing gets culled	Missing RuntimeBodyOcclusionCuller or missing body renderer reference	Add/configure RuntimeBodyOcclusionCuller on character root
Runtime warning about unreadable body mesh	Source body mesh import has Read/Write disabled	Enable Read/Write (or use Setup Wizard auto-enable option)
Open Body & Equipment Culling Painter button not visible	Item is not in Manual Culling mode	Set item Body Culling Mode to Manual Culling
Equipment Culling tab not shown in painter	Equipment Occlusion Layer is 0	Set Equipment Occlusion Layer to 1 or higher
Equipment-on-equipment culling not working at runtime	Target layer is 0, or target is on same/higher layer	Ensure target has a lower non-zero layer than the occluder
No lower-layer targets in the Equipment Culling target dropdown	No other equipment items have a lower occlusion layer	Assign layers to equipment items so lower-layer items exist
Warning about missing RuntimeBodyOcclusionCuller in inspector	Component not on character	Add RuntimeBodyOcclusionCuller to character root (or use Setup Wizard)
Painter suddenly does not paint	Preview Culled Result is enabled	Disable Preview Culled Result to return to paint mode
Mirror painting not happening	Symmetry is set to None	Set Symmetry to Horizontal or Vertical
Auto culling hides too much	Heuristics too aggressive	Tighten thresholds / increase requiredOccludedVerticesPerTriangle / increase vertexCoverageHitRatio / use manual mask
Auto culling misses clipping	Heuristics too conservative	Relax thresholds / lower requiredOccludedVerticesPerTriangle / increase surfaceDistanceThreshold / add manual mask

Related Files

• Assets/Arawn/CrystalCharacterCreator/Runtime/RuntimeBodyOcclusionCuller.cs

• Assets/Arawn/CrystalCharacterCreator/Runtime/EquipmentManager.cs

• Assets/Arawn/CrystalCharacterCreator/Editor/EquipmentPrefabDrawer.cs

• Assets/Arawn/CrystalCharacterCreator/Editor/EquipmentManagerEditor.cs

• Assets/Arawn/CrystalCharacterCreator/Editor/EquipmentCullingMaskPainter.cs

• Assets/Arawn/CrystalCharacterCreator/Editor/CharacterCreatorSetupWizard.cs