Buildings

Read and edit the buildings of the active project. Accessed via snaptrude.core.buildings.

A building is the top of the project's spatial hierarchy: a named container of storeys, positioned by its base elevation. This namespace reads a building's identity and base elevation and lists the storeys it holds; storey detail is read through snaptrude.entity.story.

All methods are host API calls that return Promises. Reads never throw for a missing building (get and getActive return null, list and listStoreys return []). Writes route through the undoable command system unless noted otherwise.

At a glance

Method	What it does	Mutates?
list()	List all buildings	—
get(buildingId)	One building by id, or null	—
listStoreys(buildingId)	A building's storey ids, in order	—
getActive()	The active building's id	—
setActive(buildingId)	Make a building active	✓ (not undoable)
create(name, baseElevation?)	Create an empty building	✓
update(buildingId, options?)	Rename / re-elevate a building (sparse)	✓
copy(buildingId, options?)	Copy a building with its contents	✓
delete(buildingId)	Delete a building (cascades to its contents)	✓

Types

PluginCoreBuildingRef

A building in the active project.

Property	Type	Description
id	string	Stable public building id (e.g. "blg_1")
name	string	Display name
baseElevation	number	Base elevation in meters, positive up (default 0)

Functions

list()

List the buildings in the active project.

• Returns: { buildings: PluginCoreBuildingRef[] } — empty when the project has none.

const { buildings } = await snaptrude.core.buildings.list();
for (const b of buildings) console.log(b.name, b.baseElevation);

---

get(buildingId)

Get a single building by id.

• Parameters:
  • buildingId: string — the id of the building to read
• Returns: PluginCoreBuildingRef | null — null if no building has that id.

const building = await snaptrude.core.buildings.get("blg_1");
if (building) console.log(building.name, building.baseElevation);

---

listStoreys(buildingId)

List the storeys of a building as stable storey ids, in storey order. Read each storey's detail through snaptrude.entity.story.

• Parameters:
  • buildingId: string — the id of the building whose storeys to list
• Returns: { storeyIds: string[] } — empty when the building is missing or has no storeys.

const { storeyIds } = await snaptrude.core.buildings.listStoreys("blg_1");
console.log(`${storeyIds.length} storeys`);

---

getActive()

Get the active building — the one new storeys and edits target. Paired with setActive.

• Returns: { buildingId: string } | null — null if there is no active building.

const active = await snaptrude.core.buildings.getActive();
if (active) console.log(active.buildingId);

---

setActive(buildingId)

Make a building the active building. Paired with getActive.

• Parameters:
  • buildingId: string — the id of the building to activate
• Returns: { buildingId: string } — the now-active building's id.
• Throws: If no building has the given id.
• Note: Flips UI state only — not undoable.

await snaptrude.core.buildings.setActive("blg_2");

---

create(name, baseElevation?)

Create a new building at the given base elevation (defaults to 0). The new building starts empty — add storeys through snaptrude.entity.story. Undoable.

• Parameters:
  • name: string — display name of the new building
  • baseElevation: number | undefined — base elevation in meters (defaults to 0)
• Returns: { buildingId: string } — id of the new building.
• Throws: If the building could not be created.

const { buildingId } = await snaptrude.core.buildings.create("Tower B", 0);

---

update(buildingId, options?)

A sparse update of a building's name and/or base elevation — omitted fields are left unchanged. Changing baseElevation repositions every storey mesh and cascades the storey bases. Undoable.

• Parameters:
  • buildingId: string — the id of the building to update
  • options.name: string | undefined — new display name (unchanged if omitted)
  • options.baseElevation: number | undefined — new base elevation in meters (unchanged if omitted)
• Returns: PluginCoreBuildingRef — the updated record.
• Throws: If no building has the given id.

const building = await snaptrude.core.buildings.update("blg_1", { name: "Tower A" });

---

copy(buildingId, options?)

Copy a building — its storeys, components, and drawing layers — into a new building. asInstances controls the copy's geometry: true (default) shares the source geometry as instances (low memory), false makes independent editable copies. Undoable.

• Parameters:
  • buildingId: string — the id of the building to copy
  • options.name: string | undefined — name for the copy (auto-generated if omitted)
  • options.baseElevation: number | undefined — base elevation for the copy in meters (source's if omitted)
  • options.asInstances: boolean | undefined — true shares source geometry as instances; false makes independent copies (default true)
• Returns: { buildingId: string } — id of the new building.
• Throws: If no building has the given id.

const { buildingId } = await snaptrude.core.buildings.copy("blg_1", {
  name: "Tower A Copy",
  asInstances: false
});

---

delete(buildingId)

Gated and destructive. Deleting a building cascades through its meshes, storeys, and the building itself, and removes its saved views — saved views are not restored on undo. The project's only remaining building cannot be deleted.

• Parameters:
  • buildingId: string — the id of the building to delete
• Returns: { deleted: true }
• Throws: If no building has the given id, or it is the only building.

await snaptrude.core.buildings.delete("blg_2");

Errors

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

Code	Thrown by	When	details
HANDLE_INVALID	setActive, update, copy, delete	No building has the given id	kind: "building"
PRECONDITION_FAILED	create, update, copy, delete	There is no active structure yet (project still loading, or no active layer)	—
PRECONDITION_FAILED	delete	The target is the project's only building	handles — the building id

Reads never throw: get and getActive return null on a miss, list and listStoreys return [].