claude-code-arcane 2.9.7 → 2.9.9

package/skills/shader-dev/techniques/voxel-rendering.md

@@ -26,31 +26,31 @@ precision highp float;
 uniform float iTime;
 uniform vec2 iResolution;
 
-// IMPORTANT: Important: WebGL2 must declare the output variable!
+// WebGL2 must declare the output variable.
 out vec4 fragColor;
 
 // ... other functions ...
 
 void main() {
-    // IMPORTANT: Use gl_FragCoord.xy instead of fragCoord
+    // Use gl_FragCoord.xy instead of fragCoord
     vec2 fragCoord = gl_FragCoord.xy;
 
     vec3 col = vec3(0.0);
 
     // ... rendering logic ...
 
-    // IMPORTANT: Write to fragColor, not gl_FragColor!
+    // Write to fragColor, not gl_FragColor!
     fragColor = vec4(col, 1.0);
 }`;
 ```
 
-**IMPORTANT: Common GLSL compile errors:**
+**Common GLSL compile errors:**
 - `in/out storage qualifier supported in GLSL ES 3.00 only` → Check that you are using `getContext("webgl2")` and `#version 300 es`
 - `#version directive must occur on the first line` → Check that the shader string starts with #version, with no characters before it
 - **IMPORTANT: GLSL reserved words**: `cast`, `class`, `template`, `namespace`, `union`, `enum`, `typedef`, `sizeof`, `input`, `output`, `filter`, `image`, `sampler`, `fixed`, `volatile`, `public`, `static`, `extern`, `external`, `interface`, `long`, `short`, `double`, `half`, `unsigned`, `superp`, `inline`, `noinline`, etc. are all GLSL reserved words and **must never be used as variable or function names**! Common pitfall: naming a function `cast` for ray casting → compile failure. **Use compound names like `castRay`, `castShadow`, `shootRay` instead**.
-- **IMPORTANT: GLSL strict typing**: float/int cannot be mixed. `if (x > 0)` for int, `if (y < 0.0)` for float. Comparing ivec3 members to float requires explicit conversion: `float(c.y) < height`. When getVoxel returns int, compare with `> 0` not `> 0.0`. Function parameter types must match exactly.
-- **IMPORTANT: Vector dimension mismatch (vec2 vs vec3)**: `p.xz` returns `vec2` and **must never** be added to `vec3` or passed to functions expecting `vec3` parameters (e.g., `fbm(vec3)`, `noise(vec3)`)! Common error: `fbm(p.xz * 0.08 + vec3(...))` — `vec2 + vec3` compile failure. **Fix**: either use a `vec2` version of noise/fbm, or construct a full vec3: `fbm(vec3(p.xz * 0.08, p.y * 0.05))`. Similarly, `vec2` only has `.x`/`.y`, cannot access `.z`/`.w`.
-- **IMPORTANT: length() / floating-point precision**: `length(ivec2)` must first convert to `vec2`: `length(vec2(d))`. Exact floating-point equality comparison almost never works; use range comparison: `floor(p.y) == floor(height)`
+- **GLSL strict typing**: float/int cannot be mixed. `if (x > 0)` for int, `if (y < 0.0)` for float. Comparing ivec3 members to float requires explicit conversion: `float(c.y) < height`. When getVoxel returns int, compare with `> 0` not `> 0.0`. Function parameter types must match exactly.
+- **Vector dimension mismatch (vec2 vs vec3)**: `p.xz` returns `vec2` and **must never** be added to `vec3` or passed to functions expecting `vec3` parameters (e.g., `fbm(vec3)`, `noise(vec3)`)! Common error: `fbm(p.xz * 0.08 + vec3(...))` — `vec2 + vec3` compile failure. **Fix**: either use a `vec2` version of noise/fbm, or construct a full vec3: `fbm(vec3(p.xz * 0.08, p.y * 0.05))`. Similarly, `vec2` only has `.x`/`.y`, cannot access `.z`/`.w`.
+- **length() / floating-point precision**: `length(ivec2)` must first convert to `vec2`: `length(vec2(d))`. Exact floating-point equality comparison almost never works; use range comparison: `floor(p.y) == floor(height)`
 
 # Voxel Rendering Skill
 
