CharacterController Usage

BeastCharacterGroundAlignment is the current Creature Kit integration for applications that move a Beast with Unity's CharacterController.

Requirements

The controller GameObject needs:

• a generated Beast with a reachable BeastStructure;
• BeastCharacterGroundAlignment;
• a Unity CharacterController on the same GameObject;
• walkable colliders assigned to a dedicated ground layer;
• an application movement script that calls the public ground-alignment methods.

BeastCharacterGroundAlignment requires a CharacterController, so Unity adds one automatically when necessary.

Inspector Setup

1. Select the GameObject that owns Beast movement.
2. Add BeastCharacterGroundAlignment.
3. Assign Beast Structure if it was not resolved automatically.
4. Create a Unity layer for walkable terrain and ground colliders.
5. Assign those colliders to the layer.
6. Select only the intended ground layers in Ground Alignment Layer Mask.
7. Leave Fit Controller On Start enabled for the initial setup.
8. Enter Play Mode and use the debug gizmos to verify every external-foot ray reaches the intended collider.

An empty Layer Mask cannot resolve a ground normal. A collider that is visible but not included in the selected mask is ignored.

Ground Alignment Settings

Setting	Purpose
Align To Ground Slope	Enables ground sampling, velocity projection, and visual slope alignment.
Ground Alignment Layer Mask	Restricts ground raycasts to walkable terrain and ground colliders.
Ground Probe Start Height	Raises each downward ray origin above its generated foot contact.
Ground Probe Distance	Requests the downward distance from the elevated origin. Runtime extends it when necessary to cover the start height, half the controller height, and controller skin.
Ground Align Smoothing	Controls how quickly the resolved ground-up direction follows normal changes. Zero applies the new direction immediately.
Max Ground Tilt Angle	Limits the visual inclination relative to world up.

External Foot Contacts

Beast generation creates a GroundContact transform at the theoretical bottom center of every foot. The contact follows the animated Foot; runtime sampling reads that transform directly and does not recalculate renderer bounds.

The component selects at most four contacts:

• a Beast with one leg pair uses its left and right feet;
• a Beast with two or more leg pairs uses the left and right feet from the front and rear pairs;
• feet from intermediate pairs are not sampled because rigid body alignment cannot solve their contacts independently.

One successful impact is sufficient. With two impacts, the contact line contributes to the inclination. Three or four impacts define a support plane. When every active foot probe misses briefly, the last valid ground orientation is preserved. For contact diagnosis, enable Log Missing Ground Warnings in Ground Debug; it logs one warning after a continuous 0.5-second miss, reports configuration errors immediately, and is disabled by default.

Controller Fit Settings

Setting	Purpose
Fit Controller On Start	Fits the capsule from the generated Body and Legs render bounds when the component starts.
Disable Beast Colliders On Start	Disables colliders inside the generated Beast hierarchy so the CharacterController remains the movement collider.
Controller Skin	Adds clearance around the fitted support bounds.

Use the component context menu command Fit Controller To Beast after changing or rebuilding Beast proportions when the controller must be fitted again.

Runtime Call Order

A typical movement loop performs these operations in order:

1. Resolve the desired horizontal velocity.
2. Update airborne gravity owned by the application.
3. Call GetDesiredGroundUp.
4. When grounded, call ProjectVelocityOnGround.
5. Move the CharacterController.
6. Call RotateControllerTowards to update upright yaw.
7. Call AlignVisualToGround to incline the generated Beast visual.
8. Optionally call DrawGroundProbeDebugLines in Play Mode.

using CreatureKit.Beasts;
using UnityEngine;

[RequireComponent(typeof(BeastCharacterGroundAlignment))]
public sealed class BeastGroundMovementExample : MonoBehaviour
{
    [SerializeField] private float movementSpeed = 4f;
    [SerializeField] private float rotationSpeed = 360f;

    private BeastCharacterGroundAlignment groundAlignment;
    private float verticalVelocity;

    private void Awake()
    {
        groundAlignment = GetComponent<BeastCharacterGroundAlignment>();
    }

    private void Update()
    {
        CharacterController controller = groundAlignment.Controller;
        if (controller == null)
            return;

        Vector2 input = new Vector2(Input.GetAxisRaw("Horizontal"), Input.GetAxisRaw("Vertical"));
        Vector3 horizontalVelocity = new Vector3(input.x, 0f, input.y).normalized * movementSpeed;

        if (controller.isGrounded && verticalVelocity < 0f)
            verticalVelocity = -1f;
        verticalVelocity += Physics.gravity.y * Time.deltaTime;

        Vector3 groundUp = groundAlignment.GetDesiredGroundUp(Time.deltaTime);
        bool followsGround = controller.isGrounded;
        Vector3 groundVelocity = followsGround
            ? groundAlignment.ProjectVelocityOnGround(horizontalVelocity, groundUp)
            : horizontalVelocity;

        Vector3 gravityVelocity = Vector3.up * verticalVelocity;

        controller.Move((groundVelocity + gravityVelocity) * Time.deltaTime);
        groundAlignment.RotateControllerTowards(horizontalVelocity, rotationSpeed, Time.deltaTime);
        groundAlignment.AlignVisualToGround(horizontalVelocity, groundUp, rotationSpeed, Time.deltaTime);
        groundAlignment.DrawGroundProbeDebugLines();
    }
}

Gravity remains vertical while only locomotion is projected onto the sampled ground plane. Avoid applying contact pressure along -groundUp: on a slope that vector contains a horizontal uphill component that can affect CharacterController movement.

The example uses Unity's legacy input API only to keep the movement sequence compact. Input System, AI, navigation, and other application controllers can produce the same horizontal velocity.

Disabling The Component

Disabling BeastCharacterGroundAlignment restores the generated visual root to its recorded rest pose and clears the smoothed ground state. The application remains responsible for deciding whether movement should continue without slope support.