К основному содержанию
правило CX Codex

migration-checklist — правило для Claude Code: гид по Three.js

Правило migration-checklist подсказывает агенту, как мигрировать код при обновлении Three.js. Перечисляет breaking changes с r125 и актуальные пути импортов.

MIT ★ 4 719 обновлён 2026-10-24

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
.claude/rules/migration-checklist.md
Открыть на GitHub

Что делает migration-checklist

Правило содержит таблицу поломок API Three.js с версии r125: удалённые конструкторы (BoxBufferGeometry теперь просто BoxGeometry), переименования (outputEncoding стал outputColorSpace), изменения поведения света и теней. Агент видит примеры старого и нового синтаксиса — импорты через three/webgpu вместо addons/renderers/webgpu/, булевый vertexColors вместо константы, новый цикл анимации через setAnimationLoop(). Для WebGPU перечислены обязательные пути TSL и дефолтные настройки PBR.

У каждой поломки — пример кода до и после, диагностика частых ошибок вроде «X is not a constructor» и значения дефолтных параметров decay, bias, roughness. Без внешних библиотек — правило читает сам Three.js.

Какие задачи решает

  • исправить ошибку импорта OrbitControls после обновления Three.js
  • заменить BoxBufferGeometry на актуальный конструктор
  • настроить colorSpace вместо устаревшего outputEncoding
  • адаптировать код к изменениям теней и PBR-материалов в r182–r183

Примеры запросов агенту

  • Поправь импорты Three.js под r170 в файле scene.js
  • Замени устаревшие конструкторы геометрии в models/
  • Проверь, нет ли проблем с BoxBufferGeometry — агент выдаёт ошибку конструктора

Как установить migration-checklist

Вручную: положить файлы

.claude/rules/migration-checklist.md

Поле paths во frontmatter ограничивает файлы

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы о migration-checklist

Как установить migration-checklist в Claude Code?

Положи файл в .claude/rules/migration-checklist.md — агент подтянет его автоматически.

Что делает migration-checklist?

Показывает агенту breaking changes Three.js с r125: какие конструкторы удалены, как переписать импорты, куда переехали свойства рендерера и материалов.

Какие версии Three.js покрывает правило?

С r125 по r183. Подробнее всего разобраны r170 (импорты), r147 (цвет и свет), r180–r183 (WebGPU и PBR).

Исходный текст

migration-checklist.md · MIT
# Migration Checklist

Breaking changes and migration guide for Three.js versions.

## Recent Changes (r180-r183)

### r182 → r183

- Shadow quality improved in WebGPURenderer; reduce/remove bias values
- RoomEnvironment scene position updated; lighting may differ
- Sky/SkyMesh legacy gamma correction removed
- MeshPostProcessingMaterial removed

### r181 → r182

- `PCFSoftShadowMap` deprecated with WebGLRenderer; use `PCFShadowMap`
- WebGPURenderer: `colorBufferType` → `outputBufferType`
- VOXLoader.load() restructured

### r180 → r181

- Indirect specular light computation improved for PBR
- Rough PBR materials now appear brighter
- `renderAsync()`/`computeAsync()` deprecated; use sync versions
- TSL: `PI2` → `TWO_PI`
- New JSDoc-based API documentation

## Import Changes (r170+)

### BAD - Deprecated

```javascript
import { WebGPURenderer } from 'three/addons/renderers/webgpu/WebGPURenderer.js';
import { MeshStandardNodeMaterial } from 'three/addons/nodes/materials/...';
```

### GOOD - Current

```javascript
import * as THREE from 'three/webgpu';  // WebGPURenderer and NodeMaterials
import { ... } from 'three/tsl';         // TSL functions
```

## Color Management (r151+)

### BAD - Old API

```javascript
renderer.outputEncoding = THREE.sRGBEncoding;
texture.encoding = THREE.sRGBEncoding;
```

### GOOD - Current API

```javascript
renderer.outputColorSpace = THREE.SRGBColorSpace;
texture.colorSpace = THREE.SRGBColorSpace;
// ColorManagement.enabled = true by default
```

## Geometry Changes (r125+)

### Removed

```javascript
// REMOVED - use BufferGeometry
const geometry = new THREE.Geometry();
```

### Aliases Removed

```javascript
// These no longer exist
BoxBufferGeometry → BoxGeometry
SphereBufferGeometry → SphereGeometry
PlaneBufferGeometry → PlaneGeometry
// Just use BoxGeometry, SphereGeometry, etc.
```

## Light Decay (r147+)

```javascript
// Default decay is now 2 (physically correct)
const light = new THREE.PointLight(0xffffff, 1);
light.decay = 2; // DEFAULT

// To restore old behavior:
light.decay = 1;
```

## Material Changes (r147+)

```javascript
// vertexColors is now boolean
material.vertexColors = true;  // CORRECT

// OLD:
// material.vertexColors = THREE.VertexColors; // REMOVED
```

## Renderer Changes

### setAnimationLoop

```javascript
// GOOD - Modern way
renderer.setAnimationLoop(animate);

// OLD - Still works but less preferred
function animate() {
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}
animate();
```

### XR Animation Loop

```javascript
// For WebXR, MUST use setAnimationLoop
renderer.xr.enabled = true;
renderer.setAnimationLoop(animate);
```

## Version Check

