threejs-perf

Q: How do I install threejs-perf?

Run npx skills add https://github.com/playableintelligence/game-creator --skill threejs-perf in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/threejs-perf/ (personal) or .claude/skills/threejs-perf/ (project).

Q: Which AI agents can use threejs-perf?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Q: Is threejs-perf safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Q: Who maintains threejs-perf?

It is published by playableintelligence in playableintelligence/game-creator. It has 647 recorded installs.

by playableintelligenceMedia & Creative

Three.js performance optimization patterns for draw calls, scene traversal, and instancing. Use when optimizing 3D scenes with 100+ repeated objects, thousands of moving entities, or draw calls above 500. Loaded by threejs-game, viral-game, and make-game for performance guidance.

Installs: 647
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/playableintelligence/game-creator --skill threejs-perf

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads threejs-perf automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Three.js Performance Optimization

Performance patterns for Three.js games, backed by measured before/after numbers on Three.js r183 (headless Chromium via Playwright, Apple M1 Pro, software WebGL).

Reference Files

instancing-static.md — InstancedMesh for large static repeated objects (19,600 → 1 draw call)
instancing-moving.md — Flat state buffer + batched InstancedMesh writes for moving entities (8,000 entities)
templates/ — Baseline vs optimized reference implementations for each pattern

When to Use This Skill

Scene has 100+ repeated objects sharing geometry/material
Draw calls exceed 500 and frame time is unstable
Thousands of moving entities need per-frame transform updates
Profile shows scene-graph traversal as a bottleneck

When NOT to Use

Object count is low (<50 unique meshes) — simpler code wins
Every object needs unique materials/shaders that defeat batching
Geometry differs enough that instancing provides no batching benefit

Pattern 1: Instancing Large Static Object Sets

Problem: Forests, debris, decorations as individual Meshes = unnecessary draw calls.

Solution: One InstancedMesh per shared geometry+material combo.

Evidence: ~19,365 → 2 draw calls. Render CPU p95: 28.5ms → 0.5ms (~57× faster). Build: 39.4ms → 3.9ms. See instancing-static.md.

// Anti-pattern: one Mesh per prop
for (let i = 0; i < 19600; i++) {
  const mesh = new THREE.Mesh(geometry, material);
  mesh.position.set(x, 0, z);
  scene.add(mesh); // 19,600 draw calls
}

// Correct: one InstancedMesh
const im = new THREE.InstancedMesh(geometry, material, 19600);
const mat = new THREE.Matrix4();
for (let i = 0; i < 19600; i++) {
  mat.makeTranslation(x, 0, z);
  im.setMatrixAt(i, mat);
}
im.instanceMatrix.needsUpdate = true;
scene.add(im); // 1 draw call

Pattern 2: Moving Entity Update Loops

Problem: Thousands of moving actors as individual Meshes = scene-graph churn + transform propagation.

Solution: Flat entity state buffer + batched InstancedMesh.setMatrixAt() writes.

Evidence: 8,000 → 1 draw calls. Render CPU p95: 9.9ms → 0.5ms (~20× faster). Update loop p95: 1.4ms → 0.3ms. See instancing-moving.md.

// Anti-pattern: per-entity Mesh position writes
meshes.forEach((mesh, i) => {
  mesh.position.x = computeX(i, tick);
  mesh.position.y = computeY(i, tick);
});

// Correct: batched instance matrix writes
const mat = new THREE.Matrix4();
for (let i = 0; i < count; i++) {
  mat.makeTranslation(computeX(i, tick), computeY(i, tick), computeZ(i, tick));
  instancedMesh.setMatrixAt(i, mat);
}
instancedMesh.instanceMatrix.needsUpdate = true;

Decision Tree

Is the object repeated 50+ times with same geometry+material?
├── YES → Is it static (no per-frame movement)?
│   ├── YES → Pattern 1: Static InstancedMesh (instancing-static.md)
│   └── NO  → Pattern 2: Moving InstancedMesh with batched writes (instancing-moving.md)
└── NO  → Standard Mesh is fine. Focus on material/geometry reuse.

Measured Results

Headless Chromium 147 via Playwright, Three.js r183, Apple M1 Pro, 30 warmup + 180 sample frames, median of 3 runs.

Scenario	Metric	Baseline	Optimized	Improvement
Static World (19.6k cubes)	Draw calls	~19,365	2	~9,682×
Static World (19.6k cubes)	Render CPU p95	28.5ms	0.5ms	~57×
Static World (19.6k cubes)	Build	39.4ms	3.9ms	~10×
Moving Entities (8k wave-field)	Draw calls	8,000	1	8,000×
Moving Entities (8k wave-field)	Render CPU p95	9.9ms	0.5ms	~20×
Moving Entities (8k wave-field)	Update loop p95	1.4ms	0.3ms	~4.7×

Methodology notes

CPU-side metrics are the trustworthy signal. Draw calls, render CPU p95, update loop, and build time reliably show the 1–2 order-of-magnitude win.
FPS and frame-time p95 are unreliable in headless Chromium. Playwright's bundled Chromium uses SwiftShader (software WebGL), which bottlenecks on fragment shading of ~90 MB of visible geometry regardless of draw-call count. On real hardware WebGL, the FPS gap would be substantially larger — baseline would drop to single-digit FPS under real fill, and optimized would hit vsync cleanly.
A benchmark passes if draw calls decreased and render CPU p95 did not regress.

FAQ

What does the threejs-perf skill do?

How do I install threejs-perf?

Run npx skills add https://github.com/playableintelligence/game-creator --skill threejs-perf in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/threejs-perf/ (personal) or .claude/skills/threejs-perf/ (project).

Which AI agents can use threejs-perf?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is threejs-perf safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains threejs-perf?

It is published by playableintelligence in playableintelligence/game-creator. It has 647 recorded installs.