object-pooling — правило для Claude Code: пул объектов в Three.js
Правило object-pooling учит агента переиспользовать снаряды, частицы и NPC из пула, вместо того чтобы создавать и удалять меши каждый кадр.
MIT ★ 4 719 обновлён 2026-10-24
.claude/rules/object-pooling.mdЧто делает object-pooling
Правило задаёт агенту паттерн пула для сцен Three.js: класс ObjectPool с factory, reset и стартовым размером, методы acquire и release, предварительный прогрев объектов на загрузке. В списке применений — пули, частицы, снаряды, спавн врагов и коллекционные предметы.
Внутри лежит markdown-файл с готовым классом и примером пула пуль. Все меши делят одну геометрию и материал, прячутся через visible = false вместо удаления со сцены и возвращаются в пул, когда длина позиции перевалит за 100. Рядом антипаттерн: новый SphereGeometry и MeshBasicMaterial на каждый спавн внутри setTimeout, без освобождения — память растёт.
Сбрасывать состояние при release правило просит не зря. Не обнулили userData.velocity — следующий снаряд полетит по старой траектории. Примеры написаны на JavaScript под Three.js, в другом движке класс придётся адаптировать.
Какие задачи решает
- переиспользовать снаряды вместо нового меша на каждый выстрел
- убрать паузы сборщика мусора из игрового цикла
- держать память сцены в предсказуемых рамках
- прогреть пул частиц на этапе загрузки
- найти утечку в спавне, где геометрия и материал не освобождаются
Примеры запросов агенту
- Сделай пул пуль для сцены Three.js: заготовь 50 мешей с общей геометрией и материалом, выдавай через
acquire, возвращай черезrelease. - Переделай спавн частиц по правилу object-pooling: никаких новых
SphereGeometryиMeshBasicMaterialв игровом цикле. - Добавь сброс состояния при
release: обнуляйuserData.velocityи прячь объект черезvisible = false.
Как установить object-pooling
Вручную: положить файлы
.claude/rules/object-pooling.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/object-pooling.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/object-pooling.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/object-pooling.mdВручную: положить файлы
.clinerules/object-pooling.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы об object-pooling
Как установить object-pooling в Claude Code?
Положите файл правила в проект по пути .claude/rules/object-pooling.md.
Что делает object-pooling?
Даёт агенту готовый рецепт пула: acquire и release, прогретые объекты, общая геометрия и материал, чтобы ничего не выделялось заново каждый кадр.
Чем плох спавн мешей через setTimeout?
Каждый вызов создаёт новые SphereGeometry и MeshBasicMaterial, а после удаления со сцены они остаются в памяти.
Исходный текст
object-pooling.md · MIT
# Object Pooling
> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)
Object pooling prevents garbage collection pauses by reusing objects instead of creating/destroying them.
## When to Use
- Bullets, particles, projectiles
- Spawned enemies/NPCs
- Collectibles
- Any frequently created/destroyed objects
## Implementation
```javascript
class ObjectPool {
constructor(factory, reset, initialSize = 20) {
this.factory = factory;
this.reset = reset;
this.pool = [];
// Pre-warm the pool
for (let i = 0; i < initialSize; i++) {
const obj = factory();
obj.visible = false;
this.pool.push(obj);
}
}
acquire() {
const obj = this.pool.pop() || this.factory();
obj.visible = true;
return obj;
}
release(obj) {
this.reset(obj);
obj.visible = false;
this.pool.push(obj);
}
}
```
## Example: Bullet Pool
```javascript
const bulletGeometry = new THREE.SphereGeometry(0.1);
const bulletMaterial = new THREE.MeshBasicMaterial({ color: 0xffff00 });
const bulletPool = new ObjectPool(
// Factory: create new bullet
() => {
const bullet = new THREE.Mesh(bulletGeometry, bulletMaterial);
scene.add(bullet);
return bullet;
},
// Reset: return bullet to initial state
(bullet) => {
bullet.position.set(0, 0, 0);
bullet.userData.velocity = null;
},
50 // Initial pool size
);
// Spawn bullet
function fireBullet(position, direction) {
const bullet = bulletPool.acquire();
bullet.position.copy(position);
bullet.userData.velocity = direction.clone().multiplyScalar(10);
activeBullets.add(bullet);
}
// Despawn bullet
function removeBullet(bullet) {
activeBullets.delete(bullet);
bulletPool.release(bullet);
}
// Update loop
function updateBullets(delta) {
for (const bullet of activeBullets) {
bullet.position.add(
bullet.userData.velocity.clone().multiplyScalar(delta)
);
// Check bounds
if (bullet.position.length() > 100) {
removeBullet(bullet);
}
}
}
```
## Key Benefits
1. **No GC pauses** - Objects are reused, not collected
2. **Predictable memory** - Pool size is bounded
3. **Faster spawning** - No allocation overhead
## Best Practices
1. **Pre-warm pools** - Create objects during loading, not gameplay
2. **Share geometry/material** - All pooled objects use same resources
3. **Reset completely** - Clear all state when releasing
4. **Size appropriately** - Match pool size to max concurrent objects
5. **Use visibility** - Toggle `visible` instead of add/remove from scene
## Anti-Pattern
```javascript
// BAD: Creates garbage every frame
function spawnParticle() {
const particle = new THREE.Mesh(
new THREE.SphereGeometry(0.1), // New geometry!
new THREE.MeshBasicMaterial() // New material!
);
scene.add(particle);
setTimeout(() => {
scene.remove(particle);
// Memory leak: geometry/material not disposed
}, 1000);
}
```
© zebbern · MIT · zebbern/claude-code-guide