Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

unity-3d-math

Unity 3D math correctness patterns. Catches common mistakes with coordinate spaces, Quaternion, Vector3, Plane, Bounds, Transform hierarchies, raycasting projection, and floating-point precision. PATTERN format: WHEN/WRONG/RIGHT/GOTCHA. Based on Unity 6.3 LTS documentation.

Nice-Wolf-Studio · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add Nice-Wolf-Studio/unity-claude-skills --skill unity-3d-math

About this skill


name: unity-3d-math description: > Unity 3D math correctness patterns. Catches common mistakes with coordinate spaces, Quaternion, Vector3, Plane, Bounds, Transform hierarchies, raycasting projection, and floating-point precision. PATTERN format: WHEN/WRONG/RIGHT/GOTCHA. Based on Unity 6.3 LTS documentation. globs:

  • "**/*.cs"

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

GOTCHA: This is the opposite of matrix multiplication reading order. If you think "first A then B", write A * B -- the right operand is applied in the left operand's local space.


PATTERN: Euler Angle Interpolation (Gimbal Lock)

WHEN: Smoothly rotating between two orientations

WRONG (Claude default):

// Interpolating euler angles directly
Vector3 currentEuler = Vector3.Lerp(startEuler, endEuler, t);
transform.eulerAngles = currentEuler;

RIGHT:

// Always interpolate quaternions, never euler angles
transform.rotation = Quaternion.Slerp(startRot, endRot, t);

// For small angles where performance matters, Lerp is acceptable
transform.rotation = Quaternion.Lerp(startRot, endRot, t); // Slightly faster, less accurate for large arcs

GOTCHA: Euler angles suffer from gimbal lock at 90-degree pitch and have discontinuities (e.g., 359 to 1 degree jumps through 358 degrees instead of 2). Quaternion.Slerp always takes the shortest path. Use Quaternion.Lerp only when the angular difference is small (< 45 degrees).


PATTERN: Quaternion.LookRotation Zero Vector

WHEN: Rotating an object to face a target direction

WRONG (Claude default):

Vector3 dir = target.position - transform.position;
transform.rotation = Quaternion.LookRotation(dir);

RIGHT:

Vector3 dir = target.position - transform.position;
if (dir.sqrMagnitude > 0.0001f) // Guard against zero/near-zero vector
{
    transform.rotation = Quaternion.LookRotation(dir, Vector3.up);
}

GOTCHA: LookRotation(Vector3.zero) produces NaN quaternion that silently corrupts the transform. The forward parameter does not need to be normalized (Unity normalizes internally), but it MUST be non-zero. Also fails if forward is exactly parallel to up -- the second parameter defaults to Vector3.up, which breaks if the target is directly above/below.


PATTERN: Never Modify Quaternion Components Directly

WHEN: Trying to zero out or modify a specific rotation axis

WRONG (Claude default):

// "Remove the X rotation"
Quaternion rot = transform.rotation;
rot.x = 0f;
transform.rotation = rot;

RIGHT:

// Extract euler, modify, rebuild
Vector3 euler = transform.eulerAngles;
euler.x = 0f;
transform.rotation = Quaternion.Euler(euler);

// Or use Quaternion factory methods
// Keep only Y rotation:
transform.rotation = Quaternion.Euler(0f, transform.eulerAngles.y, 0f);

GOTCHA: Quaternion x/y/z/w are NOT euler angles. They are components of a 4D unit quaternion. Setting .x = 0 produces a non-unit quaternion with undefined behavior. Always use factory methods: Quaternion.Euler(), Quaternion.AngleAxis(), Quaternion.LookRotation().


PATTERN: Float Comparison

WHEN: Comparing positions, distances, or any floating-point values

WRONG (Claude default):

if (transform.position == targetPosition) { /* arrived */ }
if (distance == 0f) { /* overlapping */ }

RIGHT:

// For positions: use sqrMagnitude with epsilon
if ((transform.position - targetPosition).sqrMagnitude < 0.0001f) { /* arrived */ }

// For single floats: use Mathf.Approximately
if (Mathf.Approximately(distance, 0f)) { /* close enough */ }

// For custom tolerance:
const float epsilon = 0.01f;
if (Mathf.Abs(a - b) < epsilon) { /* within tolerance */ }

GOTCHA: Vector3 == Vector3 in Unity does use an approximate comparison internally (epsilon ~1e-5), but it is often too tight for gameplay logic. Use explicit thresholds matching your

Read the complete source ↗