Modeling tools
Generated from
openspec/specs/modeling-tools/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”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.
Requirements
Section titled “Requirements”Requirement: Parametric carpentry
Section titled “Requirement: Parametric carpentry”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.
Scenario: Placing a carpentry preset
Section titled “Scenario: Placing a carpentry preset”- 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.
Scenario: Adding a cutout with clearance
Section titled “Scenario: Adding a cutout with clearance”- 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.
Scenario: Anchored unit tracks its asset
Section titled “Scenario: Anchored unit tracks its asset”- WHEN a carpentry unit has
anchorAssetIdset withanchorMode: 'follow'(orfit-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
Scenario: Deleting the anchor asset
Section titled “Scenario: Deleting the anchor asset”- 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
Requirement: Cladding cover-ups
Section titled “Requirement: Cladding cover-ups”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.
Scenario: Placing a false ceiling
Section titled “Scenario: Placing a false ceiling”- WHEN a designer drops a polygon for a false ceiling and sets drop height, rim, and material
- THEN a
false-ceilingcladding 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
Scenario: Placing a plan-curved wall
Section titled “Scenario: Placing a plan-curved wall”- 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-wallcladding entity, and re-selecting the tool withinitialPoints+replaceIdedits 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.
Scenario: Push/Pull with a snap guide
Section titled “Scenario: Push/Pull with a snap guide”- 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
Scenario: Typed numeric distance
Section titled “Scenario: Typed numeric distance”- 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
Solidentity (internal cells such as doors/drawers/shelves are dropped) as one undo step, and the immediate undo restores the original carpentry entity
Requirement: Craft composite assets
Section titled “Requirement: Craft composite assets”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.
Scenario: Saving a craft composite
Section titled “Scenario: Saving a craft composite”- 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
Scenario: Selection-seeded craft
Section titled “Scenario: Selection-seeded craft”- 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-
readyor already-composite items among the selection are skipped
Scenario: Placing a saved craft
Section titled “Scenario: Placing a saved craft”- 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
parentSceneItemIdis the anchor, so moving, rotating, or deleting the anchor moves, rotates, or deletes the whole arrangement as a unit
Requirement: Stacking items on surfaces
Section titled “Requirement: Stacking items on surfaces”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.
Scenario: Stacking a lamp on a side table
Section titled “Scenario: Stacking a lamp on a side table”- WHEN a designer places an asset with
mountType: 'surface'over another placed item - THEN the new item’s
parentSceneItemIdis 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
Requirement: Parametric MEP entities
Section titled “Requirement: Parametric MEP entities”The system SHALL let a designer place parametric MEP entities — plug points/switches, pipes, and wiring — with Singapore HDB default mounting heights.
Scenario: Placing a socket
Section titled “Scenario: Placing a socket”- WHEN a designer places a
plug-pointof 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_PRESETSentry the build tool’s picker offers, rather than from a second table of generated shapes