Skip to main content
rule CX Codex

mobile-optimization — Claude Code rule: Three.js on mobile devices

mobile-optimization is a rule for accelerating Three.js scenes on smartphones and tablets. It reduces GPU load and memory use, helping maintain a stable frame rate.

MIT ★ 4,719 updated 2026-10-24

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

What mobile-optimization does

The rule brings together tested techniques: device detection and capability assessment, renderer setup (no antialiasing, capped pixel ratio at 1.5), material selection from fast (MeshBasicMaterial) to slow (MeshStandardMaterial). It covers texture compression via KTX2, combining shaders to cut draw calls, aggressive memory cleanup, and LOD for complex geometry.

You get practical profiles (high, medium, low): copy the one that fits your target device, swap in your textures and meshes. The rule targets iOS and Android. On weaker devices (4 cores or fewer, under 4 GB RAM), Phong material can drop from 60 FPS to 15 — the guide warns when to switch to Lambert or Basic instead.

Includes shadowing options (disable, bake into texture, or BasicShadowMap), keeps draw calls under 100, recommends texture sizes 512–1024 px for mobile. Covers touch controls and hit areas.

What it helps with

  • speed up Three.js scenes on mobile devices
  • reduce GPU and RAM consumption
  • lower draw calls to under 100
  • select materials and textures based on device capability
  • optimise post-processing and shadows for weak GPUs

Example prompts for the agent

  • Help me optimise this Three.js scene for mobile: add device detection and apply the right performance profile
  • Show how to set up the renderer and materials for iOS and Android targets
  • Import mobile-optimization into my project and tune it for my current scene

How to install mobile-optimization

Manually: put the files in place

.claude/rules/mobile-optimization.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 mobile-optimization

How do I install mobile-optimization in Claude Code?

Copy mobile-optimization.md into the .claude/rules/ directory of your project. Claude Code will then apply the guidance when working with Three.js code.

What does mobile-optimization do?

It provides ready-to-use code patterns for speeding up 3D scenes on mobile: material and texture choices, memory management, draw call reduction, and device-aware configuration.

Which devices does it cover, and when should I use it?

It targets iOS and Android. Use it when your scene lags on mobile, consumes too much memory, or when you need to support low-end phones with 4 cores or fewer and under 4 GB RAM.

Source text

mobile-optimization.md · MIT
# Mobile Optimization

Essential optimizations for Three.js on mobile devices.

## Device Detection

```javascript
const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
const isLowEnd = navigator.hardwareConcurrency <= 4;
const hasLimitedMemory = navigator.deviceMemory && navigator.deviceMemory < 4;
```

## Renderer Configuration

```javascript
const renderer = new THREE.WebGLRenderer({
  antialias: !isMobile,              // Disable AA on mobile
  powerPreference: 'high-performance',
  precision: isMobile ? 'mediump' : 'highp'
});

// Limit pixel ratio (CRITICAL)
renderer.setPixelRatio(Math.min(window.devicePixelRatio, isMobile ? 1.5 : 2));
```

## Material Hierarchy (Fast to Slow)

```javascript
// 1. MeshBasicMaterial (no lighting) - FASTEST
const basic = new THREE.MeshBasicMaterial({ color: 0xff0000 });

// 2. MeshLambertMaterial (per-vertex lighting)
const lambert = new THREE.MeshLambertMaterial({ color: 0xff0000 });

// 3. MeshPhongMaterial (per-pixel lighting)
const phong = new THREE.MeshPhongMaterial({ color: 0xff0000 });

// 4. MeshStandardMaterial (PBR) - SLOWEST
const standard = new THREE.MeshStandardMaterial({ color: 0xff0000 });
```

> On iOS, Phong can drop FPS from 60 to 15. Prefer Lambert or Basic for mobile.

## Texture Optimization

```javascript
// Max recommended: 1024x1024 for mobile, ideal: 512x512
texture.minFilter = THREE.LinearFilter; // Avoid mipmaps if not needed
texture.generateMipmaps = false;

// Use compressed formats - KTX2/Basis reduces memory 75%+
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
ktx2Loader.detectSupport(renderer);
```

## Shader Optimization

### BAD - Multiple passes

```javascript
composer.addPass(bloomPass);
composer.addPass(filmPass);
composer.addPass(colorPass);
// 3 draw calls, 3 framebuffer switches
```

### GOOD - Combined SuperShader

```javascript
const superShader = {
  uniforms: { /* all uniforms combined */ },
  fragmentShader: `
    // Combine all effects in single shader
    void main() {
      vec4 color = texture2D(tDiffuse, vUv);
      color = applyBloom(color);
      color = applyFilm(color);
      color = applyColorGrade(color);
      gl_FragColor = color;
    }
  `
};
// 1 draw call, 1 framebuffer switch
```

