Storeys

Storey (building floor) management. Accessed via snaptrude.core.storeys.

A storey represents a building floor in the Snaptrude project. Storeys are identified by their integer storey value (e.g. 1 for the ground floor, 2 for the first floor, -1 for a basement).

This is the canonical home for storey operations; it shares its implementation and schemas with the deprecated entity.story surface. All methods are host API calls that return Promises and support undo/redo (except setActive, a view change).

Functions

get(storyValue, properties)

Get properties of a storey by its storey number. Only the properties listed in properties are returned — unlisted properties will be undefined in the result.

• Parameters:
  • storyValue: number (int) — The storey number (e.g. 1 for ground floor)
  • properties: PluginStoryGetProperty[] — Properties to retrieve (see table below)
• Returns: PluginStoryGetResult — A partial object with only the requested properties
• Throws: If the storey does not exist

const info = await snaptrude.core.storeys.get(1, ["height", "name", "spacesCount"]);
console.log(info.name, info.height, info.spacesCount);

---

list()

List all storeys in the current project. Returns basic identification data for every storey, sorted from top to bottom (highest storey value first).

• Returns: PluginCoreStoreysListResult — { storeys: Array<{ value: number, id: string, name: string }> }

Field rename

This is the entity.story.getAll() result with the array field renamed stories → storeys. The element shape ({ value, id, name }) and ordering are unchanged.

const { storeys } = await snaptrude.core.storeys.list();
for (const s of storeys) {
  console.log(`Storey ${s.value}: ${s.name} (id: ${s.id})`);
}

---

create(storyValue, height?)

Create a new storey (floor) in the project. The new storey is inserted at the position specified by storyValue. This operation is undoable.

• Parameters:
  • storyValue: number (int) — The storey number to create (e.g. 3 to add a third floor)
  • height: number (optional) — Height in Babylon units (use snaptrude.core.units.convert(value, from, to) to convert from meters/feet). If omitted, the project's default storey height is used.
• Returns: PluginStoryCreateResult — { storyId: string, storyValue: number }
• Throws: If a storey with the given value already exists or creation fails

// Create a new third floor with custom height
const { storyId } = await snaptrude.core.storeys.create(3, 4.5);

---

update(storyValue, height?, options?)

Update a storey's height and/or name. At least one must be supplied.

• Height is a geometry-aware edit that matches the Storeys panel: it stretches the walls/columns/masses on the storey, shifts every storey above by the delta, and re-fits staircases/curtain walls/furniture, all as one undo step. Omit the height argument to leave it unchanged.

• Name matches renaming in the Storeys panel: it is persisted immediately but, like the panel, is not part of the height undo step.

• Parameters:

  • storyValue: number (int) — Storey number of the storey to update
  • height: number (optional) — New height in Babylon units; omit to leave the height unchanged
  • options: object (optional) — name?: string (new display name for the storey)

• Returns: PluginStoryUpdateResult — { storyValue: number, height: number, name: string } (the storey's state after the update)

• Throws: PRECONDITION_FAILED if no storey has the given value; VALIDATION if neither height nor options.name is supplied; STORY_HEIGHT_REJECTED if the engine rejects the height; STORY_UPDATE_FAILED if the storey cannot be re-read after the update

// Set ground floor height to 5 Babylon units — walls stretch and the floors
// above move up to match, all in a single undo step.
const result = await snaptrude.core.storeys.update(1, 5);
// Rename only, leaving the height untouched.
await snaptrude.core.storeys.update(1, undefined, { name: "Lobby" });

---

getActive()

Get the active storey's value — the storey subsequent draws and creates target. Paired with setActive. A view read: it commits nothing and is not undoable.

• Returns: number — The active storey value, in the same numbering list and get use.

const storey = await snaptrude.core.storeys.getActive();
const info = await snaptrude.core.storeys.get(storey, ["name", "height"]);
console.log(`On storey ${storey}: ${info.name}`);

---

setActive(storyValue)

Make a storey the active storey — the same as clicking it in the storey/layer panel. Subsequent draws and creates target this storey, and in 2D the viewport switches to it. This is a view/navigation change: it is not undoable and commits nothing to the model.

• Parameters:
  • storyValue: number (int) — Storey number to activate
• Returns: PluginStorySetActiveResult — { storyValue: number } (the now-active storey)
• Throws: PRECONDITION_FAILED if no storey has the given value

// Activate storey 2, then draw a wall — it lands on storey 2.
await snaptrude.core.storeys.setActive(2);

---

delete(storyValue)

Delete a storey and everything on it — the same as removing it from the storey panel. Every element placed on the storey (walls, floors, masses, …) is deleted with it, the remaining storeys are re-stacked, and the active storey falls back to an adjacent one. Committed as a single undo step.

• Parameters:
  • storyValue: number (int) — Storey number to delete
• Returns: PluginStoryDeleteResult — { storyValue: number, newActiveStory: number }
• Throws: PRECONDITION_FAILED if no storey has the given value, or if plugin writes are disabled

const { newActiveStory } = await snaptrude.core.storeys.delete(3);
console.log(`Deleted storey 3; now on storey ${newActiveStory}`);

---

copy(direction, options?)

Copy a storey into the adjacent level, up or down. By default the whole storey is copied: every eligible element (walls, floors, roofs, masses, columns, beams, staircases, ceilings, parametric curtain walls, furniture) is copied one level "up" or "down". Pass options.components to copy only a subset. The target storey is created automatically if it does not yet exist, inheriting the source storey's height. Copies are instanced by default (unique: false) — they share geometry with the source; set unique: true for independent geometry. Doors and windows ride along with their host wall. Locked/ineligible elements are skipped and counted in skipped. One undo step.

• Parameters:
  • direction: 'up' | 'down' — Which way to stack the copy
  • options: object (optional) — components?: ComponentHandle[] (subset to copy), unique?: boolean (independent geometry instead of instances; default false)
• Returns: PluginStoryDuplicateResult — { sourceStory: number, targetStories: number[], created: ComponentHandle[], createdStoryValues: number[], skipped: number }
• Throws: NO_ACTIVE_STRUCTURE if there is no active structure; NO_ELIGIBLE_ELEMENTS if nothing is copyable; HANDLE_INVALID for a stale/foreign handle; or if plugin writes are disabled

// Copy the whole active storey one level up (instanced copies).
const { targetStories, created, skipped } = await snaptrude.core.storeys.copy("up");
console.log(`Copied ${created.length} elements onto storey ${targetStories}`);
if (skipped) console.log(`${skipped} elements were skipped`);

Queryable Properties

Properties that can be passed to get:

Value	Return Type	Description
"value"	number	The integer storey number
"id"	string	Unique storey identifier
"name"	string	Display name of the storey
"height"	number	Floor-to-floor height in Babylon units
"base"	number	Base elevation in Babylon units
"hidden"	boolean	Whether the storey is hidden in the viewport
"spacesCount"	number	Number of spaces on this storey
"totalArea"	number	Total floor area of this storey

Errors

Failed calls reject with a typed PluginError — see Error Handling. A storyValue is a storey number, not a handle, so an unknown storey surfaces as PRECONDITION_FAILED rather than HANDLE_INVALID. list never throws — it returns an empty storeys list when the project has none.