```javascript
console.log('Three.js version:', THREE.REVISION);

// Example: "182"
if (parseInt(THREE.REVISION) < 170) {
  console.warn('Please update Three.js to r170+');
}
```

## Common Migration Issues

### Issue: "X is not a constructor"

```javascript
// Check import path
// OLD:
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';

// NEW:
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
```

### Issue: Colors look different

```javascript
// Color management is now enabled by default
// If colors look washed out:
THREE.ColorManagement.enabled = false; // Revert to old behavior (not recommended)

// Better: Fix your color values for linear workflow
```

### Issue: Materials appear different

```javascript
// PBR materials changed in r180+
// Rough surfaces are now brighter
// Adjust roughness values if needed
material.roughness = 0.6; // May need to increase
```

### Issue: Shadows look wrong

```javascript
// Shadow bias may need adjustment
light.shadow.bias = -0.0001; // r183+ may need smaller values
```

## Quick Migration Checklist

- [ ] Update import paths (`addons/` instead of `examples/jsm/`)
- [ ] Replace `encoding` with `colorSpace`
- [ ] Remove BufferGeometry suffix (BoxGeometry, not BoxBufferGeometry)
- [ ] Check light decay values
- [ ] Update vertexColors to boolean
- [ ] For WebGPU: use `three/webgpu` and `three/tsl` imports
- [ ] Test shadows and adjust bias if needed
- [ ] Verify PBR material appearance

## References

- [Three.js Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide)
- [Three.js Releases](https://github.com/mrdoob/three.js/releases)

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

Похожие правила IDE

Все правила IDE по теме «Фронтенд и UI» →
threejs-animation CloudAI-X Скилл threejs-animation для работы с keyframe-анимацией, костями и морф-целями в Three.js. Помогает воспроизводить glTF-анимации, управлять костями скелета, миксировать и кроссфейдить клипы на WebGL и WebGPU. CX Codex +1 27 200установок web-shader-extractor lixiaolin94 Скилл web-shader-extractor для Claude Code и Codex извлекает и локально воспроизводит WebGL-, WebGPU-, Canvas- и шейдерные эффекты со страниц. Разбирает анимированные фоны и интерактивную 3D-графику. CX Codex +1 850установок r3f-fundamentals EnzeD Скилл r3f-fundamentals учит агента строить сцены React Three Fiber: Canvas, типизированный JSX, хуки рендер-цикла и владение ресурсами. Для базовой архитектуры сцены, не для детальных материалов. CX Codex +1 2 400установок r3f-animation EnzeD Скилл r3f-animation для плавной анимации 3D-объектов в React Three Fiber через useFrame, damping и GLTF-клипы. Подходит для процедурного движения, переходов между состояниями и управления анимацией по запросу. CX Codex +1 2 300установок build-hybrid-game-assets MengTo Скилл build-hybrid-game-assets для Claude Code, Codex, Cursor и других агентов: помогает спланировать, собрать или проверить гибридный пайплайн ассетов для Three.js и веб-игр. CX Codex +1 1 600установок threejs-towers MengTo Скилл threejs-towers для Claude Code и пяти других платформ, который учит агента строить башни, пагоды и купола параметрически в Three.js. Запускается, когда нужен герой-объект, который собирается на экране, а не просто появляется. CX Codex +1 1 500установок

Из того же набора86

Весь набор →
postprocessing-optimization Правило postprocessing-optimization для Three.js и React Three Fiber. Помогает оптимизировать постобработку и объединять шейдерные проходы без просадок FPS. CX Codex +1 ★ 4 719звёзд репо timeline-builder Скилл timeline-builder для Claude Code превращает JSON-данные в интерактивную HTML-хронологию с вертикальной, горизонтальной или двусторонней раскладкой. Отображает этапы проекта, историю выпусков и резюме. CX Codex +1 ★ 4 719звёзд репо loading-suspense Правило loading-suspense требует оборачивать асинхронные компоненты React Three Fiber в Suspense с заглушкой: без границы сцена останется пустой, пока грузится модель или текстура. CX Codex +1 ★ 4 719звёзд репо lighting-shadows-advanced Правило lighting-shadows-advanced для Claude Code настраивает освещение и тени в Three.js с учётом стоимости рендеринга. Оптимизирует тени при множестве источников света. CX Codex +1 ★ 4 719звёзд репо audio-spatial Правило audio-spatial для Claude Code задаёт шаблоны настройки 3D-звука в Three.js: позиционирование источников, затухание и реакцию на действия пользователя. CX Codex +1 ★ 4 719звёзд репо debug-devtools Правило debug-devtools для Claude Code и Codex добавляет в Three.js-проект средства диагностики производительности, сцены и потери WebGL-контекста. Находит узкие места и проверяет параметры вживую. CX Codex +1 ★ 4 719звёзд репо tsl-post-processing Правило tsl-post-processing для Claude Code описывает постобработку Three.js на TSL: эффекты подключаются к postProcessing.outputNode без цепочки проходов EffectComposer. Агент обращается к нему при написании кода сцены. CX Codex +1 ★ 4 719звёзд репо tsl-compute-shaders Правило tsl-compute-shaders подсказывает агенту, как писать вычислительные шейдеры на Three.js TSL для WebGPU и настраивать GPGPU-симуляции вроде частиц с расчётом физики. CX Codex +1 ★ 4 719звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой