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
.claude/rules/shader-mobile.mdWhat 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/elselogic intomix()andstep()calls - pack spread-out varying attributes into three or fewer
vec4slots - merge discrete textures into a single RGBA texture map
- swap dynamic loop limits for static bounded loops
- replace runtime
discardcalls with materialalphaTest
Example prompts for the agent
- Review
TerrainShader.glsland optimize it for mobile graphics chips - Compress varying variables in our vertex shader into packed vectors
- Convert the dynamic light loop in
lighting.glslto a fixed upper limit
How to install shader-mobile
Manually: put the files in place
.claude/rules/shader-mobile.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/shader-mobile.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/shader-mobile.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/shader-mobile.mdManually: put the files in place
.clinerules/shader-mobile.mdStep 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