Unity Physics

Unity Physics

Retrieval Sources

Key Guidelines

Rigidbody & Movement

A Rigidbody hands a GameObject over to the physics solver: once attached (and not isKinematic), gravity, drag, and collision response act on it automatically, and the solver — not your script — is the source of truth for transform.position/rotation after each physics step. All physics-driven writes (AddForce, AddTorque, MovePosition, MoveRotation, reading/writing linearVelocity) belong in FixedUpdate, because the solver advances on a fixed timestep (Time.fixedDeltaTime, default 0.02s / 50Hz) that is decoupled from the variable per-frame Update rate — doing force math in Update makes motion framerate-dependent and non-reproducible across machines. Never assign transform.position directly to a non-kinematic Rigidbody; that snaps the body without going through the solver's velocity integration, causing jitter, tunneling, and missed collision events on the next step. If a Rigidbody must be positioned by external logic (e.g. an animation or a moving platform script) rather than by forces, mark it isKinematic = true and drive it with MovePosition/MoveRotation, which still generates correct collision/trigger events against non-kinematic bodies. Rigidbody.interpolation (None/Interpolate/Extrapolate) smooths the visual transform between fixed-timestep steps for cameras/rendering without affecting the simulation itself — use Interpolate on the player-controlled or camera-followed body and leave everything else None to save cost.

public class ForceMover : MonoBehaviour
{
    [SerializeField] private float thrust = 10f;
    private Rigidbody rb;

    void Awake()
    {
        rb = GetComponent<Rigidbody>();
        rb.interpolation = RigidbodyInterpolation.Interpolate; // smooth visuals only
        rb.collisionDetectionMode = CollisionDetectionMode.ContinuousDynamic; // fast mover vs fast/slow others
    }

    void FixedUpdate()
    {
        Vector3 input = new Vector3(Input.GetAxis("Horizontal"), 0f, Input.GetAxis("Vertical"));
        rb.AddForce(input * thrust, ForceMode.Force); // continuous force, mass-dependent
        // rb.MovePosition(rb.position + input * speed * Time.fixedDeltaTime); // alternative: kinematic-style displacement
    }
}

Colliders & Triggers

A Collider defines the shape used for both physical collision response and trigger detection; it can exist with or without a Rigidbody, but at least one of the two colliding GameObjects in a pair must have a non-kinematic (or kinematic) Rigidbody for Unity to generate any callback at all — two static colliders (no Rigidbody on either) never fire OnCollisionEnter/OnTriggerEnter. isTrigger decides the behavior: with it on, the collider raises OnTriggerEnter/Stay/Exit and never generates a physical response (objects pass through it); with it off, the collider is solid, blocks motion, and raises OnCollisionEnter/Stay/Exit with contact-point/impulse data available via the Collision parameter. Prefer primitive colliders (Box/Sphere/Capsule) for anything that moves — they use analytic collision math and are far cheaper than Mesh Colliders. A MeshCollider is non-convex by default, which means it can only collide with primitive colliders and other convex mesh colliders, never with another non-convex mesh collider, and non-convex mesh colliders cannot be attached to a non-kinematic Rigidbody at all — check convex = true (capped at 255 triangles) if the shape must move or must collide with other meshes. Build complex static or moving shapes out of several primitive colliders on child GameObjects (compound colliders) rather than reaching for a Mesh Collider by default.

public class HazardTrigger : MonoBehaviour
{
    void Awake()
    {
        GetComponent<Collider>().isTrigger = true; // must be true to get OnTrigger* callbacks
    }

    void OnTriggerEnter(Collider other)
    {
        if (other.attachedRigidbody != null && other.CompareTag("Player"))
            Debug.Log("Player entered hazard zone");
    }

    void OnCollisionEnter(Collision collision) // only fires on a non-trigger collider pair
    {
        ContactPoint contact = collision.GetContact(0);
        Debug.Log($"Hit {collision.collider.name} at {contact.point} with impulse {collision.impulse}");
    }
}

Raycasting & Queries

