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

perf-never-set-state-in-useframe — правило R3F

Правило perf-never-set-state-in-useframe для react-three-fiber: не вызывать setState внутри useFrame, потому что это даёт перерисовку на каждом кадре. Вместо состояния React — мутация ref.

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

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

Что делает perf-never-set-state-in-useframe

useFrame из react-three-fiber срабатывает на каждом кадре. Если внутри стоит setState, React пересобирает компонент с той же частотой, и почти всё время кадра уходит на это. Правило требует другого: держать объект Three.js в ref и менять ref.current.position напрямую. Такой мутации React не видит и перерисовку не запускает.

Внутри разобраны два примера, плохой и хороший, плюс вариант с delta: поворот задаётся в радианах в секунду и не зависит от частоты кадров. Несколько осей сразу ставятся через position.set и rotation.set. Для Zustand есть отдельный случай: чтение через getState() не подписывает компонент, поэтому цель можно брать прямо в useFrame и подтягивать через lerp.

Состояние React всё ещё нужно для интерфейса. Анимированный меш выносят в отдельный компонент, а счёт или подпись держат рядом в обычном: обновление счёта тогда не трогает меш. Искать по проекту стоит любой useFrame с setState внутри, потому что именно такой вызов и роняет кадры.

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

  • найти setState внутри useFrame и убрать лишние перерисовки
  • перевести покадровую анимацию с состояния React на мутацию ref
  • сделать скорость поворота независимой от частоты кадров через delta
  • читать цель из Zustand без подписки компонента на стор
  • вынести состояние интерфейса из анимированного компонента

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

  • Проверь Scene.jsx: если внутри useFrame вызывается setState, перепиши на мутацию ref.
  • Анимация дёргается. Посмотри, не обновляется ли состояние компонента на каждом кадре.
  • Переведи вращение на delta, а состояние оставь только для счёта в интерфейсе.

Как установить perf-never-set-state-in-useframe

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

.claude/rules/perf-never-set-state-in-useframe.md

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

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

Вопросы о perf-never-set-state-in-useframe

Как установить perf-never-set-state-in-useframe в Claude Code?

Положите файл правила в проект по пути .claude/rules/perf-never-set-state-in-useframe.md.

Что делает perf-never-set-state-in-useframe?

Запрещает вызывать setState внутри useFrame в react-three-fiber и показывает замену: правку ref.current у объекта Three.js.

Почему setState в useFrame так бьёт по кадрам?

useFrame идёт с частотой кадров, и каждый вызов setState планирует новую пересборку дерева React. Отсюда просадки кадров и паузы сборки мусора.

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

perf-never-set-state-in-useframe.md · MIT
# perf-never-set-state-in-useframe

**NEVER call setState inside useFrame.**

## Why It Matters

This is the #1 performance killer in R3F. Calling setState triggers React re-renders. useFrame runs at 60fps. setState in useFrame = 60 re-renders per second = destroyed performance.

## Bad Example

```jsx
// BAD - Causes 60 re-renders per second!
function BadComponent() {
  const [position, setPosition] = useState(0);

  useFrame(() => {
    setPosition(p => p + 0.01); // NEVER DO THIS
  });

  return <mesh position-x={position} />;
}
```

This triggers React reconciliation 60 times per second, causing:
- Massive CPU usage
- Frame drops
- Component re-creation
- Garbage collection pauses

## Good Example

```jsx
// GOOD - Mutate refs directly, no re-renders
function GoodComponent() {
  const meshRef = useRef();

  useFrame(() => {
    meshRef.current.position.x += 0.01;
  });

  return <mesh ref={meshRef} />;
}
```

The ref gives direct access to the Three.js object. Mutating it doesn't trigger React.

## With Delta Time

```jsx
function AnimatedComponent() {
  const meshRef = useRef();

  useFrame((state, delta) => {
    meshRef.current.rotation.y += 1 * delta; // 1 rad/sec
    meshRef.current.position.x = Math.sin(state.clock.elapsedTime);
  });

  return <mesh ref={meshRef} />;
}
```

## Multiple Values

```jsx
function ComplexAnimation() {
  const meshRef = useRef();

  useFrame(({ clock }) => {
    const t = clock.elapsedTime;
    meshRef.current.position.set(
      Math.sin(t) * 2,
      Math.cos(t * 2),
      Math.sin(t * 0.5)
    );
    meshRef.current.rotation.set(t, t * 0.5, 0);
  });

  return <mesh ref={meshRef} />;
}
```

