> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ploterr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instanced drawables

> Find and pick the objects that draw the repeated blocks of a storey.

A storey draws its repeated blocks instanced. Two or more copies of one block share one `THREE.InstancedMesh` for each body, one merged outline for each body, one `THREE.InstancedMesh` for each plan fill and one merged object for the plan lines. The copies stay real elements: they keep their bodies, their plan symbols, their ids and their edits. Only the drawing changes.

A storey also draws its walls, slabs, roofs, columns, beams, stairs and railings through batches: one `THREE.BatchedMesh` for each material and one merged outline for each outline material. These elements also stay real elements; only the drawing changes.

Use `instancedElementId` to find the block or the element under a pointer, and `isInstancedDrawable` to find the objects that draw them.

## Import

```typescript theme={null}
import {
  isInstancedDrawable,
  instancedElementId,
  INSTANCED_SOURCE_LAYER,
} from '@opengeometry/floorkit';
```

## Example

```typescript theme={null}
import * as THREE from 'three';
import { instancedElementId, type BuildingSession } from '@opengeometry/floorkit';

export function blockAt(
  session: BuildingSession,
  camera: THREE.Camera,
  pointer: THREE.Vector2,
): string | undefined {
  const raycaster = new THREE.Raycaster();
  raycaster.setFromCamera(pointer, camera);
  for (const hit of raycaster.intersectObject(session.root, true)) {
    const id = instancedElementId(hit);
    if (id !== undefined) return id;
  }
  return undefined;
}
```

## Notes

* Each instanced drawable has `userData.floorkitInstanced`: `kind` (`surface`, `symbol-fill`, `symbol-lines`, `batched`, `batched-outline`, `merged-lines` or `merged-fill`), `storeyId`, `assetRef` and `elementIds`. A surface also has `bodyKey` and `shapeId`. Instance `i` draws the block `elementIds[i]`. The `symbol-lines` object draws the plan lines of all blocks of its storey: its `assetRef` is `*`.
* A `batched` object is a `THREE.BatchedMesh`: slot `i` draws a body of the element `elementIds[i]`, and a hit on it has `batchId` (the slot), not `instanceId`. Its `assetRef` is empty. A `batched-outline` object draws the outlines of the batched bodies and a raycaster does not hit it.
* A `merged-lines` object is one `THREE.LineSegments` of a storey for each line style: it draws the outlines of the block copies and of the bodies that draw themselves, and the plan lines of stairs, railings and fills, with a colour per vertex. A hit on a plan line has `index`, and `instancedElementId(hit)` gives the element of that line; a hit on an outline of a body gives none, because the body's surface is hit first. A `merged-fill` object is a `THREE.BatchedMesh` of a storey that draws its plan fills (rooms, stairs, columns, slabs): slot `i` draws a fill of the element `elementIds[i]`, and `instancedElementId(hit)` gives that element. A selected or dragged element leaves both and draws its own lines and fills until the selection clears.
* The copies and the batched bodies themselves are on the render layer `INSTANCED_SOURCE_LAYER` (30). A camera and a raycaster on layer 0 do not see them. `Box3.expandByObject` still counts them. The kernel body of each copy and each batched body is host-drawn (`OpenGeometry.setHostDrawn`): its `visible` is `false`, so the three.js scene walk skips it, and the kernel still keeps its mesh current. Do not write `visible` on such a body. A part of an element whose whole content its storey draws this way (a body mount, an opening's group, a plan line or fill) has `visible` `false` too, so the walk skips it; the element's own `visible`, `modelView` and `profileView` keep their values. While any instanced drawable is hidden, as in the GLB export, these parts are shown again.
* `OpenGeometry.resolveHit` gives no body for a hit on an instanced drawable. Use `instancedElementId`, not the parents of the hit object.
* A change made in place to the material of a batched body does not show. Set the element's appearance instead: that takes the body out of the batch.
* A copy with its own shape (a mirrored or unevenly scaled copy) and a block with no other copy on its storey draw as before.

## isInstancedDrawable

Whether `object` is a storey's instanced drawable of repeated blocks or of batched elements.

```typescript theme={null}
function isInstancedDrawable(object: THREE.Object3D): boolean;
```

## instancedElementId

The live id of the block that a raycaster hit on an instanced drawable shows, or undefined for a hit on anything else.

```typescript theme={null}
function instancedElementId(hit: THREE.Intersection): string | undefined;
```

## INSTANCED\_SOURCE\_LAYER

The render layer of a placed block's own surfaces, outlines and plan symbols while one instanced drawable of its storey draws them: a camera on layer 0 does not draw them, a raycaster on layer 0 does not hit them, and their bounds still count.

```typescript theme={null}
const INSTANCED_SOURCE_LAYER = 30;
```

## Types

### InstancedDrawableData

What an instanced drawable of a storey draws, on its `userData.floorkitInstanced`.

```typescript theme={null}
interface InstancedDrawableData {
  readonly kind:
    | 'surface'
    | 'symbol-fill'
    | 'symbol-lines'
    | 'batched'
    | 'batched-outline'
    | 'merged-lines'
    | 'merged-fill'
    | 'silhouette-lines'
    | 'wide-lines';
  readonly storeyId: string;
  readonly assetRef: string;
  readonly bodyKey?: string;
  readonly shapeId?: string;
  readonly elementIds: readonly string[];
}
```

**kind** `'surface' | 'symbol-fill' | 'symbol-lines' | 'batched' | 'batched-outline' | 'merged-lines' | 'merged-fill' | 'silhouette-lines' | 'wide-lines'` *required*

**storeyId** `string` *required*

The storey of the first copy; a surface or symbol fill draws the copies of every storey.

**assetRef** `string` *required*

**bodyKey** `string`

**shapeId** `string`

**elementIds** `readonly string[]` *required*

The live ids of the elements it draws: instance `i` draws `elementIds[i]`; for a batch, slot `i`
(the hit's `batchId`) draws `elementIds[i]`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.