Skip to content

Modeling tools

Generated from openspec/specs/modeling-tools/spec.md — edit that file, not this page.

Modeling tools are the “custom build” layer of the floorplan editor — everything a designer models in place rather than picks from the catalog: parametric carpentry, cladding cover-ups (box covers, panels, false ceilings, curved walls), SketchUp-style free-form solid editing, Craft composite assets, stacking of items on surfaces, and parametric MEP (plug points, switches, pipes, wiring). All of it is Yjs-backed via the Floorplan facade, so every gesture is collaborative and a single undo step.

The system SHALL let a designer place and configure a parametric carpentry unit (wardrobe, kitchen run, TV console, shower enclosure, etc.) as a box carcass with a configurable rows × columns grid of cells, each cell typed as open, door, or drawer.

  • WHEN a designer places a carpentry preset (e.g. bookshelf, wardrobe, kitchen base/wall) from CARPENTRY_PRESETS
  • THEN a carcass with the preset’s default dimensions and cell grid is added to the floorplan as one undo step, editable afterward via the inspector’s dims, grid, and per-cell material controls

Scenario: Adding a bay or repeating a column

Section titled “Scenario: Adding a bay or repeating a column”
  • WHEN a designer uses “Add bay ◀/▶”, “Repeat × N”, or “Duplicate col” on a selected carpentry unit
  • THEN the carcass grid is extended or duplicated accordingly, and cutouts/countertop stay consistent with the new grid

Requirement: Carpentry CSG cutouts and countertops

Section titled “Requirement: Carpentry CSG cutouts and countertops”

The system SHALL support up to 6 CSG cutouts (niche, through-box, cylinder) per carpentry unit, subtracted from the carcass, plus an optional countertop rendered as part of the unit.

  • WHEN a designer adds a cutout to a carpentry unit via the cutouts editor
  • THEN the cutout is subtracted from the carcass mesh, its ghost is clamped to the carcass bounds, and clearance dimensions plus wall-snap feedback are shown (bypassable by holding Alt)

Requirement: Carpentry anchoring to a furniture asset

Section titled “Requirement: Carpentry anchoring to a furniture asset”

The system SHALL let a carpentry unit anchor its pose to a furniture asset (“build shelving around this TV”), deriving the carpentry’s position from the asset’s live pose rather than storing it independently.

  • WHEN a carpentry unit has anchorAssetId set with anchorMode: 'follow' (or fit-width / fit-around) and the anchor asset is moved
  • THEN the carpentry unit’s world pose is recomputed from the asset’s new pose on the next snapshot read, without the designer manually repositioning the carpentry
  • WHEN the furniture asset a carpentry unit is anchored to is deleted
  • THEN the carpentry unit’s last-resolved world pose is baked back into its stored fields so it remains in place, un-anchored

The system SHALL let a designer place box covers, composite wall panels (including half-glass), false ceilings, plan-curved walls, and elevation-curved feature walls as distinct cladding entities.

  • WHEN a designer drops a polygon for a false ceiling and sets drop height, rim, and material
  • THEN a false-ceiling cladding entity is created with that footprint, and re-opening the same tool on an existing ceiling edits its shape rather than creating a new one
  • WHEN a designer places a curved wall by dropping floor control points
  • THEN a Catmull-Rom curve through those points is extruded straight up into a curved-wall cladding entity, and re-selecting the tool with initialPoints + replaceId edits the same curve in place

Scenario: Placing an elevation-curved feature wall

Section titled “Scenario: Placing an elevation-curved feature wall”
  • WHEN a designer places a curved-profile wall and edits its vertical profile control points (plus optional horizontal bow, top profile, glass, or up to 4 rectangular apertures)
  • THEN the wall renders as a tessellated curved mesh reflecting the profile, editable via the profile editor in the inspector

Requirement: SketchUp-style solid modeling

Section titled “Requirement: SketchUp-style solid modeling”