## Using Zustand Without Re-renders

```jsx
function ZustandAnimation() {
  const meshRef = useRef();

  useFrame(() => {
    // getState() doesn't trigger re-renders
    const { targetPosition } = useStore.getState();
    meshRef.current.position.lerp(targetPosition, 0.1);
  });

  return <mesh ref={meshRef} />;
}
```

## When You NEED State

If you genuinely need React state (e.g., for UI updates), isolate it:

```jsx
// Keep animated mesh separate
function AnimatedMesh() {
  const meshRef = useRef();
  useFrame((_, delta) => {
    meshRef.current.rotation.y += delta;
  });
  return <mesh ref={meshRef} />;
}

// State changes here won't affect AnimatedMesh
function UI() {
  const [score, setScore] = useState(0);
  return <Html><div>{score}</div></Html>;
}

function Scene() {
  return (
    <>
      <AnimatedMesh />
      <UI />
    </>
  );
}
```

## References

- [R3F Performance Pitfalls](https://docs.pmnd.rs/react-three-fiber/advanced/pitfalls)

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

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

Все правила IDE по теме «Фронтенд и UI» →
react-three-fiber-architect Claude Design Skillstack Субагент react-three-fiber-architect для проектирования 3D-сцен на React Three Fiber: разбирает архитектуру, ищет узкие места рендера и предлагает план оптимизации. CX Codex ★ 1 428звёзд репо improve-threejs millionco Скилл improve-threejs для Claude Code находит утечки памяти GPU и просадки FPS в Three.js и React Three Fiber. Включается по запросу аудита или команде /improve-threejs. CX Codex +1 451установок threejs-animation iart-ai Скилл threejs-animation для ИИ-кодинга, который помогает писать анимацию Three.js и React Three Fiber: сцены, GLTF-клипы, камера по скроллу, инстансинг. CX Codex +1 2 300установок threejs-perf OpusGameLabs Скилл threejs-perf переводит отрисовку повторяющихся объектов Three.js на InstancedMesh и пакетное обновление матриц. Снижает число draw calls в сценах с сотнями одинаковых мешей. CX Codex +1 753установок threejs-react-three-fiber CloudAI-X Скилл threejs-react-three-fiber для Claude Code помогает собирать сцены three.js в React-компонентах. Он охватывает React Three Fiber, drei, цикл кадров и обработку событий указателя. CX Codex +1 6 800установок react-three-fiber freshtechbro Скилл react-three-fiber обучает агента строить декларативные 3D-сцены в React через Three.js, настраивать хуки рендера и загружать модели через Suspense. CX Codex +1 4 300установок

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

Весь набор →
official-docs-researcher Субагент official-docs-researcher сверяет актуальные сведения с официальной документацией и релизами. Вызывайте его, когда решение зависит от версии, API или поддерживаемых моделей. CX Codex ★ 4 719звёзд репо change-implementer Субагент change-implementer проводит одно заранее утверждённое изменение до конца: правит код, проверяет его в реальном запуске и докладывает, что увидел. CX Codex ★ 4 719звёзд репо tsl-why-use Правило tsl-why-use для Claude Code и Codex: кастомные материалы в Three.js собираются из нод TSL, а не через патч onBeforeCompile. Применяется в проектах со своими шейдерами. CX Codex +1 ★ 4 719звёзд репо asset-compression Правило asset-compression с инструкциями по сжатию 3D-ассетов для Three.js. Помогает настроить Draco, Meshopt, KTX2-текстуры и LOD для ускорения 3D-сцен в вебе. CX Codex +1 ★ 4 719звёзд репо frame-delta-time Правило frame-delta-time требует умножать движение на delta в useFrame, чтобы скорость анимации не зависела от частоты кадров. CX Codex +1 ★ 4 719звёзд репо draw-call-optimization Правило draw-call-optimization для Claude Code описывает оптимизацию сцены Three.js: снизить число вызовов отрисовки до 100 на кадр инстансингом, батчингом и слиянием геометрий. CX Codex +1 ★ 4 719звёзд репо object-pooling Правило object-pooling учит агента переиспользовать снаряды, частицы и NPC из пула, вместо того чтобы создавать и удалять меши каждый кадр. CX Codex +1 ★ 4 719звёзд репо shader-mobile Правило shader-mobile для Claude Code содержит приёмы оптимизации GLSL и Three.js шейдеров под мобильные GPU, помогающие избежать просадок FPS на смартфонах. CX Codex +1 ★ 4 719звёзд репо

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

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