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`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| references/physics-2d.md | markdown | 4.9 KB |
| references/raycasting-and-joints.md | markdown | 3.4 KB |
references/raycasting-and-joints.md
View on GitHub# Raycasting variants & joints (Unity 6.3 LTS PhysX)
Depth for `unity-physics`. All types are in `UnityEngine`. Verified against
`ScriptReference/Physics` and the joint component pages.
## LayerMask bit math
A `LayerMask` is a 32-bit set of layers. Common constructions:
```csharp
int mask = LayerMask.GetMask("Ground", "Enemy"); // by name (recommended)
int onlyGround = 1 << LayerMask.NameToLayer("Ground"); // single layer by index
int everythingButPlayer = ~(1 << LayerMask.NameToLayer("Player")); // invert
```
`Physics.Raycast(..., layerMask)` tests only layers whose bit is set. To *ignore* triggers
in a cast, pass `QueryTriggerInteraction.Ignore` as the last argument.
## Cast variants
```csharp
// Single nearest hit along a ray.
if (Physics.Raycast(origin, dir, out RaycastHit hit, maxDistance, mask)) { /* hit.point, hit.normal, hit.collider */ }
// Thick ray — good for "can a character-sized body pass?".
if (Physics.SphereCast(origin, radius, dir, out RaycastHit sHit, maxDistance, mask)) { }
// All hits along the ray (unordered) — e.g. shoot-through targets.
RaycastHit[] hits = Physics.RaycastAll(origin, dir, maxDistance, mask);
// Non-allocating versions write into a buffer you own (no GC each call) — prefer in hot paths.
private readonly RaycastHit[] _buffer = new RaycastHit[8];
int count = Physics.RaycastNonAlloc(origin, dir, _buffer, maxDistance, mask);
// Overlap tests (no direction): what is inside this volume right now?
Collider[] inRange = Physics.OverlapSphere(center, radius, mask);
```
Tips:
- `RaycastHit.normal` is the surface normal at the hit — use it to align decals or compute
slope angle (`Vector3.Angle(hit.normal, Vector3.up)`).
- Prefer the `NonAlloc` / buffer overloads in per-frame code to avoid garbage.
- A ray starting *inside* a collider never reports that collider; start the ray outside it.
(`Physics.queriesHitBackfaces` is a different setting: it only lets queries hit back-face
triangles of mesh colliders.)
## Joints
Joints connect two Rigidbodies (or a body to the world if `Connected Body` is empty).
| Joint | Constrains | Typical use |
|-------|-----------|-------------|
| `FixedJoint` | all 6 DOF (rigidly attaches) | weld parts that can break apart |
| `HingeJoint` | rotation about one axis, with motor/limits/spring | doors, wheels, pendulums |
| `SpringJoint` | distance via a spring | bungee, soft tethers |
| `ConfigurableJoint` | any combination of the 6 DOF | custom ragdoll/vehicle constraints |
```csharp
// A motorised hinge (e.g. a powered door).
var hinge = gameObject.AddComponent<HingeJoint>();
hinge.axis = Vector3.up;
hinge.useMotor = true;
hinge.motor = new JointMotor { force = 100f, targetVelocity = 90f /* deg/s */ };
```
### Breakable joints
```csharp
fixedJoint.breakForce = 500f; // newtons before the joint snaps
fixedJoint.breakTorque = 500f;
// When it breaks, the engine calls this on the GameObject:
private void OnJointBreak(float breakForce) => Debug.Log($"Joint broke at {breakForce}");
```
## Gotchas
- Joints simulate in `FixedUpdate`; setting joint properties is fine from `Update` but effects
apply on the next physics step.
- A `ConfigurableJoint`'s locked/limited axes are relative to the joint's initial orientation —
set up the bodies in their rest pose before adding the joint.
- Very stiff joints + high mass ratios are unstable; increase `Default Solver Iterations`
(Project Settings → Physics) before fighting it with bigger forces.
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 |