Skip to main content
rule CX Codex

shader-mobile — Claude Code rule: what it does, how to install

The shader-mobile rule for Claude Code provides guidelines for optimizing GLSL and Three.js shaders for mobile GPUs to prevent framerate drops on mobile devices.

MIT ★ 4,719 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/shader-mobile.md
Open on GitHub

What shader-mobile does

This guideline directs coding assistants to write GLSL code suited for mobile hardware constraints. It defaults floating-point math to mediump instead of highp, cutting arithmetic overhead almost in half. The rule also mandates packing interpolation attributes into composite vec4 variables to keep total varying counts at three or fewer, while consolidating single-channel textures into combined RGBA maps to drop memory lookups by 75%.

Inside shader routines, conditional branching gets replaced with math functions like mix() and step(), unbounded for loops switch to fixed ceilings with conditional breaks, and the costly discard statement gives way to alphaTest. It also advises shifting static matrix operations onto the CPU side and leaning on Three.js Shading Language (TSL) for cross-platform builds. The instructions only apply when your project actually builds custom materials with GLSL or WebGL nodes.

What it helps with

  • convert conditional if/else logic into mix() and step() calls
  • pack spread-out varying attributes into three or fewer vec4 slots
  • merge discrete textures into a single RGBA texture map
  • swap dynamic loop limits for static bounded loops
  • replace runtime discard calls with material alphaTest

Example prompts for the agent

  • Review TerrainShader.glsl and optimize it for mobile graphics chips
  • Compress varying variables in our vertex shader into packed vectors
  • Convert the dynamic light loop in lighting.glsl to a fixed upper limit

How to install shader-mobile

Manually: put the files in place

.claude/rules/shader-mobile.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about shader-mobile

How to install shader-mobile in Claude Code?

Place the rule text inside .claude/rules/shader-mobile.md in your repository root.

What does the shader-mobile rule do?

It guides the agent to write performant mobile shaders by enforcing mediump precision, vector packing, branchless math, and loop unrolling boundaries.

Why does this rule advise against using discard?

On tile-based mobile GPUs, discard disrupts early depth rejection; the guideline recommends configuring material.alphaTest and setting transparent = false instead.

Source text

shader-mobile.md · MIT
# Shader Optimization for Mobile

> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)

Mobile GPUs have specific constraints that require careful shader optimization.

## Use `mediump` Precision

Mobile processes `mediump` ~2x faster than `highp`:

```glsl
precision mediump float;

// Or per-variable
mediump vec3 color;
highp float depth; // Use highp only when necessary
```

## Minimize Varying Variables

Keep under 3 varyings for mobile GPUs by packing data:

```glsl
// BAD: 5 varyings
varying vec3 vPosition;
varying vec3 vNormal;
varying vec2 vUv;
varying vec3 vColor;
varying float vAlpha;

// GOOD: 2 varyings with packed data
varying vec4 vPositionAlpha; // xyz = position, w = alpha
varying vec4 vNormalUv;      // xy = normal.xy, zw = uv
// Reconstruct normal.z in fragment shader
```

## Replace Conditionals with `mix()` and `step()`

Branching is expensive on mobile GPUs:

```glsl
// BAD: Conditional
if (value > 0.5) {
  color = colorA;
} else {
  color = colorB;
}

// GOOD: Branchless
color = mix(colorB, colorA, step(0.5, value));
```

## Pack Data into RGBA Channels

Reduces texture fetches by 75%:

```glsl
// BAD: 4 texture fetches
float value1 = texture2D(tex1, uv).r;
float value2 = texture2D(tex2, uv).r;
float value3 = texture2D(tex3, uv).r;
float value4 = texture2D(tex4, uv).r;

// GOOD: 1 texture fetch
vec4 data = texture2D(dataTex, uv);
float value1 = data.r;
float value2 = data.g;
float value3 = data.b;
float value4 = data.a;
```

## Avoid Dynamic Loops

Use fixed loop bounds to enable compiler optimization:

```glsl
// BAD: Dynamic loop
for (int i = 0; i < numLights; i++) {
  // ...
}

// GOOD: Fixed loop with early exit
#define MAX_LIGHTS 4
for (int i = 0; i < MAX_LIGHTS; i++) {
  if (i >= numLights) break;
  // ...
}
```

## Avoid `discard`

Use `alphaTest` instead:

```javascript
// Instead of discard in shader
material.alphaTest = 0.5;
material.transparent = false; // Avoid transparent sorting
```

## Use TSL for Cross-Platform

TSL automatically optimizes for the target platform:

```javascript
import { color, positionLocal, sin, time } from 'three/tsl';

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = color(1, 0, 0).mul(sin(time).mul(0.5).add(0.5));
```

## Precompute on CPU

Move constant calculations out of shaders:

```javascript
// CPU: Compute once
const inverseViewMatrix = camera.matrixWorld.clone();
material.uniforms.uInverseView = { value: inverseViewMatrix };

// Update only when camera moves
camera.addEventListener('change', () => {
  material.uniforms.uInverseView.value.copy(camera.matrixWorld);
});
```

## Mobile Shader Checklist

- [ ] Use `mediump` precision by default
- [ ] Limit varyings to 3 or fewer
- [ ] Pack data into vec4 where possible
- [ ] Replace conditionals with mix/step
- [ ] Use fixed loop bounds
- [ ] Pack multiple values into single texture
- [ ] Avoid `discard`, use `alphaTest`
- [ ] Precompute constants on CPU
- [ ] Use TSL for automatic optimization

© zebbern · MIT · zebbern/claude-code-guide

Similar IDE rules

All IDE rules for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set86

The whole set →
perf-never-set-state-in-useframe perf-never-set-state-in-useframe — a react-three-fiber rule that bans setState inside useFrame and pushes you to mutate a ref instead, so animation stops triggering a React render every frame. CX Codex +1 ★ 4,719repo stars frame-delta-time frame-delta-time — a rule that makes every animated movement multiply by delta, so speed stops depending on the display's refresh rate. CX Codex +1 ★ 4,719repo stars draw-call-optimization The draw-call-optimization rule for Claude Code guides Three.js optimization, reducing draw calls to below 100 per frame through instancing, batching, and geometry merging. CX Codex +1 ★ 4,719repo stars object-pooling object-pooling — a rule that pushes the agent to reuse bullets, particles and NPCs from a pool instead of building and discarding meshes every frame. CX Codex +1 ★ 4,719repo stars drei-use-gltf The drei-use-gltf rule guides GLTF loading through useGLTF, including caching and preloading. It fits React Three Fiber scenes that need model assets. CX Codex +1 ★ 4,719repo stars perf-zustand-selectors perf-zustand-selectors — a rule file that pushes the agent to subscribe components to individual Zustand slices instead of the whole store, so a component repaints only when the data it reads changes. CX Codex +1 ★ 4,719repo stars geometry-instanced-mesh geometry-instanced-mesh guides AI agents to use THREE.InstancedMesh instead of separate meshes for repeating 3D objects. CX Codex +1 ★ 4,719repo stars webgpu-renderer The webgpu-renderer rule guides Three.js WebGPU setup with a WebGL 2 fallback. Use it when a 3D scene needs compute work, GPU particles, or indirect rendering. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open