Design Delete

Hard removal of scene BIM entities. Accessed via snaptrude.design.delete. This is distinct from design.erase.edge (a plan-level adjacency-edge topology op) and design.boolean.subtract (a CSG geometry delete) — these are three separate operations.

Performance

entities is array-only — pass every target in one call (one host round-trip). There is no per-item delete; never delete one entity at a time in a loop. See Performance.

Types

PluginDesignChangeResult

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

Property	Type	Description
affected	ComponentHandle[]	The entities that were deleted

Functions

entities(components)

Delete one or more entities in one host round-trip — pass the whole set at once rather than looping. Generic hard delete (backed by the same batched, undoable path as the editor's space delete). Cascade is opinionated by the engine: children are removed and linked-list neighbours are fixed up — not caller-tunable in v1. Undoable — commits as a single undo entry.

• Parameters:
  • components: ComponentHandle[] — Entities to delete (min 1). Unknown/forged handles reject the whole call (fail-fast)
• Returns: PluginDesignChangeResult — { affected }: the entities that were deleted, as ComponentHandle[] (echoed host-side from the resolved-and-deleted set). Deleted handles are stale afterwards: re-resolving one throws HANDLE_INVALID
• Throws: HandleInvalidError (code HANDLE_INVALID) if any supplied handle is unknown/forged — the whole call rejects before anything is deleted (all-or-nothing resolution)

// Delete the current selection in one undoable step
const selection = await snaptrude.design.selection.get();
if (selection.length > 0) {
  const { affected } = await snaptrude.design.delete.entities(selection);
  console.log(`Deleted ${affected.length} entities`);
}

Errors

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

Code	Thrown by	When	details
HANDLE_INVALID	entities	Any supplied handle is unknown, forged, or stale — thrown before anything is deleted, so the whole call is all-or-nothing	—

Repeated handles in one call are de-duplicated, not an error.