Physics.Raycast and its siblings (RaycastAll, Linecast, SphereCast, BoxCast, CapsuleCast, OverlapSphere, OverlapBox, OverlapCapsule) are the query API for asking "what's out there" without waiting for a collision callback — used for ground checks, line-of-sight, weapon hit detection, and proximity checks. Every overload accepts an optional LayerMask and QueryTriggerInteraction; always pass an explicit LayerMask on any query run every frame (e.g. a ground check) to skip irrelevant colliders (UI hitboxes, VFX-only triggers, etc.) and cut query cost — an unfiltered raycast walks every collider layer in the scene's broad phase. Physics.Raycast returns a bool and fills a RaycastHit only on hit; RaycastAll allocates an array every call and is more expensive, so prefer the non-allocating Physics.RaycastNonAlloc variant in hot loops. Shape casts (SphereCast/BoxCast/CapsuleCast) sweep a volume instead of an infinitely thin line and are the right tool for fast-moving projectiles or characters where a thin raycast could miss thin geometry between frames — they cost more than a plain raycast, so reserve them for cases where tunneling is a real risk. OverlapSphere/OverlapBox test a static volume for overlapping colliders (no direction/distance), useful for "what's near me right now" checks like an explosion radius.

public class GroundCheck : MonoBehaviour
{
    [SerializeField] private LayerMask groundMask; // set in Inspector to only the "Ground" layer
    [SerializeField] private float checkDistance = 0.2f;

    bool IsGrounded()
    {
        Ray ray = new Ray(transform.position, Vector3.down);
        return Physics.Raycast(ray, out RaycastHit hit, checkDistance, groundMask, QueryTriggerInteraction.Ignore);
    }

    void FireHitscanWeapon(Vector3 origin, Vector3 direction, float range)
    {
        if (Physics.SphereCast(origin, 0.1f, direction, out RaycastHit hit, range, groundMask))
            Debug.Log($"Hit {hit.collider.name} at distance {hit.distance}");
    }
}

Layers & Collision Matrix

Physics layers (Project Settings > Tags and Layers) combined with the collision matrix (Project Settings > Physics, the "Layer Collision Matrix" grid) let Unity skip broad-phase collision checks entirely between layer pairs that are unchecked — this is cheaper and more centralized than filtering collisions in OnCollisionEnter/OnTriggerEnter code, because the excluded pairs never even reach the narrow phase. Leaving everything on the Default layer means the matrix can't selectively exclude anything, so assign meaningful layers (Player, Enemy, Ground, Projectile, Trigger-only, etc.) early in a project rather than retrofitting them later. LayerMask values used in scripts are bitmasks, not layer indices — build them with LayerMask.GetMask("Ground", "Wall") rather than hardcoding an index, since layer indices can be reordered by whoever edits the Tags and Layers list. Physics.IgnoreLayerCollision(layerA, layerB, ignore) and Physics.IgnoreCollision(colliderA, colliderB, ignore) can flip collision ignoring at runtime for cases the static matrix can't express (per-instance rather than per-layer), such as temporarily letting a player fall through a specific platform.

public class LayerSetup : MonoBehaviour
{
    [SerializeField] private LayerMask groundAndWallMask;

    void Start()
    {
        // equivalent runtime construction if the mask isn't set in the Inspector
        int mask = LayerMask.GetMask("Ground", "Wall");

        // runtime override of the static collision matrix for one specific pair of colliders
        Collider player = GetComponent<Collider>();
        Collider
        Physics.IgnoreCollision(player, oneWayPlatform, true);
    }
}

Joints

