unity-3d-math

3D Math & Spatial Reasoning -- Correctness Patterns

Prerequisite skills: unity-scripting (Vector3/Quaternion API), unity-foundations (Transform, GameObjects), unity-physics (raycasting basics)

These patterns target the most dangerous Claude failure mode: plausible-looking math that compiles but produces wrong results. Each pattern documents Claude's default mistake and the correct Unity approach.

---

PATTERN: Coordinate Space -- TransformPoint vs TransformDirection

WHEN: Converting between local and world space

WRONG (Claude default):

// Using TransformDirection for a position offset
Vector3 worldPos = transform.TransformDirection(localOffset);

RIGHT:

// Positions: TransformPoint (applies position + rotation + scale)
Vector3 worldPos = transform.TransformPoint(localOffset);

// Directions: TransformDirection (applies rotation only, ignores scale)
Vector3 worldDir = transform.TransformDirection(localDir);

// Vectors: TransformVector (applies rotation + scale, no position)
Vector3 worldVec = transform.TransformVector(localVec);

GOTCHA: TransformDirection ignores scale -- if the parent has non-uniform scale and you need the direction scaled, use TransformVector. For the inverse operations, use InverseTransformPoint, InverseTransformDirection, InverseTransformVector.

---

PATTERN: Quaternion Multiplication Order

WHEN: Combining rotations (e.g., applying a local rotation on top of a world rotation)

WRONG (Claude default):

// "First rotate by A, then rotate by B"
transform.rotation = rotA * rotB; // Actually applies B first, then A

RIGHT:

// Quaternion multiplication applies RIGHT operand first
// "Apply B in A's space" = A * B
// Parent-then-child: parent * child
transform.rotation = worldRotation * localRotation;

// Example: rotate 45 degrees around Y, then tilt 30 degrees around local X
Quaternion yaw = Quaternion.AngleAxis(45f, Vector3.up);
Quaternion pitch = Quaternion.AngleAxis(30f, Vector3.right);
transform.rotation = yaw * pitch; // yaw is applied in world, pitch in yaw's local space