# instancedMesh

> Talos next · Since 0.7

One mesh drawn at many places (rocks, fences, trees, props): N instances in a binary `.instances` file, each with a stable id that hits, picks and scripts report.

Static: collides through the static mesh path.

Use it in a scene entity's `components` list as `{ "type": "instancedMesh", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `asset` | `string` | yes |  |  | A key of scene.assets whose kind is "glb": the one mesh every instance draws. |
| `material` | `string` | no |  |  | A material asset drawn on every instance in place of the mesh's own, as on `mesh`. |
| `materials` | `object` | no |  |  | Per-submesh material override by glTF material name, as on `mesh`. |
| `color` | `string` | no |  |  | `#RRGGBB` tint over the material, as on `mesh`. |
| `castShadow` | `boolean` | no |  |  | Accepted for parity with `mesh`; not applied to instances yet. |
| `receiveShadow` | `boolean` | no |  |  | Accepted for parity with `mesh`; not applied to instances yet. |
| `source` | `string` | yes |  |  | Project-relative `.instances` file holding the instances. Missing or invalid: no instances, with `instances-source-missing` / `instances-source-invalid`. |
| `colliderMode` | `ColliderMode` | no |  | `simple`, `full`, `none` | How every instance collides: one static collider each, of the shape a `mesh` of the same asset would get in that mode. Absent: the asset's `colliderMode`, else the scene's `meta.physics.colliderMode`, else "simple" for a generated plant and "full" for anything else. |
| `collisionLayout` | `InstanceCollisionLayout` | no |  | `perInstance`, `cells` | One collider per instance or per cell (see InstanceCollisionLayout). Absent: the parent foliage layer's `collisionLayout` when this entity is one of its prototypes, else "perInstance". |
| `customData` | `string[]` | no |  |  | Names of the per-instance custom floats, in file order (at most 8). Absent: none. |
| `cullDistance` | `number` | no |  |  | Metres from the camera beyond which no instance draws. Absent: a perspective view stops drawing a cell where one instance would be under 1.5 pixels tall; an orthographic view has no limit. |
| `cellSize` | `number` | no |  |  | Edge in metres of the cells instances are culled and picked by. Absent: max(64, 8 x the mesh's radius). |