Furniture

The placeable furniture catalog (a library of source items, NOT scene entities). Accessed via snaptrude.design.furniture. Placement lives at design.create.furniture (returns a ComponentHandle); reads of placed furniture live at design.query.listFurniture/getProperties.

Catalog items are plain value records (PluginFurnitureCatalogItem) keyed by a library id (team _id or general fullName) — not handles. Reads are async (network-backed) but carry no Async suffix.

Types

PluginFurnitureCatalogItem

A placeable furniture catalog item (value record — not a scene entity/handle).

Property	Type	Description
id	string	Library id (team _id or general fullName) — pass to design.create.furniture
name	string	Display name
source	'team' | 'general'	Which library it came from
subType	string (optional)	Sub-type
category	string (optional)	Picker category — identical to subType (living / bedroom / kitchen / …)
thumbnailUrl	string (optional)	Preview image URL (team items)
cost	number (optional)	Cost (team items)
familyName	string (optional)	Family name

PluginObjectCatalogGroup

A catalog group surfaced by listCatalogGroups. The same type design.doors and design.windows return, so all three catalog surfaces share one shape.

Property	Type	Description
dbType	string	Group token — pass to listCatalog's category
label	string	Display label (for furniture, identical to dbType)
source	'default' | 'team'	Built-in picker group, or a sub-type of this project's team library

PluginFurnitureDimensions

A placed furniture item's dimensions (engine units). Axis convention matches the furniture properties panel.

Property	Type	Description
length	number	Along the object (panel Length)
width	number	Across the object (panel Width)
height	number	Vertical (panel Height)

Functions

listCatalogGroups()

List the furniture catalog's groups. Matches design.doors.listCatalogGroups and design.windows.listCatalogGroups, so all three catalog surfaces are named alike.

The built-in picker categories come back as source: 'default'; the sub-types of this project's team library come back as source: 'team', de-duplicated against the built-ins case-insensitively. That is the same project-scoped item set listCatalog filters, so every 'team' group is guaranteed to match at least one listCatalog('team', group.dbType) item.

Furniture has no separate engine token for a group — the category string is the token — so dbType and label are the same string. (design.doors has a distinct engine dbType.)

• Returns: PluginObjectCatalogGroup[] — The catalog groups ([] when empty)

const groups = await snaptrude.design.furniture.listCatalogGroups();
for (const g of groups) console.log(g.dbType, g.label, g.source);

// Pass a group's dbType straight to the catalog filter
const items = await snaptrude.design.furniture.listCatalog(undefined, groups[0].dbType);

---

listCategories()

List the furniture picker categories — the built-in order (living, bedroom, kitchen, …) plus any team-uploaded types, de-duplicated. Reads never throw; on a backend miss it falls back to the built-ins.

• Returns: string[] — Category labels

const categories = await snaptrude.design.furniture.listCategories();

Deprecated — use listCatalogGroups

listCategories() is the deprecated former name of this read, kept working unchanged. Prefer listCatalogGroups(): it returns the { dbType, label, source } shape design.doors and design.windows already use, and it is project-scoped. listCategories' user-type half comes from a backend endpoint that takes no team or project parameter and is cached across projects, so it can list categories with no items in this project and miss ones that have them.

---

listCatalog(source?, category?)

List the placeable furniture catalog (team + general libraries), optionally filtered by library and/or picker category.

• Parameters:
  • source: 'team' | 'general' (optional) — Restrict to one library
  • category: string (optional) — Restrict to one picker category (case-insensitive, matches subType)
• Returns: PluginFurnitureCatalogItem[] — The catalog ([] when empty)

// Kitchen furniture from the team library only
const items = await snaptrude.design.furniture.listCatalog("team", "kitchen");
for (const item of items) {
  console.log(item.id, item.name, item.category);
}

---

getCatalogItem(id)

Get a single catalog item by its library id.

• Parameters:
  • id: string — The catalog library id
• Returns: PluginFurnitureCatalogItem | null — The item, or null if no catalog item matches

const item = await snaptrude.design.furniture.getCatalogItem("sofa-3-seater");
if (item) {
  console.log(item.name, item.source);
}

---

exists(id)

Test whether a catalog item exists for the given library id.

• Parameters:
  • id: string — The catalog library id
• Returns: boolean — true if it exists, otherwise false

---

getDimensions(item)

Get the dimensions of a PLACED furniture item (a ComponentHandle, not a catalog id) — length along the object, width across it, height vertical, in engine units. Mirrors the Length / Width / Height fields of the furniture properties panel.

Catalog items (listCatalog / getCatalogItem) carry no dimensions: the source .babylon mesh isn't loaded until placement, so a catalog record has no geometry to measure. To size an item, place it (design.create.furniture) and read getDimensions on the returned handle.

• Parameters:
  • item: ComponentHandle — The placed furniture to query
• Returns: PluginFurnitureDimensions | null — The dimensions, or null if the geometry is degenerate

const [item] = await snaptrude.design.query.listFurniture({ isSelected: true });
const dims = await snaptrude.design.furniture.getDimensions(item);
if (dims) console.log(dims.length, dims.width, dims.height);

---

setDimensions(item, dimensions)

Resize a PLACED furniture item along one or more axes — length, width and/or height (engine units). Omitted axes are left unchanged. Each supplied axis is an undoable command, mirroring editing the furniture properties panel. Write-gated and proposal-scoped; throws PRECONDITION_FAILED if the furniture is locked or its geometry is degenerate.

• Parameters:
  • item: ComponentHandle — The placed furniture to resize
  • dimensions: { length?: number; width?: number; height?: number } — New sizes (each optional, engine units, > 0)
• Returns: PluginDesignChangeResult — { affected } — the affected furniture handle(s)

const [item] = await snaptrude.design.query.listFurniture({ isSelected: true });
const { affected } = await snaptrude.design.furniture.setDimensions(item, {
  length: 1800,
  height: 750
});

Errors

Failed calls reject with a typed PluginError — see Error Handling.

The catalog reads are total — a missing or unknown library id yields null (getCatalogItem) or false (exists), never a throw. The catalog is network-backed, so a library fetch failure surfaces as a generic INTERNAL error (report it with its errorId).

getDimensions is a read — it returns null for a non-furniture handle or degenerate geometry, and rejects only on a gone/forged handle (HANDLE_INVALID). setDimensions is a write: it rejects with HANDLE_INVALID (gone/forged), PRECONDITION_FAILED (furniture is locked, has no mesh, or its geometry is degenerate), or VALIDATION (a non-positive size).