## Memory Management

```javascript
// Pre-allocate everything at init
const tempVec3 = new THREE.Vector3();
const tempMatrix = new THREE.Matrix4();

// NEVER allocate in render loop
function animate() {
  // BAD: new THREE.Vector3() here
  // GOOD: tempVec3.set(x, y, z)
}

// Dispose aggressively
texture.dispose();
geometry.dispose();
material.dispose();

// Monitor memory
console.log(renderer.info.memory);
```

## Draw Calls

```javascript
// Check draw calls
console.log(renderer.info.render.calls);

// Target: < 100 draw calls on mobile

// Reduce with:
// - InstancedMesh for repeated objects
// - Merged geometries for static objects
// - Texture atlases
// - Material sharing
```

## Shadows on Mobile

```javascript
// Option 1: Disable shadows entirely
renderer.shadowMap.enabled = false;

// Option 2: Baked shadows (texture on ground plane)
const shadowTexture = textureLoader.load('baked-shadow.png');
const shadowMaterial = new THREE.MeshBasicMaterial({
  map: shadowTexture,
  transparent: true
});

// Option 3: Simple shadow map (if needed)
renderer.shadowMap.type = THREE.BasicShadowMap;
light.shadow.mapSize.set(512, 512); // Lower resolution
```

## Level of Detail

```javascript
const lod = new THREE.LOD();

// High detail (close)
lod.addLevel(highDetailMesh, 0);

// Medium detail
lod.addLevel(mediumDetailMesh, 10);

// Low detail (far)
lod.addLevel(lowDetailMesh, 30);

// Mobile distances
if (isMobile) {
  lod.levels[0].distance = 5;  // Switch sooner
  lod.levels[1].distance = 15;
}
```

## Mobile Checklist

- [ ] Pixel ratio ≤ 1.5
- [ ] Textures ≤ 1024px
- [ ] No antialiasing (or FXAA)
- [ ] Simple materials (Basic/Lambert)
- [ ] Post-processing minimal or combined
- [ ] Dispose aggressively
- [ ] Draw calls < 100
- [ ] No shadows or baked shadows
- [ ] LOD for complex models
- [ ] Precision mediump

## Performance Profiles

```javascript
const profiles = {
  high: {
    pixelRatio: 2,
    textureSize: 2048,
    shadows: true,
    postprocessing: true,
    antialias: true
  },
  medium: {
    pixelRatio: 1.5,
    textureSize: 1024,
    shadows: true,
    postprocessing: false,
    antialias: false
  },
  low: {
    pixelRatio: 1,
    textureSize: 512,
    shadows: false,
    postprocessing: false,
    antialias: false
  }
};

const profile = isMobile ?
  (isLowEnd ? profiles.low : profiles.medium) :
  profiles.high;

applyProfile(profile);
```

## Touch Controls

```javascript
// OrbitControls works on touch by default
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;

// Disable zoom pinch if needed
controls.enableZoom = false;

// Touch-friendly hit areas
// Make interactive elements at least 44x44 CSS pixels
```

## References

- [Three.js Mobile Optimization](https://threejs.org/manual/#en/optimize-lots-of-objects)
- [WebGL Best Practices](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_best_practices)

© 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 →
animation-system animation-system — a practical guide to Three.js animation, from playing and blending clips to morph targets and bones. Useful when building scenes with animated models. CX Codex +1 ★ 4,719repo stars gltf-loading-optimization gltf-loading-optimization is a Claude Code rule with Three.js snippets and commands for glTF loading, decoder setup, progress reporting, lazy loading and model compression. CX Codex +1 ★ 4,719repo stars physics-integration physics-integration guides Three.js integration with Rapier and Cannon-es: Vite setup, collider primitives, and mesh synchronization patterns. CX Codex +1 ★ 4,719repo stars raycasting-optimization The raycasting-optimization rule covers ways to reduce Three.js raycasting work, from filtering objects by layer to using BVH or GPU picking. Useful when a scene has complex meshes or frequent pointer checks. CX Codex +1 ★ 4,719repo stars webxr-setup The webxr-setup rule for Claude Code guides building VR and AR scenes in Three.js WebXR. It helps coding agents set up render loops, controllers, and hit-testing. CX Codex +1 ★ 4,719repo stars error-handling-recovery The error-handling-recovery rule covers WebGL context loss, resource rebuilding, and fallback UI. Use it when a Three.js scene must recover from graphics failures. CX Codex +1 ★ 4,719repo stars vc-industry-research vc-industry-research turns a prompt into a PE/VC-style industry report: sector deep-dive, investment memo or market analysis, in Chinese or English, PDF by default. CX Codex +1 ★ 4,719repo stars tsl-complete-reference The tsl-complete-reference rule for Claude Code provides a TSL reference for writing node shaders without invalid syntax. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open