Debugging Ground Alignment

The Ground Debug section exposes independent views for the controller fit, raycasts, and sampled normals. It also provides optional missing-ground warnings.

Click the ? button beside the section title to expand the complete color and marker guide in the inspector. This guide remains usable in Play Mode, where normal Unity tooltips may not appear.

Debug Switches

Inspector switch	Serialized field	Display
Draw Body + Legs Center	drawSupportCenterGizmo	Orange sphere and cross at the support center used to fit the controller.
Draw External Foot Raycasts	drawFootGroundProbeGizmos	Rays anchored to the generated external-foot contacts, successful-hit guide, and forward arrow.
Draw Ground Normals	drawGroundProbeNormals	Yellow raw normals, magenta resolved normals, and the green blended alignment normal.
Log Missing Ground Warnings	logMissingGroundWarnings	Logs sampling failures. Active probe misses require 0.5 seconds; configuration errors are immediate. Disabled by default.

Ground Normal Debug Length changes only the displayed normal length. It does not change sampling or alignment.

Four external-foot raycasts, their cyan support polygon and the normals displayed in the Unity debug view.

Reading Markers

• Cyan ray: the probe hit a collider in the selected ground layers.
• Cyan cross below a foot: its generated GroundContact position.
• Cyan cross above a foot: the elevated ray origin.
• White cross: the exact successful ground hit.
• Red ray and cross: no valid collider was hit before the configured distance ended.
• Open support-guide edge: one of the adjacent external-foot probes missed.
• Front Left Foot, Front Right Foot, Rear Right Foot, and Rear Left Foot: Scene View labels for a Beast with at least two leg pairs.
• Left Foot and Right Foot: Scene View labels for a one-pair Beast.
• Cyan arrow: the Beast's forward direction.

In Game View, enable the Unity Gizmos button. Direction labels are available in Scene View only.

Nothing Is Displayed

Check the following:

1. The relevant debug switch is enabled.
2. Align To Ground Slope is enabled for ray and normal views.
3. The Unity Scene or Game View Gizmos button is enabled.
4. The component and its GameObject are enabled.
5. The application calls DrawGroundProbeDebugLines every frame when Play Mode Debug.DrawLine output is required.

Draw Body + Legs Center can display independently of slope alignment.

Every Ray Is Red

Verify Ground Alignment Layer Mask first. The terrain collider must be assigned to a layer included in that mask.

Then verify the vertical range:

• Ground Probe Start Height must place the ray origin above the intended ground;
• Ground Probe Distance must cover both the start height and the remaining gap to the ground;
• very large or elevated Beasts may need a larger distance.

The ray origin and endpoint crosses show whether the failure comes from an incorrect origin or an insufficient distance.

Foot Probes Do Not Match The Stance

Enable Draw External Foot Raycasts and inspect the contact crosses, forward arrow, and foot labels.

Each ray is anchored to a generated GroundContact below the corresponding Foot. A Beast with one leg pair has two active probes. A Beast with more pairs still has only four: the front and rear left/right feet. Intermediate feet intentionally have no alignment ray.

After rebuilding or substantially reshaping a Beast, use Fit Controller To Beast and inspect the support center again.

During Walk, Rush, or another leg animation, a contact follows its animated foot. Temporary misses are therefore possible. The last valid orientation is retained. Enable Log Missing Ground Warnings when diagnosing contacts: one warning appears only when every active probe misses continuously for at least 0.5 seconds, and a valid impact rearms it. Configuration errors such as an empty Layer Mask or missing generated contacts are reported immediately. The option is disabled by default to keep normal animation misses out of the Console.

The Beast Floats Or Sinks On Slopes

Enable these views together:

1. Draw Body + Legs Center to verify that decorative parts do not shift the fitted center.
2. Draw External Foot Raycasts to verify the sampled support feet.
3. Draw Ground Normals to compare raw, resolved, and blended normals.

Test the same Beast on flat ground, moving uphill, and moving downhill. Direction-dependent floating often indicates an incorrect rotation center or support sample. Constant vertical error is more likely to come from controller fitting, generated foot height, or another movement script applying an additional offset.

Long necks, heads, and tails are excluded from the support center. A Cowraffe should therefore retain the same locomotion center whether its neck is enabled or disabled.

Normal Lines Disagree

This can be expected:

• yellow shows the collider hit normal;
• magenta can use an interpolated Terrain or readable Mesh normal;
• green combines the available samples into the direction used for alignment.

For a MeshCollider, enable Read/Write on the source mesh when interpolated vertex normals are required. Otherwise the component falls back to the collider hit normal.

Release Builds

Disable debug switches when they are no longer needed. They are diagnostic views and should not be part of the normal application presentation.