gamedev-skills/awesome-gamedev-agent-skills / skills/unity/unity-physics
unity-physics
VerifiedUnity 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`).
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/ColliderorRigidbody2D/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
- Find out which engine the object uses before touching code. Grep the scene or prefab
YAML for a
Rigidbody2D:orRigidbody:document header (andBoxCollider2D:vsBoxCollider:). Mixed 2D and 3D components on interacting objects are a bug, not a design. - 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 inProjectSettings/Physics2DSettings.asset(m_QueriesHitTriggers,m_QueriesStartInColliders,m_SimulationMode,m_LayerCollisionMatrix). The matrix is a hex bitfield: read and change it withPhysics.GetIgnoreLayerCollision/IgnoreLayerCollision(2D: thePhysics2Dversions) rather than editing the hex. - Do physics in
FixedUpdate. Read input inUpdate, store intent, apply forces or setlinearVelocityor callMovePositioninFixedUpdate. Both engines step afterFixedUpdateby default. - Move bodies through the physics API, not the Transform.
AddForce,linearVelocity,MovePosition. Writingtransform.positionon a dynamic body teleports it and skips collision resolution. - Pick collision vs trigger. A solid collider blocks and calls
OnCollisionEnter(OnCollisionEnter2D);isTriggerpasses through and callsOnTriggerEnter(OnTriggerEnter2D). At least one of the pair needs a rigidbody. - Prune layer pairs that never need to touch. A runtime
IgnoreLayerCollisioncall 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'ssettings.physics setcommand, which asks for confirmation. - 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>reportsready): rununity recompile --project-path <project>for compile errors, then read the state back instead of eyeballing it, for exampleunity command script eval --code 'return Physics2D.GetIgnoreLayerCollision(LayerMask.NameToLayer("Player"), LayerMask.NameToLayer("Enemy"));'or a body'sbodyType,collisionDetectionModeandlinearVelocityafter a few seconds of Play mode (unity command editor.playmode start). Commands change between CLI releases: find the current name withunity 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 withunity 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 inunity-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
OnCollisionEnterlogs per hit).
Gotchas
OnCollisionEnternever fires on aCharacterController.Movebypasses the rigidbody system and reports throughOnControllerColliderHit. 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, andsimulatedon), 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
useFullKinematicContactson the kinematicRigidbody2D. - 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 aContactFilter2DwithuseTriggers = false(2D), or turn off Queries Hit Triggers. - 2D ground check is always true. The ray starts inside the player's own collider and
queriesStartInCollidersreturns 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 themlinearVelocity,linearDamping,angularDampingin both 3D and 2D (2D also haslinearVelocityX/Y). They still compile with warnings;PhysicMaterial→PhysicsMaterialis a hard error. - Setting
transform.positionon a dynamic body. It teleports and skips collision. If you do write the Transform, queries see the old position until the next step; callPhysics.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. 3DContinuoussweeps only against static colliders;Continuous Dynamicalso against other continuous dynamic bodies;Continuous Speculativeagainst everything and cheaper. 2D hasCollisionDetectionMode2D.Continuous. For bullets, a cast along the path is often better. - A concave
MeshCollideron 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 = 0stops the simulation; queries still read collider geometry. In 2D also checkPhysics2D.simulationMode: withScript, nothing moves until you callPhysics2D.Simulate.
References
- Read
references/physics-2d.mdwhen writing 2D movement, ground checks, one-way platforms or kinematicSlidecontrollers. - Read
references/raycasting-and-joints.mdwhen you need 3D cast variants (SphereCast,RaycastAll,OverlapSphere, non-allocating buffers),LayerMaskbit math or 3D joints.
Related skills
physics-tuning: engine-neutral feel, timestep, mass ratios, stability.unity-csharp-scripting: theFixedUpdate/Updatesplit, test assemblies, the.metachecker.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).
- Unity 6 renames (3D and 2D
velocity/drag/angularDrag,Rigidbody2D.isKinematic, the 2D*NonAllocqueries,Physics2D.OverlapCollider→Overlap) are obsolete warnings with an API Updater path in 6.3;PhysicMaterialis an error. Source: Unity C# reference source at tag 6000.3.28f1,Modules/Physics/ScriptBindings/*.deprecated.csandModules/Physics2D/ScriptBindings/Physics2D.deprecated.cs(https://github.com/Unity-Technologies/UnityCsReference/tree/6000.3.28f1). - Unity 6.3 also ships a separate low-level 2D API,
UnityEngine.LowLevelPhysics2D(PhysicsWorld,PhysicsBody), with its own worlds; it is not theRigidbody2Dsystem. Unity 6.5 renamed it Physics Core 2D, namespaceUnity.U2D.Physics. Use it only when the project already does. - Unity CLI 1.0.0-beta.17 (2026-11-05) and the
com.unity.pipelinepackage 1.0.0-pre.1 (2026-11-10) are pre-release; command names can change. https://docs.unity.com/en-us/unity-cli and https://docs.unity3d.com/Packages/com.unity.pipeline@1.0/manual/index.html - Manual: https://docs.unity.com/en-us/engine/6000.3/manual/unity-editor/editor-settings-reference/comp-manager-group/class-physics2dsettings
and Scripting API pages for
Rigidbody2D,Physics2D,Rigidbody,Physics.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |