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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Nice-Wolf-Studio/unity-claude-skills --skill unity-3d-math技能说明
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