@@ -120,7 +120,7 @@ mapPos += mask * rayStep;
 ### Step 4: Voxel Occupancy Function
 ```glsl
 // Basic version: solid block (most common; use this when user asks for "voxel cube")
-// IMPORTANT: Important: getVoxel receives ivec3, but all internal calculations must use float!
+// getVoxel receives ivec3, but all internal calculations must use float!
 bool getVoxel(ivec3 c) {
     vec3 p = vec3(c) + vec3(0.5);  // ivec3 → vec3 conversion (required!)
     float d = sdBox(p, vec3(6.0));  // Solid 12x12x12 cube
@@ -135,8 +135,8 @@ bool getVoxelCarved(ivec3 c) {
 }
 
 // Advanced version: height map terrain with material IDs
-// IMPORTANT: Key: all comparisons must use float! c.y is int and must be converted to float for comparison
-// IMPORTANT: Important: must use range comparison, not exact equality (floating-point precision issues)
+// all comparisons must use float! c.y is int and must be converted to float for comparison
+// must use range comparison, not exact equality (floating-point precision issues)
 int getVoxelMaterial(ivec3 c) {
     vec3 p = vec3(c);  // ivec3 → vec3 conversion (required!)
     float groundHeight = getTerrainHeight(p.xz);  // p.xz is vec2, passes float parameters
@@ -148,7 +148,7 @@ int getVoxelMaterial(ivec3 c) {
 // Pure float version (simpler, recommended):
 int getVoxelMaterial(vec3 c) {
     float groundHeight = getTerrainHeight(c.xz);
-    // IMPORTANT: Use range comparison, never exact equality!
+    // Use range comparison, never exact equality!
     if (c.y >= groundHeight && c.y < groundHeight + 1.0) return 1;  // Grass top layer
     if (c.y >= groundHeight - 3.0 && c.y < groundHeight) return 2; // Dirt layer
     if (c.y < groundHeight - 3.0) return 3;  // Stone layer
@@ -156,30 +156,30 @@ int getVoxelMaterial(vec3 c) {
 }
 
 // Advanced version: mountain terrain (height-based coloring: grass green → rock gray → snow white)
-// IMPORTANT: Key 1: color thresholds must be based on heightRatio (normalized height 0~1), not absolute height!
-// IMPORTANT: Key 2: maxH must match the actual maximum return value of getMountainHeight!
+// Key 1: color thresholds must be based on heightRatio (normalized height 0~1), not absolute height!
+// Key 2: maxH must match the actual maximum return value of getMountainHeight!
 //           If getMountainHeight returns at most 15.0, maxH must be 15.0, not arbitrarily 20.0
-// IMPORTANT: Key 3: threshold spacing must be large enough (at least 0.2), otherwise color bands are too narrow to see
-// IMPORTANT: Key 4: grass area typically covers the largest terrain area (low elevation); set grass threshold high (0.4) to ensure green is clearly visible
-float maxH = 15.0;  // IMPORTANT: Must equal the actual max value of getMountainHeight!
+// Key 3: threshold spacing must be large enough (at least 0.2), otherwise color bands are too narrow to see
+// Key 4: grass area typically covers the largest terrain area (low elevation); set grass threshold high (0.4) to ensure green is clearly visible
+float maxH = 15.0;  // Must equal the actual max value of getMountainHeight!
 int getMountainVoxel(vec3 c) {
     float height = getMountainHeight(c.xz);  // Returns 0 ~ maxH
     if (c.y > height) return 0;  // Air
     float heightRatio = c.y / maxH;  // Normalize to 0~1
-    // IMPORTANT: Thresholds from low to high: grass < 0.4, rock 0.4~0.7, snow > 0.7
+    // Thresholds from low to high: grass < 0.4, rock 0.4~0.7, snow > 0.7
     if (heightRatio < 0.4) return 1;  // Grass (green) — largest area
     if (heightRatio < 0.7) return 2;  // Rock (gray)
     return 3;                          // Snow cap (white)
 }
-// IMPORTANT: Corresponding material colors must have sufficient saturation and clear contrast:
+// Corresponding material colors must have sufficient saturation and clear contrast:
 // mat==1: vec3(0.25, 0.55, 0.15)  Grass green (saturated green, must not be grayish!)
 // mat==2: vec3(0.5, 0.45, 0.4)   Rock gray-brown
 // mat==3: vec3(0.92, 0.93, 0.96) Snow white
-// IMPORTANT: Lighting must not be too bright or it washes out colors! Sun intensity ≤ 2.0, sky light ≤ 1.0
-// IMPORTANT: Gamma correction pow(col, vec3(0.4545)) brightens dark colors and reduces saturation;
+// Lighting must not be too bright or it washes out colors! Sun intensity ≤ 2.0, sky light ≤ 1.0
+// Gamma correction pow(col, vec3(0.4545)) brightens dark colors and reduces saturation;
 //    if colors look grayish-white, make grass green more saturated: vec3(0.2, 0.5, 0.1)
 
-// IMPORTANT: Rotating objects: to rotate a voxel object, apply inverse rotation to the sample point in getVoxel!
+// Rotating objects: to rotate a voxel object, apply inverse rotation to the sample point in getVoxel!
 // Do not rotate the camera to simulate object rotation (that only changes the viewpoint)
 bool getVoxelRotating(ivec3 c) {
     vec3 p = vec3(c) + vec3(0.5);
@@ -240,7 +240,7 @@ ao = pow(ao, 1.0 / 3.0);  // Gamma correction to control AO intensity
 
 ### Step 8: DDA Shadow Ray
 ```glsl