The system SHALL let a designer place free-form mesh primitives (cube, sphere, cylinder, pyramid) and edit them with Push/Pull, Move Vertex, and Move Edge operations, assisted by an inferencing/snap engine and numeric typed-value input, with each gesture committing as one undo step.

  • WHEN a designer drags a face with the Push/Pull tool near an aligned edge or vertex on another solid
  • THEN an extension or intersection snap guide appears and the drag pulls to that snapped value; releasing commits one undo step
  • WHEN a designer types a number during a Push/Pull, Move Vertex, or Move Edge drag
  • THEN the operation applies that exact distance instead of the freehand cursor position

Requirement: Carpentry-to-solid conversion

Section titled “Requirement: Carpentry-to-solid conversion”

The system SHALL let a designer convert a carpentry carcass into a free-form Solid for further mesh editing.

Scenario: Making a carpentry unit editable

Section titled “Scenario: Making a carpentry unit editable”
  • WHEN a designer chooses “◇ Make editable” on a selected carpentry unit
  • THEN the carcass shape becomes a Solid entity (internal cells such as doors/drawers/shelves are dropped) as one undo step, and the immediate undo restores the original carpentry entity

The system SHALL let a designer arrange existing catalog assets in an in-editor workspace and save the arrangement as one new reusable catalog asset.

  • WHEN a designer opens the Craft overlay (sidebar tile or , shortcut), arranges 2 or more ready catalog assets, and saves
  • THEN a new catalog asset is created with gltfUrl=null, composition.children[] referencing each placed asset’s id/position/rotation (max 32, no nesting), a composed bounding-box dimension, and a client-rendered composite thumbnail
  • WHEN a designer selects one or more scene items in the editor and then opens Craft
  • THEN the Craft overlay is pre-populated with those items positioned relative to their selection centroid, and any non-ready or already-composite items among the selection are skipped
  • WHEN a designer places a craft composite asset into the scene
  • THEN an invisible anchor SceneItem is created with each composite child fanned out as a SceneItem whose parentSceneItemId is the anchor, so moving, rotating, or deleting the anchor moves, rotates, or deletes the whole arrangement as a unit

The system SHALL let a designer place a surface-mountable asset on top of another placed item so it follows that item’s pose, and let carpentry countertops act as a placement surface without creating a parent/child link.

  • WHEN a designer places an asset with mountType: 'surface' over another placed item
  • THEN the new item’s parentSceneItemId is set to the item underneath, and moving or rotating the parent carries the stacked item with it

Scenario: Placing an item on a carpentry countertop

Section titled “Scenario: Placing an item on a carpentry countertop”
  • WHEN a designer places an item over a carpentry unit’s countertop/worktop
  • THEN the item is placed at the worktop’s world height as an unparented SceneItem, and subsequently moving the carpentry unit does not move the item

The system SHALL let a designer place parametric MEP entities — plug points/switches, pipes, and wiring — with Singapore HDB default mounting heights.

  • WHEN a designer places a plug-point of type socket via the MEP placement tool
  • THEN it is placed at the default 300 mm mounting height (1100 mm for a switch) and rendered by the MEP layer

Requirement: Generated joinery is an ordinary carpentry unit

Section titled “Requirement: Generated joinery is an ordinary carpentry unit”

Carpentry a furnishing action builds SHALL be the same entity a designer places by hand — no generated-only kind, flag or edit path. Once built, it SHALL be selectable, inspectable and editable by every control that applies to hand-placed carpentry.

Scenario: A generated run is edited like any other

Section titled “Scenario: A generated run is edited like any other”
  • WHEN a designer selects a cabinet run that furnishing built
  • THEN the carpentry inspector opens with its dims, grid, cells, countertop and material controls, exactly as for a unit placed with the build tool

Scenario: Bay edits apply to a generated run

Section titled “Scenario: Bay edits apply to a generated run”
  • WHEN a designer uses “Add bay ◀/▶”, “Repeat × N” or “Duplicate col” on a generated cabinet run
  • THEN the edit applies on the same terms as it would to a hand-placed unit

Scenario: Generated runs come from the shared preset table

Section titled “Scenario: Generated runs come from the shared preset table”
  • WHEN furnishing builds a kitchen base or wall run
  • THEN its carcass, grid and cell layout come from the same CARPENTRY_PRESETS entry the build tool’s picker offers, rather than from a second table of generated shapes