---
id: wiki-2026-0508-instancedmesh2
title: InstancedMesh2
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [three-instanced-mesh2, three.js-instancedmesh2]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [three.js, webgl, performance, instancing, rendering]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: three.js
---

# InstancedMesh2

## 매 한 줄
> **"매 InstancedMesh의 진화형 — frustum culling, LOD, BVH, per-instance uniforms를 그대로 지원하는 instancing 솔루션"**. 매 three.js의 stock InstancedMesh가 모든 instance를 ALWAYS draw 하는 한계를 극복하기 위해 등장한 community library — agargaro/instanced-mesh가 매 2024-2026 사실상 표준으로 자리잡음.

## 매 핵심

### 매 stock InstancedMesh의 한계
- 매 frustum culling 부재 → off-screen instance도 GPU에 commit
- 매 per-instance visibility toggle 부재
- 매 LOD 미지원 — 매 distance 무관 동일 mesh draw
- 매 raycasting brute-force — 매 매 instance 매 triangle scan

### 매 InstancedMesh2 추가 기능
- **Per-instance frustum culling**: 매 BVH 기반 fast cull
- **LOD groups**: 매 distance threshold 별 다른 geometry
- **BVH acceleration**: 매 raycast O(log n)
- **Per-instance uniforms**: 매 색상/sprite frame/animation time 등
- **Shadow culling**: 매 shadow camera frustum 별도 cull

### 매 응용
1. 매 RTS/시뮬레이션 — 매 1k+ unit 매 60fps.
2. 매 archviz — 매 forest/도시 scenery instance.
3. 매 particle alternative — 매 mesh-particle hybrid.

## 💻 패턴

### 매 기본 setup
```typescript
import { InstancedMesh2 } from '@three.ez/instanced-mesh';
import * as THREE from 'three';

const geo = new THREE.BoxGeometry(1, 1, 1);
const mat = new THREE.MeshStandardMaterial();
const count = 10_000;

const mesh = new InstancedMesh2(geo, mat, { capacity: count });
mesh.addInstances(count, (obj, idx) => {
  obj.position.set(
    (Math.random() - 0.5) * 200,
    0,
    (Math.random() - 0.5) * 200,
  );
  obj.color = new THREE.Color(Math.random(), Math.random(), Math.random());
});
mesh.computeBVH();
scene.add(mesh);
```

### 매 LOD groups
```typescript
const lod = new InstancedMesh2(geoHigh, mat, { capacity: 5000 });
lod.addLOD(geoMid, mat, 30);   // 30 units 부터 mid mesh
lod.addLOD(geoLow, mat, 100);  // 100 units 부터 low mesh
lod.addShadowLOD(geoShadow, 50); // shadow 용 별도 LOD
```

### 매 per-instance update
```typescript
mesh.updateInstances((obj, idx) => {
  obj.position.y = Math.sin(time + idx * 0.1);
  obj.rotation.y += 0.01;
});
```

### 매 frustum culling toggle
```typescript
mesh.perObjectFrustumCulled = true;  // default
mesh.sortObjects = true;             // 매 transparent 매 back-to-front
```

### 매 raycasting BVH
```typescript
mesh.computeBVH({ margin: 0 });
const ray = new THREE.Raycaster();
ray.setFromCamera(mouse, camera);
const hits = ray.intersectObject(mesh);
// hits[0].instanceId 매 정확한 instance
```

### 매 instance 제거
```typescript
mesh.removeInstances([0, 5, 10]);  // 매 batch 매 1 frame
mesh.computeBVH();  // 매 dirty 면 rebuild
```

### 매 color attribute
```typescript
mesh.setColorAt(idx, new THREE.Color('red'));
mesh.instanceColor.needsUpdate = true;
```

### 매 shader integration
```typescript
mat.onBeforeCompile = (shader) => {
  shader.vertexShader = shader.vertexShader.replace(
    '#include <begin_vertex>',
    `#include <begin_vertex>
     transformed += instanceMatrix[3].xyz * 0.01;`
  );
};
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| <500 instance | 매 stock InstancedMesh |
| 1k-100k 매 same geometry | InstancedMesh2 |
| 매 different geometries | BatchedMesh |
| 매 GPU-driven 매 indirect | 매 custom WebGPU |

**기본값**: 매 1k 이상 instance — InstancedMesh2.

## 🔗 Graph
- 부모: [[InstancedMesh]] · [[three.js]]
- 변형: [[BatchedMesh]] · [[three-mesh-bvh]]
- 응용: [[Frustum Culling]] · [[Draw Call]]
- Adjacent: [[BVH]] · [[Raycasting|Raycaster]]

## 🤖 LLM 활용
**언제**: 매 large-scale 동일 mesh scene — vegetation, crowd, debris.
**언제 X**: 매 instance 별 geometry 다름 — BatchedMesh 사용.

## ❌ 안티패턴
- **BVH 매 update 안 함**: 매 instance 이동 후 raycast 부정확.
- **capacity 매 너무 크게**: 매 GPU memory 매 낭비.
- **per-frame full update**: 매 dirty flag 만 flush.

## 🧪 검증 / 중복
- Verified (@three.ez/instanced-mesh v0.4+, three.js r170+).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — InstancedMesh2 라이브러리 사용법 + LOD/BVH 패턴 정리 |