-// IMPORTANT: Shadow steps must be capped at 16; total main ray + shadow ray steps should not exceed 80
+// Shadow steps must be capped at 16; total main ray + shadow ray steps should not exceed 80
 #define MAX_SHADOW_STEPS 16
 
 float castShadow(vec3 ro, vec3 rd) {
@@ -268,7 +268,7 @@ float diffuse = max(dot(normal, sundir), 0.0) * shadow;
 // === Voxel Rendering - Complete ShaderToy Template ===
 // Includes: DDA traversal, face shading, neighbor AO, hard shadows
 
-// IMPORTANT: Performance critical: SwiftShader software renderer (headless browser evaluation environment) cannot handle too many loop iterations
+// Performance critical: SwiftShader software renderer (headless browser evaluation environment) cannot handle too many loop iterations
 // Default 64+16=80 steps, suitable for most scenes. Simple scenes (single cube) can increase to 96+24
 // Multi-building/character/Minecraft scenes must keep 64+16 or lower!
 #define MAX_RAY_STEPS 64
@@ -289,7 +289,7 @@ vec2 rotate2d(vec2 v, float a) {
 }
 
 // ---- Voxel Scene Definition ----
-// IMPORTANT: Default solid cube. Use sdBox for "voxel cube"; add SDF boolean ops for carved/sculpted shapes
+// Default solid cube. Use sdBox for "voxel cube"; add SDF boolean ops for carved/sculpted shapes
 int getVoxel(vec3 c) {
     vec3 p = c + 0.5;
     float d = sdBox(p, vec3(6.0));  // Solid 12x12x12 block
@@ -366,14 +366,14 @@ HitInfo castRay(vec3 ro, vec3 rd, int maxSteps) {
 }
 
 // ---- Shadow Ray ----
-// IMPORTANT: Shadow steps at 16 (combined with main ray 64 = 80, within SwiftShader safe range)
+// Shadow steps at 16 (combined with main ray 64 = 80, within SwiftShader safe range)
 float castShadow(vec3 ro, vec3 rd) {
     vec3 pos = floor(ro);
     vec3 ri = 1.0 / rd;
     vec3 rs = sign(rd);
     vec3 dis = (pos - ro + 0.5 + rs * 0.5) * ri;
     for (int i = 0; i < MAX_SHADOW_STEPS; i++) {
-        // IMPORTANT: getVoxel returns int; comparison must use int constant (0), not float (0.0)
+        // getVoxel returns int; comparison must use int constant (0), not float (0.0)
         if (getVoxel(pos) > 0) return 0.0;
         vec3 mm = step(dis.xyz, dis.yzx) * step(dis.xyz, dis.zxy);
         dis += mm * rs * ri;
@@ -383,7 +383,7 @@ float castShadow(vec3 ro, vec3 rd) {
 }
 
 // ---- Material Colors ----
-// IMPORTANT: Texture coloring key: "low saturation" does not mean "near white/gray"!
+// Texture coloring key: "low saturation" does not mean "near white/gray"!
 // Low saturation = colorful but not vivid, must retain clear hue differences (e.g., brick red 0.55,0.35,0.3 not gray-white 0.8,0.8,0.8)
 // Brick/stone textures: use UV periodic patterns (mortar lines = dark lines), never use solid colors!
 vec3 getMaterialColor(int mat, vec2 uv) {
@@ -396,7 +396,7 @@ vec3 getMaterialColor(int mat, vec2 uv) {
 }
 
 // ---- Brick/Stone Texture Coloring (use this to replace getMaterialColor when user requests "brick texture") ----
-// IMPORTANT: Key: brick texture = UV periodic pattern (staggered rows + mortar dark lines), not solid color!
+// brick texture = UV periodic pattern (staggered rows + mortar dark lines), not solid color!
 vec3 getBrickColor(vec2 uv, vec3 baseColor, vec3 mortarColor) {
     vec2 brickUV = uv * vec2(4.0, 8.0);
     float row = floor(brickUV.y);
@@ -447,14 +447,14 @@ void mainImage(out vec4 fragColor, in vec2 fragCoord) {
         float sky = 0.5 + 0.5 * hit.normal.y;
 
         vec3 lighting = vec3(0.0);
-        // IMPORTANT: Mountain/terrain scenes: sun light ≤ 2.0, sky light ≤ 1.0; too bright washes out material color differences
+        // Mountain/terrain scenes: sun light ≤ 2.0, sky light ≤ 1.0; too bright washes out material color differences
         lighting += 2.0 * diff * vec3(1.0, 0.95, 0.8) * shadow;
         lighting += 1.0 * sky * skyColor;
         lighting *= ao;
 
         col = matCol * lighting;
 
-        // IMPORTANT: Fog: coefficient should not be too large, otherwise nearby objects get swallowed into pure sky color
+        // Fog: coefficient should not be too large, otherwise nearby objects get swallowed into pure sky color
         // 0.0002 suits GRID_SIZE=16 scenes; use smaller coefficients for larger scenes
         float fog = 1.0 - exp(-0.0002 * hit.t * hit.t);
         col = mix(col, skyColor, clamp(fog, 0.0, 0.7));  // Clamp prevents objects from disappearing entirely
@@ -564,7 +564,7 @@ Water surface ripple reflections, underwater refraction, sand and seaweed for a
 float waterY = 0.0;
 
 // Underwater voxel scene definition (sand + seaweed)
-// IMPORTANT: All coordinate operations must use correct vector dimensions!
+// All coordinate operations must use correct vector dimensions!
 // c.xz returns vec2, only has .x/.y components, cannot use .z!
 int getVoxel(vec3 c) {
     float sandHeight = -3.0 + 0.5 * sin(c.x * 0.3) * cos(c.z * 0.4);
@@ -572,7 +572,7 @@ int getVoxel(vec3 c) {
     if (c.y < sandHeight + 1.0) return 2; // Sand surface
     // Seaweed: only grows underwater, above sand
     float grassHash = fract(sin(dot(floor(c.xz), vec2(12.9898, 78.233))) * 43758.5453);
-    // IMPORTANT: floor(c.xz) is vec2; the second argument to dot() must also be vec2
+    // floor(c.xz) is vec2; the second argument to dot() must also be vec2
     if (grassHash > 0.85 && c.y >= sandHeight + 1.0 && c.y < sandHeight + 1.0 + 3.0 * grassHash) {
         return 3;  // Seaweed
     }
@@ -586,7 +586,7 @@ bool hitWater = tWater > 0.0 && (tWater < hit.t || !hit.hit);
 if (hitWater) {
     vec3 waterPos = ro + rd * tWater;
     vec3 waterNormal = vec3(0.0, 1.0, 0.0);
-    // IMPORTANT: waterPos.xz is vec2; access with .x/.y (not .x/.z)
+    // waterPos.xz is vec2; access with .x/.y (not .x/.z)
     vec2 waveXZ = waterPos.xz;  // vec2: waveXZ.x = worldX, waveXZ.y = worldZ
     waterNormal.x += 0.05 * sin(waveXZ.x * 3.0 + iTime);
     waterNormal.z += 0.05 * cos(waveXZ.y * 2.0 + iTime * 0.7);
@@ -619,7 +619,7 @@ if (hitWater) {
 ### Variant 7: Rotating Voxel Objects
 Rotate voxel objects as a whole. Core: apply inverse rotation to sample points in getVoxel.
 ```glsl
-// IMPORTANT: Correct way to rotate objects: apply inverse rotation to sample coordinates in getVoxel
+// Correct way to rotate objects: apply inverse rotation to sample coordinates in getVoxel
 // Wrong approach: only rotate the camera (that just changes the viewpoint, not the object)
 int getVoxel(vec3 c) {
     vec3 p = c + 0.5;
@@ -638,7 +638,7 @@ int getVoxel(vec3 c) {
 ### Variant 8: Indoor/Cave/Enclosed Scenes (Point Lights + High Ambient Lighting)
 Indoor, cave, underground, sci-fi base, and other enclosed or semi-enclosed scenes require point lights and high ambient lighting.
 ```glsl
-// IMPORTANT: Key points for enclosed/semi-enclosed scenes (caves, interiors, sci-fi bases, mazes, etc.):
+// Key points for enclosed/semi-enclosed scenes (caves, interiors, sci-fi bases, mazes, etc.):
 // 1. Camera must be placed inside the cavity (a position where getVoxel returns 0)
 // 2. Must use point lights, not just directional light (directional light blocked by walls/ceiling = total darkness!)
 // 3. Ambient light must be high enough (at least 0.2-0.3) to prevent scene from being too dark to see details
@@ -647,13 +647,13 @@ Indoor, cave, underground, sci-fi base, and other enclosed or semi-enclosed scen
 // 6. Emissive elements (holographic screens, indicator lights, magic circles) use emissive materials: add emissive color directly to lighting
 
 // Cave scene: cavity = area where getVoxel returns 0
-// IMPORTANT: Cave/terrain noise functions must respect vector dimensions!
+// Cave/terrain noise functions must respect vector dimensions!
 // p.xz is vec2; if noise/fbm function takes vec3, construct a full vec3:
 //   Correct: fbm(vec3(p.xz, p.y * 0.5))  or use vec2 version of noise
 //   Wrong: fbm(p.xz + vec3(...))  ← vec2 + vec3 compile failure!
 int getVoxel(vec3 c) {
     float cave = sdSphere(c + 0.5, 12.0);
-    // IMPORTANT: For noise-carved detail, use c's components directly (all float)
+    // For noise-carved detail, use c's components directly (all float)
     cave += 2.0 * sin(c.x * 0.3) * sin(c.y * 0.4) * sin(c.z * 0.35);
     if (cave > 0.0) return 1;  // Rock wall
     return 0;  // Cavity (camera goes here)
@@ -670,7 +670,7 @@ float diff = max(dot(hit.normal, lightDir), 0.0);
 float shadow = castShadow(hit.pos + hit.normal * 0.01, lightDir);
 
 vec3 lighting = vec3(0.0);
-// IMPORTANT: High ambient light to prevent total darkness (required for enclosed scenes! at least 0.2)
+// High ambient light to prevent total darkness (required for enclosed scenes! at least 0.2)
 lighting += vec3(0.25, 0.22, 0.2);  // Warm ambient light
 lighting += 3.0 * diff * attenuation * vec3(1.0, 0.8, 0.5) * shadow;  // Point light
 
@@ -683,7 +683,7 @@ lighting += calcPointLight(hit.pos, hit.normal, torch1, vec3(1.0, 0.6, 0.2)) * f
 lighting += calcPointLight(hit.pos, hit.normal, torch2, vec3(0.2, 1.0, 0.5)) * flicker2;
 
 // Emissive materials (holographic displays, fluorescent moss, indicator lights, magic circles, etc.)
-// IMPORTANT: Emissive colors are added directly to lighting, unaffected by shadows
+// Emissive colors are added directly to lighting, unaffected by shadows
 if (hit.mat == 2) {
     lighting += vec3(0.1, 0.4, 0.15);  // Fluorescent moss (faint green)
 }
@@ -698,12 +698,12 @@ col = matCol * lighting;
 ### Variant 9: Voxel Character Animation
 Simple voxel character animation using time-driven offsets and rotations.
 ```glsl
-// IMPORTANT: Voxel character animation core approach:
+// Voxel character animation core approach:
 // 1. Split the character into multiple body parts (head, torso, left arm, right arm, left leg, right leg)
 // 2. Each part is an sdBox with independent offset/rotation parameters
 // 3. iTime drives limb swinging (sin/cos periodic motion)
 // 4. Combine all parts using SDF min()
-// IMPORTANT: SwiftShader performance critical: character function is called at every DDA step!
+// SwiftShader performance critical: character function is called at every DDA step!
 //    Must add AABB bounding box check in getVoxel: first check if c is near the character,
 //    skip sdBox calculations for that character if not nearby. Otherwise frame timeout → black screen
 //    Reduce MAX_RAY_STEPS to 64, MAX_SHADOW_STEPS to 16
@@ -737,12 +737,12 @@ int getCharacter(vec3 p, vec3 charPos, float animPhase) {
 }
 
 // Combine scene + characters in getVoxel
-// IMPORTANT: Must add AABB bounding box early exit! Character sdBox calculations are expensive
+// Must add AABB bounding box early exit! Character sdBox calculations are expensive
 int getVoxel(vec3 c) {
     // Scene (floor, walls, etc.)
     int scene = getSceneVoxel(c);
     if (scene > 0) return scene;
-    // IMPORTANT: AABB check: only call getCharacter near the character
+    // AABB check: only call getCharacter near the character
     // Character 1: warrior (at position (5,0,0)), bounding box ±5 cells
     if (abs(c.x - 5.0) < 5.0 && c.y >= 0.0 && c.y < 10.0 && abs(c.z) < 5.0) {
         int char1 = getCharacter(c, vec3(5, 0, 0), 0.0);
@@ -760,7 +760,7 @@ int getVoxel(vec3 c) {
 ### Variant 10: Waterfall / Flowing Water Particle Effects
 Dynamic waterfall, splash particles, water mist effects. Core: time-offset noise simulates water flow, hashed particles simulate splashes, exponential decay simulates mist.
 ```glsl
-// IMPORTANT: Key points for waterfall/flowing water/particle effects:
+// Key points for waterfall/flowing water/particle effects:
 // 1. Waterfall stream: noise + iTime vertical offset simulates water column flowing down
 // 2. Splash particles: hash-distributed voxels at the bottom, positions change with iTime to simulate splashing
 // 3. Water mist: semi-transparent accumulation (reduced alpha) or density field at the bottom simulates mist diffusion
@@ -782,14 +782,14 @@ int getVoxel(vec3 c) {
     // Bottom pool floor
     if (c.y < -2.0 && abs(c.x) < 8.0 && c.z > -6.0 && c.z < 3.0) return 2;  // Pool bottom
 
-    // IMPORTANT: Waterfall stream: narrow band x ∈ [-2, 2], falling from y=13 to y=0
+    // Waterfall stream: narrow band x ∈ [-2, 2], falling from y=13 to y=0
     //    Use iTime offset on y-coordinate noise to simulate downward water flow
     if (abs(c.x) < 2.0 && c.y >= 0.0 && c.y < 13.0 && c.z > -1.0 && c.z < 1.0) {
         float flowNoise = hash21(vec2(floor(c.x), floor(c.y - iTime * 8.0)));
         if (flowNoise > 0.25) return 3;  // Water (gaps simulate translucent water curtain)
     }
 
-    // IMPORTANT: Splash particles: bottom y ∈ [-1, 3], x ∈ [-4, 4]
+    // Splash particles: bottom y ∈ [-1, 3], x ∈ [-4, 4]
     //    Use hash + iTime to generate randomly bouncing voxel particles
     if (c.y >= -1.0 && c.y < 3.0 && abs(c.x) < 4.0 && c.z > -3.0 && c.z < 2.0) {
         float t = iTime * 3.0;
@@ -798,7 +798,7 @@ int getVoxel(vec3 c) {
         if (abs(c.y - yOffset) < 0.6 && particleHash > 0.7) return 4;  // Splash particle
     }
 
-    // IMPORTANT: Water mist: bottom y ∈ [-1, 2], wider range than splashes
+    // Water mist: bottom y ∈ [-1, 2], wider range than splashes
     //    Density decreases with height and distance from waterfall center
     if (c.y >= -1.0 && c.y < 2.0 && abs(c.x) < 6.0 && c.z > -5.0 && c.z < 3.0) {
         float distFromCenter = length(vec2(c.x, c.z));
@@ -823,7 +823,7 @@ vec3 getMaterialColor(int mat, vec2 uv) {
     return vec3(0.5);
 }
 
-// IMPORTANT: Water mist material needs special lighting: high emissive + translucent feel
+// Water mist material needs special lighting: high emissive + translucent feel
 // During shading:
 if (hit.mat == 5) {
     lighting += vec3(0.4, 0.5, 0.6);  // Water mist emissive (unaffected by shadows)
@@ -835,19 +835,19 @@ if (hit.mat == 5) {
 
 ### Variant 11: Multi-Building / Town / Minecraft-Style Scenes (Multi-Structure Town Composition)
 Towns, villages, Minecraft-style worlds, and other scenes requiring multiple discrete structures (houses, trees, lampposts, etc.) placed on the ground.
-**IMPORTANT: "Minecraft-like voxel scene" = multi-building scene; must follow the performance constraints of this template!**
+**"Minecraft-like voxel scene" = multi-building scene; must follow the performance constraints of this template!**
 ```glsl
-// IMPORTANT: Key points for multi-building scenes:
+// Key points for multi-building scenes:
 // 1. Define the ground first (height map or flat plane), ensure ground getVoxel returns correct material
 // 2. Each building uses an independent helper function, receiving local coordinates, returning material ID
 // 3. In getVoxel, check each building sequentially (using offset coordinates), return on first hit
 // 4. Camera must be outside the scene facing the center, far enough to see the full view
-// 5. IMPORTANT: Building coordinate ranges must be within DDA traversal range (MAX_RAY_STEPS * cell ≈ reachable distance)
-// 6. IMPORTANT: Scene range should not be too large! Concentrate all buildings within -20~20 range, camera 30-50 cells away
-// 7. IMPORTANT: SwiftShader performance critical: getVoxel must have AABB bounding box early exit!
+// 5. Building coordinate ranges must be within DDA traversal range (MAX_RAY_STEPS * cell ≈ reachable distance)
+// 6. Scene range should not be too large! Concentrate all buildings within -20~20 range, camera 30-50 cells away
+// 7. SwiftShader performance critical: getVoxel must have AABB bounding box early exit!
 //    Above ground (c.y > 0), check AABB range first; return 0 immediately if outside building area
 //    Otherwise every DDA step checks all buildings → frame timeout → black screen / only sky renders
-// 8. IMPORTANT: MAX_RAY_STEPS reduced to 64, MAX_SHADOW_STEPS to 16 (complex getVoxel requires lower step counts)
+// 8. MAX_RAY_STEPS reduced to 64, MAX_SHADOW_STEPS to 16 (complex getVoxel requires lower step counts)
 
 // Single house: width w, depth d, height h, with triangular roof
 int makeHouse(vec3 p, float w, float d, float h, int wallMat, int roofMat) {
@@ -902,13 +902,13 @@ int getVoxel(vec3 c) {
     // 2. Road (along z direction, x range -2~2)
     if (c.y < 1.0 && abs(c.x) < 2.0) return 2;  // Road surface
 
-    // IMPORTANT: AABB bounding box early exit (required for SwiftShader!)
+    // AABB bounding box early exit (required for SwiftShader!)
     // All buildings are within x:-15~15, y:0~12, z:-5~15
     // Return 0 immediately outside this range, avoiding per-building checks
     if (c.x < -15.0 || c.x > 15.0 || c.y > 12.0 || c.z < -5.0 || c.z > 15.0) return 0;
 
     // 3. Place buildings (each with offset coordinates)
-    // IMPORTANT: House width/height must be ≥ 5 cells, otherwise they look like dots from far away! Use bright material colors
+    // House width/height must be ≥ 5 cells, otherwise they look like dots from far away! Use bright material colors
     int m;
 
     // House A: position (5, 0, 3), width 6, depth 5, height 5
@@ -930,7 +930,7 @@ int getVoxel(vec3 c) {
     return 0;
 }
 
-// IMPORTANT: Camera setup: must be far enough to overlook the entire town
+// Camera setup: must be far enough to overlook the entire town
 // Recommended: ro = vec3(0, 15, -35), looking at scene center vec3(0, 3, 5)
 vec3 ro = vec3(0.0, 15.0, -35.0);
 vec3 lookAt = vec3(0.0, 3.0, 5.0);
@@ -939,12 +939,12 @@ vec3 right = normalize(cross(forward, vec3(0, 1, 0)));
 vec3 up = cross(right, forward);
 vec3 rd = normalize(forward * 0.8 + right * screenPos.x + up * screenPos.y);
 
-// IMPORTANT: Sunset/side-lit scene key: when light comes from the side or at low angle, building fronts may be completely backlit turning into black silhouettes!
+// Sunset/side-lit scene key: when light comes from the side or at low angle, building fronts may be completely backlit turning into black silhouettes!
 // Must satisfy all: (1) ambient light ≥ 0.3 (prevent backlit faces from going black); (2) house walls use bright materials (e.g., light yellow 0.85,0.75,0.55)
 // (3) house dimensions must not be too small (width/height ≥ 5 cells), otherwise they look like dots from far away
 vec3 sunDir = normalize(vec3(-0.8, 0.3, 0.5));  // Sunset low angle
 vec3 sunColor = vec3(1.0, 0.6, 0.3);  // Warm orange
-vec3 ambientColor = vec3(0.35, 0.3, 0.4);  // IMPORTANT: High ambient light (≥0.3) to prevent silhouettes
+vec3 ambientColor = vec3(0.35, 0.3, 0.4);  // High ambient light (≥0.3) to prevent silhouettes
 // lighting = ambientColor + diff * sunColor * shadow;
 ```
 
@@ -957,7 +957,7 @@ vec3 ambientColor = vec3(0.35, 0.3, 0.4);  // IMPORTANT: High ambient light (≥
 - Material queries, AO, normals, etc. are only computed after hit
 - Replace procedural voxel queries with `texelFetch` texture sampling
 - Multi-frame accumulation + reprojection for low-noise results
-- **IMPORTANT: MAX_RAY_STEPS defaults to 64, MAX_SHADOW_STEPS defaults to 16 (total 80)**. Only simple scenes (single cube/sphere) can increase to 96+24. Multi-building/Minecraft/character scenes with complex getVoxel must keep 64+16 or lower, otherwise SwiftShader frame timeout → only sky background renders
+- **MAX_RAY_STEPS defaults to 64, MAX_SHADOW_STEPS defaults to 16 (total 80)**. Only simple scenes (single cube/sphere) can increase to 96+24. Multi-building/Minecraft/character scenes with complex getVoxel must keep 64+16 or lower, otherwise SwiftShader frame timeout → only sky background renders
 
 **Composition Tips:**
 - **Procedural noise terrain**: use FBM/Perlin noise height maps inside `getVoxel()`

package/skills/smoke-check/SKILL.md

@@ -22,7 +22,7 @@ Output: `production/qa/smoke-[date].md`
 
 1. Verify `tests/` exists (else stop → `/test-setup`)
 2. Check CI workflow for test refs
-3. Read engine from `.claude/docs/technical-preferences.md`
+3. Detect the engine from `ProjectSettings/ProjectVersion.txt` (Unity) or the `.uproject` (Unreal)
 4. Load smoke test list from `production/qa/smoke-tests.md` or `tests/smoke/`
 5. Load QA plan from `production/qa/qa-plan-*.md` (most recent)
 

package/skills/sprint-plan/SKILL.md

@@ -44,6 +44,5 @@ Glob for `production/qa/qa-plan-sprint-[N].md`. Found → note in output. Not fo
 
 - `/qa-plan sprint` — required before implementation
 - `/story-readiness [story-file]` — validate before starting
-- `/dev-story [story-file]` — begin implementing
-- `/sprint-status` — check progress mid-sprint
+- `/sprint-report` — check progress mid-sprint
 - `/scope-check [epic]` — verify no scope creep

package/skills/start/SKILL.md

@@ -35,13 +35,13 @@ AskUserQuestion multi-tab:
 
 | Tipo | Rol | División | Skills clave |
 |------|-----|----------|-------------|
-| Juego | Dev | Game Dev | `/brainstorm`, `/setup-engine`, `/design-system` |
-| Web app | Dev | Software Eng | `/scaffold-nextjs`, `/create-architecture` |
-| API | Dev | Software Eng | `/scaffold-go`, `/scaffold-fastapi` |
-| Móvil | Dev | Software Eng | `/scaffold-flutter`, `/scaffold-react-native` |
+| Juego | Dev | Game Dev | `/brainstorm`, `/scaffold-unity` (Unity) o `/ue-project-context` (Unreal), `/design-system` |
+| Web app | Dev | Software Eng | `/nextjs-scaffold`, `/architecture-decision` |
+| API | Dev | Software Eng | `/scaffold-go`, `/scaffold-fastify-ts` |
+| Móvil | Dev | Software Eng | `/scaffold-react-native` |
 | Juego | Designer | Game Dev | `/brainstorm`, `/quick-design`, `/doc-gdd` |
 | Web | Designer | Product | `/ux-design`, `/design-handoff` |
-| Any | PM | PMO | `/sprint-planning`, `/clickup`, `/jira-tickets` |
+| Any | PM | PMO | `/sprint-plan`, `/clickup`, `/jira-tickets` |
 
 ## Paso 5: Set session state
 
@@ -53,8 +53,8 @@ AskUserQuestion: primary recommendation (Recommended), secondary option, "Ver to
 
 ## Routing Cheatsheet
 
-- Game from scratch: `/start` → `/brainstorm` → `/setup-engine` → `/art-bible` → `/design-system`
-- Web app: `/start` → `/scaffold-nextjs` → `/create-architecture` → `/design-api`
+- Game from scratch: `/start` → `/brainstorm` → `/scaffold-unity` (Unity) o `/ue-project-context` (Unreal) → `/art-bible` → `/design-system`
+- Web app: `/start` → `/nextjs-scaffold` → `/architecture-decision` → `/api-design`
 - Sprint en curso: `/start` → `/clickup status` → `/standup-report`
 
 ## Reglas

package/skills/story-done/SKILL.md

@@ -59,7 +59,7 @@ Ask approval → edit story: `Status: Complete` + `## Completion Notes` (date, c
 
 ## Phase 8: Surface Next Story
 
-Read sprint plan → find READY/NOT STARTED stories (not blocked, Must/Should Have). Present up to 3 options. If all Must Have complete → sprint close-out sequence: `/smoke-check sprint` → `/team-qa sprint` → `/gate-check`.
+Read sprint plan → find READY/NOT STARTED stories (not blocked, Must/Should Have). Present up to 3 options. If all Must Have complete → sprint close-out sequence: `/smoke-check sprint` → `/gate-check`.
 
 ## Protocol
 

package/skills/test-helpers/SKILL.md

@@ -21,8 +21,8 @@ Output: `tests/helpers/` with engine-specific helpers. Run after `/test-setup`,
 
 ## Detection
 
-- Read `.claude/docs/technical-preferences.md` → Engine, Language, Framework
-- No engine → stop: "Run `/setup-engine` first"
+- Detect the engine from the project: `ProjectSettings/ProjectVersion.txt` (Unity) or a `*.uproject` file (Unreal); language and test framework from the project files
+- No engine detected → ask the user which engine the project uses
 - Scan `tests/**/*_test.*` (up to 5 files): extract setup, assertion, factory, mock patterns
 - Read `design/gdd/systems-index.md`, in-scope GDDs, `docs/architecture/tr-registry.yaml`
 
@@ -48,3 +48,8 @@ Present summary of files to create → ask approval → write. **Never overwrite
 - Helpers reflect GDD bounds and constants, not invented values
 - Generated code is a starting point — adapt to actual class structure
 - Ask before writing to `tests/`
+
+## Next Steps
+
+- `/regression-suite` — map the new helpers onto critical paths that still lack regression tests
+- `/smoke-check` — run the suite before QA hand-off

package/skills/test-setup/SKILL.md

@@ -12,7 +12,7 @@ Scaffold automated testing infrastructure. Run once during Technical Setup phase
 
 ## Phase 1: Detect Engine & State
 
-1. Read `.claude/docs/technical-preferences.md` → Engine. Not configured → stop: "Run `/setup-engine` first"
+1. Detect the engine from the project: `ProjectSettings/ProjectVersion.txt` (Unity) or a `*.uproject` file (Unreal). None found → ask the user which engine the project uses
 2. Check existing: `tests/`, `tests/unit/`, `tests/integration/`, `.github/workflows/`, engine-specific dirs
 3. Report findings. If everything exists and no `force` arg → "Already in place. Re-run with `force` to regenerate"
 4. `force` skips early-exit but never overwrites existing files

package/skills/ue-actor-component-architecture/SKILL.md

@@ -498,7 +498,6 @@ Validate before considering the work done:
 - [ ] Ownership and attachment are explicit, with no dangling component references
 - [ ] Initialization happens in the correct lifecycle stage, not all in `BeginPlay`
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-ai-navigation/SKILL.md

@@ -515,7 +515,6 @@ Validate before considering the work done:
 - [ ] Perception configuration matches the intended detection ranges and teams
 - [ ] NavMesh generation settings cover the agent sizes actually used
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-animation-system/SKILL.md

@@ -510,7 +510,6 @@ Validate before considering the work done:
 - [ ] Montage sections and notifies are named consistently and documented
 - [ ] No gameplay decisions are made inside the animation graph
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-async-threading/SKILL.md

@@ -422,7 +422,6 @@ Validate before considering the work done:
 - [ ] Every async completion path handles the owner being destroyed mid-flight
 - [ ] Shared state is protected, or ownership is transferred instead of shared
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-audio-system/SKILL.md

@@ -515,7 +515,6 @@ Validate before considering the work done:
 - [ ] Attenuation settings are shared through assets rather than tuned per instance
 - [ ] Sounds are not started every frame or on every overlap event
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-blueprints/SKILL.md

@@ -122,7 +122,6 @@ Validate before considering the work done:
 - [ ] Reusable logic lives in a Blueprint Class, not the Level Blueprint
 - [ ] Construction Script does editor-time setup only, with no gameplay side effects
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, load times or the frame budget; fix it before handing the work over.
 

package/skills/ue-character-movement/SKILL.md

@@ -464,7 +464,6 @@ Validate before considering the work done:
 - [ ] Network prediction data was extended correctly for any new movement state
 - [ ] Root motion sources are used for authored displacement
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-cpp-foundations/SKILL.md

@@ -522,7 +522,6 @@ Validate before considering the work done:
 - [ ] Containers are `TArray`/`TMap`/`TSet`, strings use the right `FName`/`FText`/`FString` role
 - [ ] No `new`/`delete` on UObjects — `NewObject<>`/`CreateDefaultSubobject<>` only
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-data-assets-tables/SKILL.md

@@ -516,7 +516,6 @@ Validate before considering the work done:
 - [ ] Primary Asset types are registered so scanning and cooking behave correctly
 - [ ] No synchronous load of large assets on the game thread during gameplay
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-editor-tools/SKILL.md

@@ -512,7 +512,6 @@ Validate before considering the work done:
 - [ ] The tool fails safely on unexpected asset state instead of corrupting data
 - [ ] Bulk operations are undoable or clearly warn before running
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-game-features/SKILL.md

@@ -466,7 +466,6 @@ Validate before considering the work done:
 - [ ] Actions register and unregister symmetrically on activate/deactivate
 - [ ] The feature can be disabled without breaking a packaged build
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-gameplay-abilities/SKILL.md

@@ -506,7 +506,6 @@ Validate before considering the work done:
 - [ ] State is identified by Gameplay Tags rather than booleans
 - [ ] Ability activation policy and prediction were chosen deliberately
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
 

package/skills/ue-gameplay-framework/SKILL.md

@@ -455,7 +455,6 @@ Validate before considering the work done:
 - [ ] Nothing authoritative lives on the Pawn, which can be destroyed and respawned
 - [ ] Server and client paths were both considered for every piece of state
 - [ ] Conventions in `docs/unreal/project-context.md` were read and followed
-- [ ] The Common Mistakes section of this skill was reviewed against the change
 
 **PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.