Unity Physics (Rigidbody / PhysX)

Make objects move, collide, and detect each other with Unity 6.3 LTS's built-in 3D physics (PhysX). Get the FixedUpdate discipline, trigger-vs-collision rules, and collision layers right. Targets Unity 6.3 LTS (6000.3).

Unity 6 renames: Rigidbody.velocity → linearVelocity, drag → linearDamping, angularDrag → angularDamping. The old names still compile in 6.3 LTS but are obsolete (warnings; the API Updater offers the rename), so write the new names. PhysicMaterial → PhysicsMaterial is a hard compile error in old code.

When to use

• Use when giving an object physical motion (forces, velocity, gravity), responding to collisions or triggers, setting up collision layers/masks, raycasting for ground checks or line-of-sight, or connecting bodies with joints.
• Use when scenes/prefabs contain Rigidbody + Collider components.

When not to use: 2D physics (Rigidbody2D, Collider2D) is a separate API — adapt the concepts but the types differ. Unity 6.3 also has a separate low-level 2D API (UnityEngine.LowLevelPhysics2D: PhysicsWorld, PhysicsBody) with its own isolated worlds; it is not the Rigidbody2D system. Cross-engine feel tuning (timestep, jitter, tunnelling) → physics-tuning. Reading input that drives movement → unity-input-system.

Core workflow

1. Add a Rigidbody to anything that should be simulated; add a Collider to anything that should be hit. OnCollision* messages need a Collider on both and at least one dynamic (non-kinematic) Rigidbody: with the default Contact Pairs Mode, kinematic vs kinematic and kinematic vs static send no collision messages.
2. Do all physics in FixedUpdate. Read input in Update, store intent, then apply forces / set linearVelocity / call MovePosition in FixedUpdate.
3. Move bodies through the physics API, not the Transform. Use AddForce, linearVelocity, or MovePosition — never assign transform.position to a non-kinematic Rigidbody (it teleports and breaks collision resolution).
4. Pick collision vs trigger. A solid collision blocks and calls OnCollisionEnter; a Collider with Is Trigger checked passes through and calls OnTriggerEnter.
5. Organise interactions with layers. Put objects on layers and edit the Layer Collision Matrix (Project Settings → Physics) so unrelated things don't test against each other.
6. Verify with the Physics Debugger (Window → Analysis → Physics Debugger) and by watching for jitter; if fast objects pass through walls, raise Collision Detection mode.

Patterns

1. Force-based movement in FixedUpdate (with a speed clamp)

using UnityEngine;

[RequireComponent(typeof(Rigidbody))]
public class Mover : MonoBehaviour
{
    [SerializeField] private float accel = 30f, maxSpeed = 8f;
    private Rigidbody _rb;
    private Vector3 _input;   // set from Update / input system

    private void Awake() => _rb = GetComponent<Rigidbody>();

    private void FixedUpdate()
    {
        _rb.AddForce(_input * accel, ForceMode.Acceleration);     // mass-independent accel
        // Unity 6.3 LTS: linearVelocity (was 'velocity'). Clamp horizontal speed.
        Vector3 flat = new(_rb.linearVelocity.x, 0, _rb.linearVelocity.z);
        if (flat.magnitude > maxSpeed)
        {
            flat = flat.normalized * maxSpeed;
            _rb.linearVelocity = new Vector3(flat.x, _rb.linearVelocity.y, flat.z);
        }
    }
}

ForceMode: Force (continuous, mass-scaled), Acceleration (continuous, ignores mass), Impulse (instant, mass-scaled — jumps), VelocityChange (instant, ignores mass).

2. Collision vs trigger callbacks

// Solid hit: both have colliders, at least one has a dynamic (non-kinematic) Rigidbody.
private void OnCollisionEnter(Collision col)
{
    // GetContact avoids the garbage that the col.contacts array allocates.
    Debug.Log($"Hit {col.gameObject.name} at {col.GetContact(0).point}");
}

// Overlap: one collider has 'Is Trigger' = true, and at least one party has a Rigidbody
// (or a Rigidbody carries the trigger). Two static colliders never report.
private void OnTriggerEnter(Collider other)
{
    if (other.CompareTag("Pickup")) Destroy(other.gameObject);
}

3. Ground check with a layer-masked raycast

[SerializeField] private LayerMask groundMask;   // set to your "Ground" layer in the Inspector

private bool IsGrounded()
{
    // Cast a short ray down; only test colliders on groundMask.
    return Physics.Raycast(transform.position, Vector3.down, out RaycastHit hit,
                           1.1f, groundMask);
}

4. Kinematic platform that still pushes bodies

// isKinematic Rigidbody: not driven by forces, but MovePosition interpolates and carries
// resting bodies correctly (unlike moving the Transform directly).
private void FixedUpdate() => _rb.MovePosition(_rb.position + Vector3.right * (2f * Time.fixedDeltaTime));

Pitfalls

• Obsolete warnings on velocity / drag / angularDrag — Unity 6 renamed them to linearVelocity, linearDamping and angularDamping (angularVelocity is unchanged). Let the API Updater rename them or edit by hand; PhysicMaterial must become PhysicsMaterial.
• Setting transform.position on a dynamic Rigidbody — teleports it, skips collision.