Joints connect two Rigidbodies (or one Rigidbody to a fixed point in world space when connectedBody is left None) and constrain their relative motion instead of letting collision response do it. FixedJoint welds two bodies together but still lets both react individually to breakForce/breakTorque thresholds — useful for objects that should detach when hit hard enough. HingeJoint constrains motion to rotation about a single axis (doors, wheels, pendulums) and exposes a JointMotor for driving that rotation with a target velocity/force, plus optional JointLimits. SpringJoint pulls two bodies toward a target distance with spring/damper forces rather than a hard constraint — good for tethers and soft connections. ConfigurableJoint is the general case: every one of the 6 degrees of freedom (3 linear, 3 angular) is independently set to Free/Limited/Locked, with drive forces (xDrive/angularXDrive/etc.) able to actively motor an axis toward a target — this is how to build anything from a rigid weld (all locked) up to a custom vehicle suspension or a ragdoll limb, and it subsumes what the other joint types do as special cases. CharacterJoint is a ConfigurableJoint preset specialized for ragdoll limbs (twist + swing1/swing2 limits). Use the Ragdoll Wizard for a quick humanoid ragdoll rig; tune RagdollStability guidance (higher solver iterations, mass distribution) if limbs jitter. ArticulationBody/physics-articulations.html is a separate, more numerically stable alternative to Joint-chains for kinematic chains like robot arms or multi-segment ragdolls, and is generally preferred over stacked Joints for long chains because it doesn't accumulate the same soft-constraint drift.

public class DoorHinge : MonoBehaviour
{
    void Awake()
    {
        HingeJoint hinge = gameObject.AddComponent<HingeJoint>();
        hinge.connectedBody = null; // hinges to world space at this GameObject's anchor
        hinge.axis = Vector3.up;
        hinge.useLimits = true;
        hinge.limits = new JointLimits { min = 0f, max = 90f };
        hinge.useMotor = true;
        hinge.motor = new JointMotor { targetVelocity = 90f, force = 50f };
    }
}

2D Physics

2D physics is a separate simulation engine from 3D physics — Rigidbody2D/Collider2D run on Box2D-derived solver, have their own Project Settings > Physics 2D panel and their own collision matrix, and do not interact with Rigidbody/Collider at all. Decide 3D vs 2D per project, not per object. Rigidbody2D.bodyType (Dynamic/Kinematic/Static) replaces the 3D isKinematic bool with an explicit enum. Collider2D shapes cover Box/Circle/Capsule/Edge/Polygon, plus a CompositeCollider2D that merges multiple child colliders (each flagged usedByComposite) into one optimized outline — the standard pattern for tilemap collision. Joint2D types (Distance/Fixed/Hinge/Slider/Spring/Wheel/Relative/Friction/Target) mirror the 3D joint concepts but each ships as its own component rather than one configurable joint. 2D-only effectors (AreaEffector2D, PointEffector2D, PlatformEffector2D, SurfaceEffector2D, BuoyancyEffector2D) apply forces to any Rigidbody2D whose Collider2D has usedByEffector checked — no 3D equivalent exists; PlatformEffector2D in particular implements one-way platforms without runtime layer-ignoring tricks. A lower-level PhysicsWorld2D/PhysicsBody2D job-friendly API sits underneath the classic components for performance-critical, multithreaded 2D physics work (Manual/2d-physics-api/).

public class OneWayPlatform : MonoBehaviour
{
    void Awake()
    {
        var collider = GetComponent<Collider2D>();
        collider.usedByEffector = true;
        var effector = gameObject.AddComponent<PlatformEffector2D>();
        effector.useOneWay = true;
        effector.surfaceArc = 180f; // only collide from above
    }
}

CharacterController vs Rigidbody

CharacterController is a kinematic capsule moved explicitly via Move(Vector3) or SimpleMove(Vector3); it applies its own built-in step-offset and slope-limit handling, reports isGrounded and per-call CollisionFlags, and is not affected by incoming physics forces or pushed by other Rigidbodies — you get precise, jitter-free control at the cost of having to hand-code any push/knockback/platform-riding behavior yourself (typically inside OnControllerColliderHit). A Rigidbody-driven capsule (non-kinematic Rigidbody + CapsuleCollider, moved with AddForce/MovePosition in FixedUpdate) fully integrates with the solver — it can be pushed by explosions, can push other Rigidbodies, and interacts naturally with joints — but is harder to tune for the snappy, deterministic feel players expect from platformer/FPS controllers, since gravity, friction, and drag all fight the intended input. Choose CharacterController for traditional first/third-person controllers where precise, predictable movement matters most; choose a Rigidbody capsule when the character must be part of the physics simulation (rammed by vehicles, knocked back by explosions, ragdolls on death).

