perf-visibility-toggle — правило для Claude Code: что делает
Правило perf-visibility-toggle учит ассистента скрывать Three.js-компоненты через свойство visible, а не удалять их из дерева React, чтобы видеокарта не пересобирала шейдеры.
MIT ★ 4 719 обновлён 2026-10-24
.claude/rules/perf-visibility-toggle.mdЧто делает perf-visibility-toggle
Правило предписывает переключать свойство visible у Three.js-объектов вместо условного рендеринга вида {show && <Model />}. При повторном монтировании React уничтожает объект Three.js, заново создаёт геометрию с материалами, отправляет данные в видеопамять и заставляет GPU компилировать шейдеры с нуля.
Свойство visible={false} оставляет меш в оперативной памяти, но пропускает его при отрисовке кадра. В тексте правила также описана прямая мутация свойства visible через ссылки в хуке useFrame и использование слоёв Three.js (layers), если нужно выборочно скрывать объекты от конкретной камеры без изменения общего флага видимости.
Полное удаление компонента из дерева остаётся оправданным только при жёстких ограничениях по памяти или когда объект появляется редко.
Какие задачи решает
- избежать повторной компиляции шейдеров при скрытии Three.js-моделей
- предотвратить лишнюю выгрузку геометрии и материалов в GPU
- настроить прямое управление видимостью меша внутри
useFrame - разделить отрисовку объектов по камерам через слои Three.js
Примеры запросов агенту
- Проверь сцену с 3D-моделью и замени условный рендеринг на свойство visible
- Оптимизируй переключение видимости меша в цикле useFrame через ref
- Покажи, как скрыть объект от основной камеры с помощью layers
Как установить perf-visibility-toggle
Вручную: положить файлы
.claude/rules/perf-visibility-toggle.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/perf-visibility-toggle.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/perf-visibility-toggle.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/perf-visibility-toggle.mdВручную: положить файлы
.clinerules/perf-visibility-toggle.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о perf-visibility-toggle
Как установить perf-visibility-toggle в Claude Code?
Сохраните файл правила по пути .claude/rules/perf-visibility-toggle.md в корне вашего проекта.
Что делает правило perf-visibility-toggle?
Оно объясняет ассистенту, что часто скрываемые 3D-компоненты нужно выключать через проп visible, чтобы не тратить ресурсы на пересоздание геометрии и шейдеров.
В каких случаях всё же нужно монтировать компонент заново?
Условный рендеринг нужен, если сцена ограничена по доступной памяти, объектов слишком много либо конкретный меш появляется крайне редко.
Исходный текст
perf-visibility-toggle.md · MIT
# Toggle Visibility Instead of Remounting
> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)
Toggle the `visible` prop instead of conditionally mounting/unmounting components.
## Why It Matters
Remounting a component:
1. Destroys the Three.js object
2. Triggers disposal (if configured)
3. Creates new geometry/material
4. Uploads new data to GPU
5. Recompiles shaders
Toggling visibility:
1. Sets `object.visible = false`
2. That's it - object stays in memory
## BAD: Conditional Mounting
```jsx
function Scene({ showModel }) {
return (
<>
{showModel && <ExpensiveModel />}
</>
);
}
```
Every toggle destroys and recreates the entire model.
## GOOD: Visibility Toggle
```jsx
function Scene({ showModel }) {
return (
<ExpensiveModel visible={showModel} />
);
}
```
Model stays in memory, just skipped during render.
## When to Use Each
### Use Visibility Toggle When:
- Frequent show/hide (e.g., UI state)
- Object is expensive to create
- Object is needed again soon
- Object count is manageable
### Use Conditional Mounting When:
- Object is rarely shown
- Memory is constrained
- Object is cheap to create
- Large number of potential objects
## With Refs
```jsx
function ToggleableModel() {
const meshRef = useRef();
const [visible, setVisible] = useState(true);
// Direct mutation for animations
useFrame(() => {
if (meshRef.current) {
meshRef.current.visible = shouldBeVisible;
}
});
return <mesh ref={meshRef} visible={visible} />;
}
```
## Visibility vs Layers
For complex visibility logic, consider using Three.js layers:
```jsx
function SelectiveRendering() {
const meshRef = useRef();
useEffect(() => {
// Set to layer 1 (not rendered by default camera)
meshRef.current.layers.set(1);
}, []);
return <mesh ref={meshRef} />;
}
```
Layers allow camera-selective rendering without changing visibility.
© zebbern · MIT · zebbern/claude-code-guide