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

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

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();

---

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).