Design Selection

Read and mutate the current scene selection. Accessed via snaptrude.design.selection.

Selection targets are ComponentHandles. The mutators (set/add/remove/clear) change the live selection and return the resulting selection snapshot — they are not undoable (the engine fires a selection listener, no command), so the returned PluginDesignChangeResult is a committed-state snapshot.

Types

PluginDesignChangeResult

Shared result for scene-state change mutations — echoes the handles actually affected. Errors throw (the RPC rejects); there is no Result<> wrapper in the SDK.

Property	Type	Description
affected	ComponentHandle[]	The resulting selection snapshot

PluginDesignSelectionSetArgs

Wire-level argument schema for set (the SDK call itself is positional: set(components)). PluginDesignSelectionAddArgs and PluginDesignSelectionRemoveArgs have the identical shape.

Property	Type	Description
components	ComponentHandle[]	The entities to select

PluginSelectionFilter

The filter for setByFilter. At least one field must be non-empty (to empty the selection use clear()). Fields AND-combine; values within a field OR-combine.

Property	Type	Description
storeys	number[] (optional)	Storey/floor levels to select (negative = basement)
types	PluginSelectionEntityType[] (optional)	Entity kinds to select

PluginSelectionEntityType

The entity kinds setByFilter can select — the union of the editor's "Filter selection" menus (Design tab + BIM tab). Includes selection-only kinds the query surface cannot reach:

"wall" | "slab" | "floor" | "door" | "window" | "beam" | "column" | "ceiling" | "roof" | "staircase" | "furniture" | "pergola" | "sunshade" | "referenceLine" | "space" | "site" | "terrain" | "cad" | "pdf" | "image" | "dimensionLine" | "model3d" | "neighborhoodBuilding" | "programBlock"

Functions

get()

Get the currently-selected entities.

• Returns: ComponentHandle[] — The selection ([] when nothing is selected)

const selected = await snaptrude.design.selection.get();
console.log(`${selected.length} entities selected`);

---

set(components)

Replace the selection with exactly the given entities.

• Parameters:
  • components: ComponentHandle[] — The entities to select
• Returns: PluginDesignChangeResult — The resulting selection snapshot

// Select every space in the project
const spaces = await snaptrude.design.query.listSpaces();
const result = await snaptrude.design.selection.set(spaces);
console.log(result.affected.length);

---

add(components)

Add entities to the current selection.

• Parameters:
  • components: ComponentHandle[] — The entities to add to the selection
• Returns: PluginDesignChangeResult — The resulting selection snapshot

---

remove(components)

Remove entities from the current selection.

• Parameters:
  • components: ComponentHandle[] — The entities to remove from the selection
• Returns: PluginDesignChangeResult — The resulting selection snapshot

---

clear()

Clear the selection (equivalent to set([])).

• Returns: PluginDesignChangeResult — The resulting (empty) selection snapshot

await snaptrude.design.selection.clear();

---

setByFilter(filter)

Replace the selection with every visible entity of the active building that matches the filter — the programmatic equivalent of the editor's Story selection (storeys) and Filter selection (types) menus under the select tool, including their combination. Reaches selection-only kinds the query surface cannot (sites, terrain, CAD/PDF/image imports, dimension lines, 3D models, neighborhood buildings) and selects whole groups the way the editor does.

This is a one-shot bulk select, not a persistent mode: the user's next canvas click resets the underlying filter state (the selection it made stays until changed). Results honor the ambient view — active building, hidden objects/buckets, and in 2D the active storey. Throws on an unknown storey (before mutating) and on an empty filter.

• Parameters:
  • filter: PluginSelectionFilter — Which entities to select; at least one field must be non-empty
• Returns: PluginDesignChangeResult — The resulting selection snapshot

// "Story selection": everything on storeys 1 and 2
await snaptrude.design.selection.setByFilter({ storeys: [1, 2] });

// "Filter selection": all walls and doors
await snaptrude.design.selection.setByFilter({ types: ["wall", "door"] });

// Combined: only the furniture on storey 2
const { affected } = await snaptrude.design.selection.setByFilter({
  storeys: [2],
  types: ["furniture"]
});

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
VALIDATION	setByFilter	The filter is empty — at least one field must be non-empty (use clear() to empty the selection)	issues
HANDLE_INVALID	set, add, remove	A component handle cannot be resolved	—
PRECONDITION_FAILED	set, add	A component has no selectable mesh (hidden or partially loaded) — thrown before any mutation, so the selection is untouched	handles — the mesh-less ids (the first is the primary handle)
PRECONDITION_FAILED	setByFilter	A storey in filter.storeys is unknown in the active building — thrown before mutating	storey — the unknown storey, requestedStoreys

remove is deliberately lenient where set/add throw: removing a mesh-less component is a no-op (it cannot be in the selection), not an error.