/physics

name: physics
description: "Unity physics — non-allocating queries, collision layers, FixedUpdate discipline, continuous collision detection, character controllers, joints."
globs: ["**/*Physics*.cs", "**/*Collider*.cs", "**/*Rigidbody*.cs", "**/*Trigger*.cs"]

Physics System

FixedUpdate Discipline

All physics code goes in `FixedUpdate`. Input reading happens in `InputView.Update` (see architecture rules) and is forwarded to the System, which applies forces in `FixedUpdate` from the cached value.

// InputView.cs — reads input in Update, forwards to System
private void Update()
{
    Vector2 moveInput = _controls.Player.Move.ReadValue<Vector2>();
    _playerSystem.SetMoveInput(moveInput);
}

// PlayerView.cs — applies physics in FixedUpdate from System-owned cached input
private Vector2 _moveInput;

public void SetMoveInput(Vector2 input) => _moveInput = input;

private void FixedUpdate()
{
    _rigidbody.AddForce(_moveInput * _force);
}

Non-Allocating Queries

// Pre-allocate buffers
private static readonly RaycastHit[] _hitBuffer = new RaycastHit[16];
private static readonly Collider[] _overlapBuffer = new Collider[32];

// Raycast
int hitCount = Physics.RaycastNonAlloc(origin, direction, _hitBuffer, maxDistance, layerMask);
for (int i = 0; i < hitCount; i++)
{
    RaycastHit hit = _hitBuffer[i];
    // Process hit
}

// Overlap sphere (area detection)
int overlapCount = Physics.OverlapSphereNonAlloc(center, radius, _overlapBuffer, layerMask);

// Sphere cast (fat raycast)
int castCount = Physics.SphereCastNonAlloc(origin, radius, direction, _hitBuffer, maxDistance, layerMask);

Layer Collision Matrix

// Ignore collisions between layers programmatically
Physics.IgnoreLayerCollision(playerLayer, pickupLayer, true);

// Or configure in Edit > Project Settings > Physics > Layer Collision Matrix

Layer organization:

6: Player
7: Ground
8: Enemy
9: Projectile
10: Trigger (no physics collision, triggers only)
11: Interactable

Collision Detection Modes

| Mode | Use When | |------|----------| | Discrete | Slow objects (default) | | Continuous | Fast objects that might tunnel through thin colliders | | Continuous Dynamic | Fast objects colliding with other fast objects | | Continuous Speculative | Good balance of accuracy and performance |

Collision vs Trigger Callbacks

// Collision (both have colliders, at least one has Rigidbody, neither is trigger)
private void OnCollisionEnter(Collision collision) { }
private void OnCollisionStay(Collision collision) { }
private void OnCollisionExit(Collision collision) { }

// Trigger (at least one collider has isTrigger = true)
private void OnTriggerEnter(Collider other) { }
private void OnTriggerStay(Collider other) { }
private void OnTriggerExit(Collider other) { }

Physics.SyncTransforms

After moving a transform directly, physics queries won't reflect the new position until the next physics step. Force sync:

transform.position = newPosition;
Physics.SyncTransforms(); // Now raycasts see the new position

Rigidbody Configuration

• **Interpolation:** `Interpolate` for player (smooths between physics steps), `None` for others
• **Constraints:** Freeze rotation for 2D-like behavior in 3D
• **Collision Detection:** Continuous for fast-moving objects

2D Physics Equivalents

| 3D | 2D | |----|-----| | `Rigidbody` | `Rigidbody2D` | | `BoxCollider` | `BoxCollider2D` | | `Physics.Raycast` | `Physics2D.Raycast` | | `Physics.OverlapSphereNonAlloc` | `Physics2D.OverlapCircleNonAlloc` | | `OnCollisionEnter(Collision)` | `OnCollisionEnter2D(Collision2D)` | | `OnTriggerEnter(Collider)` | `OnTriggerEnter2D(Collider2D)` |

Joints

| Joint | Use | |-------|-----| | Fixed | Weld objects together | | Hinge | Doors, wheels | | Spring | Bouncy connections | | Configurable | Full control over all axes | | Character | Character controller with physics |