Story

Story (floor/storey) management. Accessed via snaptrude.entity.story.

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

All methods are host API calls that return Promises and support undo/redo.

Functions

get(storyValue, properties)

Get properties of a story 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 story does not exist

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

---

getAll()

Get all stories in the current project.

Returns basic identification data for every storey, sorted from top to bottom (highest story value first).

• Returns: PluginStoryGetAllResult — { stories: Array<{ value: number, id: string, name: string }> }

const { stories } = await snaptrude.entity.story.getAll();
for (const s of stories) {
  console.log(`Story ${s.value}: ${s.name} (id: ${s.id})`);
}

---

create(storyValue, height?)

Create a new story (floor) in the project.

The new story 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 Snaptrude 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 story with the given value already exists or creation fails

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

---

update(storyValue, height?, options?)

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

• Height is a geometry-aware edit that matches the Stories 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 Stories panel: it is persisted immediately (saved to the project) but, like the panel, is not part of the height undo step.

• Parameters:

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

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

• Throws: If the story does not exist, if neither height nor name is supplied (VALIDATION), or the update fails

// Set ground floor height to 5 Snaptrude units
const result = await snaptrude.entity.story.update(1, 5);
// Rename only, leaving the height untouched
await snaptrude.entity.story.update(1, undefined, { name: "Lobby" });

---

setActive(storyValue)

Make a story the active story — the same as clicking it in the storey/layer panel. Subsequent draws and creates target this story, 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: If the story does not exist

// Activate story 2, then draw a wall — it lands on story 2
await snaptrude.entity.story.setActive(2);

---

delete(storyValue)

Delete a story and everything on it — the same as removing it from the storey panel. Every element placed on the story (walls, floors, masses, …) is deleted with it, the remaining stories are re-stacked, and the active story 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: If the story does not exist, or plugin writes are disabled

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

---

duplicate(direction, options?)

Duplicate the eligible elements of the active storey one level up or down — the same operation as the Stories panel's duplicate. By default it copies every duplicable element on the source storey; pass options.components to copy only a subset. Ineligible elements (locked, ride-along doors/windows, buildings) are skipped and reported in skipped. This operation is undoable.

Performance

When storeys share a layout, duplicate the storey instead of recreating its contents floor by floor — this copies every element in one call, and the default instanced copies keep the floors linked. See Performance.

• Parameters:
  • direction: 'up' | 'down' — Which way to stack the copy
  • options: object (optional) — components?: ComponentHandle[] (subset to copy), unique?: boolean (make independent geometry instead of instances)
• Returns: PluginStoryDuplicateResult — { sourceStory: number, targetStories: number[], created: ComponentHandle[], createdStoryValues: number[], skipped: number }
• Throws: If there is no active structure, or no eligible elements to duplicate

const result = await snaptrude.entity.story.duplicate("up");
console.log(`copied ${result.created.length} elements, skipped ${result.skipped}`);

Queryable Properties

Properties that can be passed to get:

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

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. Conditions specific to this namespace:

Code	Thrown by	When	details
VALIDATION	create	storyValue is 0 — storey values are non-zero integers (1 is the ground storey, -1 the first basement)	storyValue
VALIDATION	update	Neither height nor name was supplied	storyValue
PRECONDITION_FAILED	get, update, setActive, delete	No storey with the given value exists	storyValue
PRECONDITION_FAILED	create	A storey with the given value already exists	storyValue
OPERATION_FAILED	create	The engine could not create the storey	engineMessage

getAll never throws — it returns an empty list when the project has no storeys.