Index of every page on this site: llms.txt
All skills
Run it yourself

Unity 6.3 LTS physics in 3D and 2D: Rigidbody and Rigidbody2D, forces and linearVelocity, the layer collision matrix and raycasts. Use when an object falls through the floor, OnTriggerEnter never fires, or a ground ray hits the player. Not for engine-neutral tunnelling tuning (`physics-tuning`), tilemap colliders (`unity-tilemap-2d`) or NavMesh (`unity-navmesh`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/unity-physics

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈95 tokens for metadata: the name and description. ≈3.1k when used: this file. ≈2.1k more on demand in 2 files.

Description uses 4.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈381 characters, or 4.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Unity Physics (3D PhysX and 2D)

Make objects move, collide and detect each other in Unity 6.3 LTS (6000.3). Unity has two separate physics engines: 3D (Rigidbody, Collider, Physics) and 2D (Rigidbody2D, Collider2D, Physics2D). They never interact: a Rigidbody2D falls straight through a BoxCollider, and 3D callbacks never fire on 2D objects.

When to use

  • Giving an object physical motion, responding to collisions or triggers, setting up layers, ray or shape casts for ground checks and line of sight, joints, kinematic movers.
  • The project's scenes or prefabs contain Rigidbody/Collider or Rigidbody2D/Collider2D.

When not to use: cross-engine feel (fixed timestep choice, jitter strategy, tunnelling trade-offs) → physics-tuning; Tilemap Collider 2D and composite merging → unity-tilemap-2d; pathfinding agents → unity-navmesh; reading the input that drives movement → unity-input-system. If Unity's official fix-3d-physics-collisions or create-2d-physics skill is installed and an Editor is connected, it can drive the Editor for scene setup; this skill still owns the API and the code.

Workflow

  1. Find out which engine the object uses before touching code. Grep the scene or prefab YAML for a Rigidbody2D: or Rigidbody: document header (and BoxCollider2D: vs BoxCollider:). Mixed 2D and 3D components on interacting objects are a bug, not a design.
  2. Read the physics settings as text, not through the Inspector. 3D settings live in ProjectSettings/DynamicsManager.asset (m_QueriesHitTriggers, m_ContactPairsMode, m_LayerCollisionMatrix), 2D settings in ProjectSettings/Physics2DSettings.asset (m_QueriesHitTriggers, m_QueriesStartInColliders, m_SimulationMode, m_LayerCollisionMatrix). The matrix is a hex bitfield: read and change it with Physics.GetIgnoreLayerCollision/IgnoreLayerCollision (2D: the Physics2D versions) rather than editing the hex.
  3. Do physics in FixedUpdate. Read input in Update, store intent, apply forces or set linearVelocity or call MovePosition in FixedUpdate. Both engines step after FixedUpdate by default.
  4. Move bodies through the physics API, not the Transform. AddForce, linearVelocity, MovePosition. Writing transform.position on a dynamic body teleports it and skips collision resolution.
  5. Pick collision vs trigger. A solid collider blocks and calls OnCollisionEnter (OnCollisionEnter2D); isTrigger passes through and calls OnTriggerEnter (OnTriggerEnter2D). At least one of the pair needs a rigidbody.
  6. Prune layer pairs that never need to touch. A runtime IgnoreLayerCollision call is not saved; for a lasting change ask the user to untick the pair in Project Settings > Physics (or Physics 2D) > Layer Collision Matrix, or for 3D use the Unity CLI's settings.physics set command, which asks for confirmation.
  7. Verify with one of the checks below, then remove any temporary logging.

Patterns

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

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
        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 and Acceleration are continuous (mass-scaled vs not); Impulse and VelocityChange are instant (mass-scaled vs not; use them for jumps).

2. Ground check that ignores triggers (3D)

[SerializeField] private LayerMask groundMask;   // only the Ground layer

private bool IsGrounded() =>
    Physics.Raycast(transform.position, Vector3.down, out RaycastHit _, 1.1f,
                    groundMask, QueryTriggerInteraction.Ignore);

3. Kinematic platform that carries resting bodies (3D)

// isKinematic Rigidbody: MovePosition moves it through the solver, so bodies on top ride along.
private void FixedUpdate() =>
    _rb.MovePosition(_rb.position + Vector3.right * (2f * Time.fixedDeltaTime));

2D physics (Rigidbody2D)

Same rules, different types. The traps a 3D habit walks into:

3D 2D equivalent Difference that bites
Rigidbody.isKinematic Rigidbody2D.bodyType (Dynamic, Kinematic, Static) Rigidbody2D.isKinematic is obsolete; set bodyType
OnCollisionEnter(Collision) OnCollisionEnter2D(Collision2D) a 3D-named method on a 2D object never runs, with no error
OnTriggerEnter(Collider) OnTriggerEnter2D(Collider2D) same
Physics.Raycast → bool + out RaycastHit Physics2D.Raycast → RaycastHit2D test if (hit) or hit.collider != null
ray starting inside a collider misses it Physics2D.queriesStartInColliders is on by default a ground ray cast from the player's centre hits the player itself
RaycastNonAlloc Physics2D.Raycast(origin, dir, contactFilter, results, distance) the 2D *NonAlloc methods are deprecated in Unity 6
Vector3 angularVelocity (rad/s) float angularVelocity (degrees/s) unit change

For a kinematic 2D character, Rigidbody2D.Slide moves the body along surfaces with gravity and slope limits, which saves writing your own cast-and-slide loop. Patterns for the ground check with a ContactFilter2D, one-way platforms and Slide are in references/physics-2d.md.

Verify

Pick the first path that is available and say which one you used.

  • Unity CLI with a ready Editor (unity status --project-path <project> reports ready): run unity recompile --project-path <project> for compile errors, then read the state back instead of eyeballing it, for example unity command script eval --code 'return Physics2D.GetIgnoreLayerCollision(LayerMask.NameToLayer("Player"), LayerMask.NameToLayer("Enemy"));' or a body's bodyType, collisionDetectionMode and linearVelocity after a few seconds of Play mode (unity command editor.playmode start). Commands change between CLI releases: find the current name with unity command --query <word> and its flags with --help.
  • PlayMode test, with or without the CLI: build the case in code (a floor, a falling body, yield return new WaitForSeconds(1f), assert the body rests above the floor or the callback count is 1). Run it with unity test <project> --mode PlayMode, or without the CLI in batch mode: -batchmode -projectPath <project> -runTests -testPlatform PlayMode -testResults <file> (no -quit; the test runner exits by itself). Read the NUnit XML, not just the exit code. Test-assembly setup is in unity-csharp-scripting.
  • Feel or visual only: ask the user to enter Play mode and report a number (does the crate rest at y ≈ 1, how many OnCollisionEnter logs per hit).

Gotchas

  • OnCollisionEnter never fires on a CharacterController. Move bypasses the rigidbody system and reports through OnControllerColliderHit. Adding a Rigidbody does not fix it; the two are separate movement modes.
  • Trigger callbacks never fire. One of the two colliders needs a rigidbody (2D: a Rigidbody2D, and simulated on), and both colliders must be enabled. Two static colliders never report.
  • No collision messages between two kinematic bodies, or kinematic vs static. With the default 3D Contact Pairs Mode Unity only reports when one body is dynamic. Make one dynamic, use a trigger, or change Contact Pairs Mode. In 2D, turn on useFullKinematicContacts on the kinematic Rigidbody2D.
  • A ground or line-of-sight ray stops on a trigger volume. Queries hit triggers by default in both engines. Pass QueryTriggerInteraction.Ignore (3D) or a ContactFilter2D with useTriggers = false (2D), or turn off Queries Hit Triggers.
  • 2D ground check is always true. The ray starts inside the player's own collider and queriesStartInColliders returns it. Exclude the player's layer from the mask, or start the ray just below the collider.
  • Obsolete warnings on velocity, drag, angularDrag. Unity 6 renamed them linearVelocity, linearDamping, angularDamping in both 3D and 2D (2D also has linearVelocityX/Y). They still compile with warnings; PhysicMaterial → PhysicsMaterial is a hard error.
  • Setting transform.position on a dynamic body. It teleports and skips collision. If you do write the Transform, queries see the old position until the next step; call Physics.SyncTransforms() (2D: Physics2D.SyncTransforms()) once before a same-frame query.
  • A resting body hangs in mid-air after its floor moves. Sleeping bodies wake on collisions and forces, but a static collider moved by its Transform may not wake them. Call WakeUp(). A collider that moves every frame should get a kinematic rigidbody instead of staying static.
  • Fast objects pass through walls. Raise Collision Detection from Discrete. 3D Continuous sweeps only against static colliders; Continuous Dynamic also against other continuous dynamic bodies; Continuous Speculative against everything and cheaper. 2D has CollisionDetectionMode2D.Continuous. For bullets, a cast along the path is often better.
  • A concave MeshCollider on a moving body. Concave mesh colliders can only be static or kinematic, and two concave colliders never collide. Enable Convex or build a compound collider from primitives, and keep scale uniform.
  • Part of a compound body drifts away. A compound collider has one rigidbody, on the root. An extra rigidbody on a child makes it a separate body.
  • Nothing moves, raycasts still hit. Time.timeScale = 0 stops the simulation; queries still read collider geometry. In 2D also check Physics2D.simulationMode: with Script, nothing moves until you call Physics2D.Simulate.

References

  • Read references/physics-2d.md when writing 2D movement, ground checks, one-way platforms or kinematic Slide controllers.
  • Read references/raycasting-and-joints.md when you need 3D cast variants (SphereCast, RaycastAll, OverlapSphere, non-allocating buffers), LayerMask bit math or 3D joints.

Related skills

  • physics-tuning: engine-neutral feel, timestep, mass ratios, stability.
  • unity-csharp-scripting: the FixedUpdate/Update split, test assemblies, the .meta checker.
  • unity-tilemap-2d: tilemap colliders and composite colliders.
  • unity-navmesh: agent movement that is not force-driven.

Version notes

Last verified: 2026-11-11, against Unity 6000.3.28f1 (latest 6.3 LTS patch).

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    This skill provides best practices, C# code snippets, and verification workflows for Unity 6.3 LTS physics. It references official Unity resources and uses standard CLI commands for project interaction.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/unity-physics