public class KinematicPlayer : MonoBehaviour
{
    private CharacterController controller;
    [SerializeField] private float speed = 5f;
    [SerializeField] private float gravity = -9.81f;
    private Vector3 velocity;

    void Awake() => controller = GetComponent<CharacterController>();

    void Update()
    {
        if (controller.isGrounded && velocity.y < 0) velocity.y = -2f; // small stick-to-ground bias
        Vector3 input = new Vector3(Input.GetAxis("Horizontal"), 0, Input.GetAxis("Vertical"));
        controller.Move(input * speed * Time.deltaTime);
        velocity.y += gravity * Time.deltaTime;
        controller.Move(velocity * Time.deltaTime);
    }

    void OnControllerColliderHit(ControllerColliderHit hit)
    {
        if (hit.rigidbody != null && !hit.rigidbody.isKinematic)
            hit.rigidbody.AddForceAtPosition(controller.velocity * 0.1f, hit.point, ForceMode.Impulse); // manual push
    }
}

Common Mistakes

Quick Reference

Advanced Notes

Fixed timestep tuning. Time.fixedDeltaTime (Project Settings > Time > Fixed Timestep) sets how often the solver steps; smaller values give a more accurate simulation at higher CPU cost, larger values are cheaper but coarser (visible as choppier physics motion, especially under interpolation = None). Maximum Allowed Timestep caps how much simulated time a single frame is allowed to catch up on a slow frame — if a frame takes longer than this, Unity runs multiple FixedUpdate steps in a row (a "physics spiral of death" risk if the cap is too high and steps can't keep up); lowering the cap instead skips catching up fully and lets visible time slip. Physics.defaultSolverIterations/Physics-defaultSolverVelocityIterations (or per-Rigidbody solverIterations/solverVelocityIterations) trade CPU for constraint accuracy — raise them for stacks of joints/ragdolls that jitter, lower them for scenes with many simple non-interacting bodies. Set Physics.simulationMode to Script and drive stepping yourself with Physics.Simulate(step) for deterministic lockstep simulation (networked physics, replay systems) instead of relying on Unity's automatic FixedUpdate cadence — see Manual/physics-optimization-cpu-manual-simulation.html.

Static vs dynamic collider cost. Colliders on GameObjects with no Rigidbody are treated as static by the broad phase and are cheap to have many of, but moving a "static" collider's transform at runtime forces an expensive broad-phase rebuild — if a wall or platform needs to move, give it a kinematic Rigidbody rather than just moving its transform, so Unity treats it as dynamic and updates it cheaply instead of re-baking static state every frame (Manual/physics-optimization-cpu-static-colliders.html, Manual/physics-optimization-cpu-transform-sync.html).

Unity Physics / DOTS (alternative stack). Alongside the built-in GameObject/PhysX-backed system this skill otherwise documents, Unity ships a separate Unity.Physics package (Manual/com.unity.physics.html) built for the Entity Component System — burst-compiled, job-safe, and deterministic, aimed at large-scale simulations (thousands of bodies) and DOTS-based projects. It does not share components with Rigidbody/Collider (uses PhysicsVelocity, PhysicsCollider, etc. as ECS components instead) and is a project-level architecture choice, not a drop-in swap — reach for it only if the project is already ECS/DOTS-based or physics performance at GameObject scale has been profiled and found wanting.

Physics Debug window & Profiler. Manual/PhysicsDebugVisualization.html exposes a Physics Debug window (Window > Analysis > Physics Debug) to visualize colliders, contacts, and queries directly in-editor, independent of Gizmos code. The Profiler's dedicated Physics module (Manual/ProfilerPhysics.html) and the 2D-specific Physics 2D Profiler module (Manual/2d-physics/physics-profiler/physics-2d-profiler-module-reference.html) break down solver cost by phase (broad phase, narrow phase, solve, sync-transforms) — use these before guessing which optimization (layer matrix, collider type, solver iterations, sleep thresholds) will actually move the needle.