roblox3dskill(ihateaistill)

---
name: "roblox"
description: "roblox anim"
---

# roblox3d — Skill: Math, CFrame Spaces, and Procedural Rigging That Runs Correctly

> **Type:** skill.md
> **Language:** Luau (Roblox)
> **Origin:** Derived from a forensic postmortem of broken procedural R6/R15 joint animators, matrix decomposition errors, and inverted object-space camera scripts that caused limb detachment, gimbal lock, and viewport inversion.

---

## 1. The Prime Directive of 3D Spaces

**You cannot add or multiply 3D vectors and matrices based on how they read. You must trace the coordinate spaces.**

A 3D engine does not care about your aesthetic intent. If you multiply a local rotation matrix on the wrong side of an offset transformation, the joint will orbit the wrong origin, components will decouple, and characters will deform.

Every transformation has a designated home: **World Space**, **Object Space**, or **Joint-Local Space**. Mixing them up without explicit translation is a critical math bug.

---

## 2. Matrix Composition Rules (Non-Negotiable)

### 2.1 CFrame Multiplication is NOT Commutative ($A \times B \neq B \times A$)
The order in which you multiply `CFrame` values dictates the axis and origin of the rotation.

```lua
-- ❌ WRONG: Rotates the joint around the PARENT's axis (Torso alignment)
-- Result: Arm detaches, orbits the stomach, or shears wildly when the torso moves.
motor.C0 = restC0 * CFrame.new(offset) * CFrame.Angles(x, y, z)

-- ✅ CORRECT: Rotates the joint around its OWN local socket pivot point
-- Result: Limbs rotate naturally inside their shoulder/hip sockets.
motor.C0 = restC0 * CFrame.Angles(x, y, z) * CFrame.new(offset)
```
**The Rule:** To transform an object along its **local axes**, multiply the modification `CFrame` to the **right** of the original base (`Base * LocalTransform`). To transform an object along **world/parent axes**, multiply the modification `CFrame` to the **left** (`WorldTransform * Base`).

### 2.2 Never assume identical axes across different rig joints
An angle that represents a "forward tilt" on a head does not mean "forward tilt" on a shoulder. In the standard Roblox R6/R15 configuration, joints are welded with distinct base orientations:
* **Shoulders (Left/Right):** The default primary lifting axis is the local **Z-axis** (bringing the arm from the hip up to the sky). Side-to-side waving occurs along the local **X-axis** once raised.
* **Neck:** The local **X-axis** dictates pitch (looking up/down), the **Y-axis** dictates yaw (looking left/right), and the **Z-axis** dictates roll (tilting the head sideways).

**The Rule:** Run a physical diagnostic or use your eyes in Studio to map the exact joint rotation before writing keyframe tables. Never copy-paste `CFrame.Angles` parameters from an arm to a leg or a head expecting the same visual output.

---

## 3. Computational Geometry & Viewport Rules

### 3.1 Clamp camera pitch explicitly to prevent Viewport Inversion
When implementing custom 3D orbit, vehicle, or camera inspection systems, tracking mouse movements across raw Euler angles will cause the camera to flip upside down, invert left/right controls, and induce **Gimbal Lock** if it passes a vertical pole.

```lua
-- ❌ WRONG: Unclamped Euler accumulators cause gimbal flips at the poles
cameraRotation = cameraRotation * CFrame.Angles(mouseDelta.Y, mouseDelta.X, 0)

-- ✅ CORRECT: Track raw scalar angles, clamp pitch, and construct cleanly
local maxPitch = math.rad(88) -- Prevent reaching exact vertical 90 degrees
currentPitch = math.clamp(currentPitch - mouseDelta.Y, -maxPitch, maxPitch)
currentYaw = currentYaw - mouseDelta.X

camera.CFrame = CFrame.new(targetPosition)
                * CFrame.Angles(0, currentYaw, 0)
                * CFrame.Angles(currentPitch, 0, 0)
                * CFrame.new(0, 0, zoomDistance)
```

### 3.2 Roblox Grip Welds assume spatial inversion (The Wrist Trap)
When scripting tools, visual attachments, or custom weapon grips, remember:
* In modeling suites like **Blender**, characters stand upright on the **+Z axis**, and tools are traditionally modeled pointing upward along **+Y**.
* In **Roblox**, the engine's internal `RightGrip` weld forces a hardcoded $-\frac{\pi}{2}$ ($90^\circ$) pitch at the hand socket, assuming items extend outward along the **-Z axis**.

**The Rule:** When bridging raw assets between Blender and Luau procedural code, you must inject an explicit compensation matrix (`CFrame.Angles(math.rad(-90), 0, 0)`) to re-align tool geometries to the hand container.

---

## 4. Performance & Lifecycle Invariants

### 4.1 Frame updates must carry explicit death plans
Any script manipulating raw `Motor6D.C0`, `Camera.CFrame`, or structural 3D vectors via high-frequency event connections (`RenderStepped`, `Heartbeat`) will leak processing memory and crash threads if it is not unlinked when instances are cleared.

```lua
-- ✅ Ensure loop lifecycle terminates when character resets or object is destroyed
local connection
connection = RunService.Heartbeat:Connect(function(dt)
    if not character:IsDescendantOf(workspace) or not humanoid or humanoid.Health <= 0 then
        connection:Disconnect()
        return
    end
    -- Apply 3D math here safely
end)
```

### 4.2 Cache rest states once; never read structural states on the hot path
Reading properties like `Motor6D.Transform`, `Joint.C0`, or spatial parameters from the data model inside an frame loop triggers an implicit execution cost, causing serious physics engine lag.

* **Pure Data Rule:** Cache the original `RestC0` states into memory **once** at script startup. Use your mathematical adjustments against the stored data table, and push the calculations to the instances *exactly once per frame*.

### 4.3 * **Hips vs. Shoulders Inversion:** Hip joints are mirrored relative to shoulders on standard rigs. Applying identical angular modifications (`CFrame.Angles`) to both will cause legs to cross over or invert. Always invert the roll/yaw sign or map hip pitch to the opposing local axis coordinate.

---

## 5. Summary Mechanical Checklist

- [ ] **Pivot Order:** Verify custom joint angles are multiplied before translations (`Rest * Angles * Offset`).
- [ ] **Axis Validation:** Explicitly test if `X`, `Y`, or `Z` drives the intended movement for that specific joint before hardcoding interpolation tables.
- [ ] **Gimbal Protection:** Check that camera pitch trackers are strictly clamped between roughly $-88^\circ$ and $+88^\circ$ to prevent viewport flipping.
- [ ] **Clean Disposal:** Ensure all frame loops feature a verification check that disconnects the engine sequence when the player or rig leaves the active workspace tree.