# instanced

Instanced geometry and material helpers for rendering many copies of a mesh with per-instance transforms.

---

## `InstancedGeometry`

An `InstancedBufferGeometry` that copies positions and indices from a base geometry and adds an `instanceMatrix` attribute (16 floats per instance, column-major `Matrix4`).

```typescript
new InstancedGeometry(baseGeometry: BufferGeometry, instanceCount: number)
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `baseGeometry` | `BufferGeometry` | Source geometry; its `position` attribute and index are copied |
| `instanceCount` | `number` | Number of instances to allocate |

### Methods

#### `setInstanceMatrix(i, mat) → void`

Write a `Matrix4` transform for instance `i` into the `instanceMatrix` attribute and mark it for GPU upload.

| Name | Type | Description |
|------|------|-------------|
| `i` | `number` | Zero-based instance index |
| `mat` | `Matrix4` | Transform matrix to store |

### Example

```typescript
import { InstancedGeometry, StandardInstancedMaterial } from '@yaoc1996/js-tools/three-utils'
import { BoxGeometry, Matrix4, Mesh } from 'three'

const base = new BoxGeometry(1, 1, 1)
const geo = new InstancedGeometry(base, 100)
const mat = new StandardInstancedMaterial({ uniforms: { color: { value: [1, 0, 0] } } })

geo.setInstanceMatrix(0, new Matrix4().makeTranslation(5, 0, 0))

const mesh = new Mesh(geo, mat)
```

---

## `StandardInstancedMaterial`

A `ShaderMaterial` that uses the built-in instanced vertex/fragment shaders. Accepts any `ShaderMaterialParameters` except `vertexShader` and `fragmentShader`, which are provided internally.

```typescript
new StandardInstancedMaterial(params?: ShaderMaterialParameters)
```

### Notes

- The `THREE` define is always injected. Additional defines can be passed via `params.defines`.
