Editor command reference

🚧

Beta

The command API is in beta: command names, parameters and results may still change between
editor releases. Pin an editor release with the version option of initFPEditor if you depend on it.

Every command of editor release 2.80.1, for api.command(name, payload) and api.transaction(steps). How to call them, what they answer and how GUIDs work is on Editor commands. api.commands() returns the same list as JSON Schema, from the editor you are running.

Lengths and coordinates are in centimetres. x grows to the east (right), y to the south (down).

Walls

set_wall_height

Set a wall's height, measured from each end's own base elevation.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
heightnumber, ≥ 0yesHeight in cm, measured from each end's own base

set_wall_elevation

Raise or lower a wall's base, keeping each end's height.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
elevationnumber, ≥ -400, ≤ 400yesHeight of the wall's base above the floor, cm; negative lowers it

set_wall_thickness

Set a wall's thickness. At zero it can hold no openings, and loses them.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
thicknessnumber, ≥ 0yesThickness in cm; at 0 the wall loses its openings

set_wall_balance

Set which side of its centreline a wall's thickness falls on: 0 right, 0.5 centred, 1 left.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
balancenumber, ≥ 0, ≤ 1yesWhich side of the centreline the thickness falls on, looking from end a towards end b: 0 all to the right, 0.5 centred, 1 all to the left

set_wall_decor

Paint one side of a wall, or both, with a colour or a cached material.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
sideone of 'left', 'right', 'both'yesWhich face: left or right looking from end a towards end b, or both
colorstringPaint colour, e.g. #D04C44; send color OR material, or neither to strip the side bare
materialstringRefid of a material the host has seeded; send material OR color

set_wall_texture

Place an image on one side of a wall, or remove it by omitting src.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
sideone of 'left', 'right'yesWhich face: left or right looking from end a towards end b
srcstringImage URL; omit it to remove the texture
fitone of 'free', 'no-stretch', 'fill', 'contain', 'tile-horizontally', 'tile-vertically', 'tile-both'How the image fills its rectangle
tlxnumberImage rectangle's left edge, cm from the wall face's top-left
tlynumberImage rectangle's top edge, cm from the wall face's top-left
brxnumberImage rectangle's right edge, cm from the wall face's top-left
brynumberImage rectangle's bottom edge, cm from the wall face's top-left

set_wall_material_transform

Scale or rotate the material on one side of a wall, or both. Percentages and degrees.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
sideone of 'left', 'right', 'both'yesWhich face: left or right looking from end a towards end b, or both
sxnumber, ≥ 1, ≤ 1000Horizontal scale, % of the material's own size (100 = as is)
synumber, ≥ 1, ≤ 1000Vertical scale, % of the material's own size (100 = as is)
rotationnumber, ≥ -360, ≤ 360Rotation of the material, degrees

set_wall_trim

Set the trim fields one side of a wall, or both, changes from its room's: each field given replaces the room's for that face, a size of 0 switches that part off there, and a field left out follows the room. Omit trim to remove them so the side follows its room again.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
sideone of 'left', 'right', 'both'yesWhich face: left or right looking from end a towards end b, or both
trimobjectOnly the fields this side changes from its room's, whole: it replaces the side's own. Omit it so the side follows its room again
trim.styleone of 'classic', 'artdeco', 'craftsman', 'modern', 'wainscot', 'shiplap'A named profile family; the sizes beside it are still what is used
trim.skirtingHeightnumber, ≥ 0, ≤ 50Baseboard height; 0 switches it off, cm (0–50)
trim.skirtingThicknessnumber, ≥ 0.5, ≤ 5How far the baseboard stands off the wall, cm (0.5–5)
trim.skirtingColorstring, matching ^#[0-9a-fA-F]{6}$Baseboard colour, e.g. #FFFFFF
trim.skirtingProfileone of 'flat', 'rounded', 'beveled'The baseboard's top edge
trim.panellingHeightnumber, ≥ 0, ≤ 250Paneling height from the floor; 0 switches it off, cm (0–250)
trim.panellingColorstring, matching ^#[0-9a-fA-F]{6}$Paneling colour, e.g. #FFFFFF
trim.panellingTypeone of 'wainscot', 'board-batten', 'shiplap', 'raised-panel'The kind of paneling
trim.panellingHasTopRailbooleanA cap rail along the top of the paneling
trim.moldingDepthnumber, ≥ 0, ≤ 30How far the crown molding reaches out from the wall; 0 switches it off, cm (0–30)
trim.moldingColorstring, matching ^#[0-9a-fA-F]{6}$Crown molding colour, e.g. #FFFFFF
trim.moldingProfileone of 'simple', 'cove', 'crown', 'dentil'The crown molding's profile
trim.casingWidthnumber, ≥ 0, ≤ 20Door and window casing face width; 0 switches casings off, cm (0–20)

move_wall

Move a wall sideways, keeping the walls it meets attached and its openings in place.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
delta{x, y}yesHow far to move the wall, cm; ends that meet other walls slide along them, so facts says where they landed
snapbooleanfalse to put the wall exactly where delta says: no landing on a wall within 1.6 cm. The editor passes false while S is held

split_wall

Split a wall in two at a point, dividing its openings between the halves.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
at{x, y}yesWhere to split, cm; projected onto the wall, so a point near it is enough

set_wall_curve

Bend a wall through a point, or straighten it. apex is the point the wall should pass THROUGH, not the control point — omit it to straighten, and an apex within half the wall's thickness of the straight line straightens it too. facts.control is what was stored.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
apex{x, y}A point the curved wall passes THROUGH, cm (not the control point); omit it to straighten

draw_wall

Draw a wall between two points. Crossing an existing wall splits it; closing a loop makes a room. Each end is corrected onto a wall it almost touches so walls join rather than doubling; facts.snapped says when that happened. An end left a few cm short of a wall joins nothing and leaks the rooms either side into one; a near-miss warning says so, with the point to draw to.

ParameterTypeRequiredDescription
from{x, y}yesStart of the wall's centreline (end a), absolute plan coordinates in cm
to{x, y}yesEnd of the wall's centreline (end b), absolute plan coordinates in cm
thicknessnumber, ≥ 0Thickness in cm; the plan's default if omitted
heightnumber, ≥ 0Height in cm; the plan's default if omitted
elevationnumberHeight of the base above the floor, cm; 0 if omitted
snapbooleanfalse keeps the ends exactly as given instead of joining them onto a wall they almost touch
balancenumber, ≥ 0, ≤ 1Which side of the centreline the thickness falls on, looking from from towards to: 0 right, 0.5 centred (default), 1 left

draw_room

Draw a rectangular room: four walls in one call. width and depth are the INSIDE measurements unless inside is false, matching what the editor shows while you drag. Against another room, give beside {room, side} instead of at: the room goes on that room's wall, sharing it, and keeps its inside size. at is corrected onto a wall it almost touches so the room shares it rather than doubling it; facts.snapped says when that happened.

ParameterTypeRequiredDescription
at{x, y}The room's TOP-LEFT corner (smallest x and y) on the walls' centrelines, cm; not its centre, whatever inside is. Give at or beside
besideobjectDraw it against another room's side, sharing that wall, instead of at a point: the engine places it, and width and depth stay the inside. No room: against the whole plan's side
beside.roomstringGUID of the room, from list_rooms; leave out for the whole plan
beside.sideone of 'north', 'east', 'south', 'west'yesThe neighbour's side the new room goes against
beside.alignone of 'start', 'centre', 'end'Where along that side: start (the north or west end, default), centre or end
beside.offsetnumbercm further along the side from align, towards east or south
widthnumber, ≥ 1yesSize along x, cm; the inside measurement unless inside is false
depthnumber, ≥ 1yesSize along y, cm; the inside measurement unless inside is false
insidebooleantrue (default): width and depth are inside measurements, as the editor shows, so the room grows one wall thickness beyond them; false: centreline measurements
thicknessnumber, ≥ 0Wall thickness in cm; the plan's default if omitted
heightnumber, ≥ 0Wall height in cm; the plan's default if omitted
elevationnumberHeight of the walls' base above the floor, cm; 0 if omitted
snapbooleanfalse keeps at exactly as given instead of joining it onto a wall it almost touches
rolenumberRoomtype number from list_roomtypes, e.g. 0 Living, 2 Kitchen, 3 Bedroom; sets the roomtype's name and colour
customNamestringA label of the room's own, drawn instead of the roomtype's name
colorstringFloor colour, e.g. #CEEDF3; with role it replaces the roomtype's colour
materialstringRefid of a floor material from search_materials

delete_walls

Delete walls; their doors and windows go with them, and a room they bounded is retired or merged with its neighbour. There is no room delete: a wall between two rooms bounds both, so to take a room out, delete the walls that only it uses.

ParameterTypeRequiredDescription
wallsstring[]yesGUIDs of the walls to delete; every one must exist or nothing is deleted

set_wall_name

Give a wall a name of your own, and show or hide it on the plan.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
customNamestringA name of your own, drawn on the plan with showName; "" removes it
showNamebooleantrue: the name is drawn on the plan in 2D

list_walls

List every wall in the plan, or the walls of one room, with its GUID, endpoints, length, thickness, height, elevation, rooms (the room GUID on its left and right side looking from a to b, or "outside") and openings (cm), each with its catalogue name, and for a door its swing: the room it opens into (into), the side looking from a to b, and the hinge end; the GUIDs are what every wall, corner and opening command takes.

Read-only: answers in facts and changes nothing.

ParameterTypeRequiredDescription
roomstringOnly the walls with this room on either side, from list_rooms

open_ends

The wall ends that join nothing, which is why a room does not form: ends, each end within reach cm (default 30) of another wall, with its wall and which end of it (end, a or b, what move_corner takes), where it is (at), the wall it nearly meets (onto), the gap (by, cm) and the point to move it or draw it to (to) to join, where the line of the wall meets the other wall, else the nearest point with turns, the degrees the wall would turn to reach it; a gap between two facing ends is listed once; missing, the ends further from a wall but within 150 cm, where a short wall seems left out (the side of a bay, a jog): draw_wall from at to to there rather than moving the corner; and alone, the ends with no wall within 150 cm (a stub, or a wall that should go on). Nothing is changed: join an end with move_corner or draw_wall to its to.

Read-only: answers in facts and changes nothing.

ParameterTypeRequiredDescription
reachnumbercm: how far short of another wall an end is still listed with it; default 30, at most 100

Corners

move_corner

Move the corner at one wall's end to a new point, keeping every wall that meets it attached. Answers joins, the other walls the corner meets after the move (empty: it meets none, and a room it was to close stays open); landed is set only when the corner was snapped onto a corner or wall within 1.6 cm of to.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
endone of 'a', 'b'yesWhich end of that wall is the corner: its start (a) or its end (b)
to{x, y}yesWhere the corner goes, absolute plan coordinates in cm
snapbooleanfalse to put the corner exactly at to: no landing on a corner or wall within 1.6 cm. The editor passes false while S is held

delete_corner

Remove a redundant corner by merging the two collinear walls that meet at it into one.

ParameterTypeRequiredDescription
wallstringyesGUID of the wall
endone of 'a', 'b'yesWhich end of that wall is the corner to remove: its start (a) or its end (b)

Doors and windows

delete_openings

Delete doors and windows; the wall they were in stays, closed where they were.

ParameterTypeRequiredDescription
openingsstring[]yesGUIDs of the openings to delete; every one must exist or nothing is deleted

set_opening_position

Move an opening along its wall, or to another wall. t is 0 at the wall's a end and 1 at its b end.

ParameterTypeRequiredDescription
openingstringyesGUID of the opening
tnumber, ≥ 0, ≤ 1yesWhere the opening's CENTRE sits along the wall: 0 at end a, 1 at end b
wallstringGUID of the wall

duplicate_opening

Copy an opening onto a wall at a given position, with a fresh GUID.

ParameterTypeRequiredDescription
openingstringyesGUID of the opening
tnumber, ≥ 0, ≤ 1yesWhere the copy's CENTRE sits along the wall: 0 at end a, 1 at end b
wallstringGUID of the wall

add_opening

Put a door or window in a wall, by kind or by refid. t is 0 at the wall's a end and 1 at its b end. Kinds and built-in refids need nothing seeded.

ParameterTypeRequiredDescription
wallstringGUID of the wall; with from and to it may be left out, and the wall they lie on is found
kindone of 'door', 'frontDoor', 'doubleDoor', 'slidingDoor', 'pocketDoor', 'foldingDoor', 'bifoldDoor', 'garageDoor', 'opening', 'window', 'twoPaneWindow', 'threePaneWindow', 'roofWindow', 'glassWall'What to put in the wall: doubleDoor is French doors, opening is an archway with no leaf. Give kind, or refid for an exact variant
refidstringInstead of kind: which door or window exactly, chosen by how the drawing draws it. Doors: "200" leaf drawn fully open with a quarter arc; "205" leaf drawn partly open, about 30 degrees, no full arc; "216" pocket door; "208" or "209" French doors, two leaves drawn as a V; "210" double door swinging both ways; "211" sliding doors; "214" folding; "215" bifold; "223" archway, an opening with no leaf; "212" garage door. Windows: "218" standard, "219" two pane, "220" three pane, "224" glass wall. Or a refid the host has seeded
tnumber, ≥ 0, ≤ 1Where the opening's CENTRE sits along the wall: 0 at end a, 1 at end b. Give t, or from and to
from{x, y}Instead of t: one end of the gap the opening fills, plan cm, on or beside the wall; with to
to{x, y}Instead of t: the other end of the gap; the width defaults to the distance from from
widthnumber, ≥ 1Width in cm; the opening's own default if omitted
znumber, ≥ 0Height of its bottom above the floor, cm (a window sill); its default if omitted
z_heightnumber, ≥ 1Its height in cm; its default if omitted
swing_intostringThe room the door opens into, by GUID, or "outside", or the side of the wall it opens to: north, south, east or west
hingeone of 'a', 'b', 'north', 'south', 'east', 'west'Which end of the wall the door's hinge is nearer: a or b, as for t, or north, south, east or west

set_opening_width

Set an opening's width. Widening one near a wall's end can push it off, which facts.offWall reports.

ParameterTypeRequiredDescription
openingstringyesGUID of the opening
widthnumber, ≥ 1yesNew width in cm, keeping its centre where it is

set_opening_swing

Set which way a door opens: the room it swings into, and which end of the wall its hinge is at. Sliding, pocket and folding doors have no swing and are refused.

ParameterTypeRequiredDescription
openingstringyesGUID of the opening
swing_intostringThe room the door opens into, by GUID, or "outside", or the side of the wall it opens to: north, south, east or west
hingeone of 'a', 'b', 'north', 'south', 'east', 'west'Which end of the wall the door's hinge is nearer: a or b, as for t, or north, south, east or west

set_opening_height

Set an opening's height and how high its bottom is off the floor (a window's sill), in cm. Its top may not pass the wall's top.

ParameterTypeRequiredDescription
openingstringyesGUID of the opening
heightnumber, ≥ 1, ≤ 1000How tall it is, cm
elevationnumber, ≥ -500, ≤ 1000Its bottom's height off the floor, cm: a window's sill, 0 for a door

set_opening_finish

Set a door's or window's frame colour, a door's leaf colour and threshold (a colour or a material refid), and mark a door the front door or an internal one.

ParameterTypeRequiredDescription
openingstringyesGUID of the opening
frame_colorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$The frame, #rrggbb; doors and windows
door_colorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$The leaf, #rrggbb; doors only
materialsobjectAny finish slot the product lists, as {SLOT: value}: a #rrggbb colour or a wood by name (Oak, Cherry, Caramel, Sandalwood, Wood Cherry, Wood Medium, Wood Light, Medium Wood); list_walls shows an opening's slots
thresholdstringA door threshold: a #rrggbb colour, or a material refid from search_materials
front_doorbooleantrue marks it the front door
internal_doorbooleantrue marks it an internal door

set_opening_product

Swap a door or window for another product, by kind or by refid, keeping its place. A catalogue product keeps the plan's size, a built-in one takes its own. A door may become a window and back.

ParameterTypeRequiredDescription
openingstringyesGUID of the opening
kindone of 'door', 'frontDoor', 'doubleDoor', 'slidingDoor', 'pocketDoor', 'foldingDoor', 'bifoldDoor', 'garageDoor', 'opening', 'window', 'twoPaneWindow', 'threePaneWindow', 'roofWindow', 'glassWall'The product by kind, as add_opening takes it; or refid
refidstringInstead of kind: a built-in opening id, or a door or window refid from search_products

set_opening_name

Give a door or window a name of your own, and show or hide it on the plan.

ParameterTypeRequiredDescription
openingstringyesGUID of the opening
customNamestringA name of your own, drawn on the plan with showName; "" removes it
showNamebooleantrue: the name is drawn on the plan in 2D

Rooms

set_room_decor

Paint the inside of every wall around a room with a colour or a cached material, this room's side only, as one change; with replace, only the faces that have that finish now. facts.faces names each wall and side painted.

ParameterTypeRequiredDescription
areastringyesThe room, from list_rooms
colorstringPaint colour, e.g. #D04C44; send color OR material, or neither to strip the faces bare
materialstringRefid of a wall material the host has seeded; send material OR color
wallsstring[]Only these walls of the room (GUIDs from list_rooms), on its own side; leave it out for all
replacestringOnly the faces with this finish now: a colour like #D04C44, a material refid, or "default" for faces with neither; leave it out to paint every face

set_area_trim

Set a room's baseboard, paneling and crown molding, or remove them by omitting trim. Every wall side facing the room follows it unless set_wall_trim gave that side its own.

ParameterTypeRequiredDescription
areastringyesGUID of the area
trimobjectThe room's trim, whole: it replaces what is there. Omit it to remove the trim
trim.styleone of 'classic', 'artdeco', 'craftsman', 'modern', 'wainscot', 'shiplap'A named profile family; the sizes beside it are still what is used
trim.skirtingHeightnumber, ≥ 0, ≤ 50Baseboard height; 0 switches it off, cm (0–50)
trim.skirtingThicknessnumber, ≥ 0.5, ≤ 5How far the baseboard stands off the wall, cm (0.5–5)
trim.skirtingColorstring, matching ^#[0-9a-fA-F]{6}$Baseboard colour, e.g. #FFFFFF
trim.skirtingProfileone of 'flat', 'rounded', 'beveled'The baseboard's top edge
trim.panellingHeightnumber, ≥ 0, ≤ 250Paneling height from the floor; 0 switches it off, cm (0–250)
trim.panellingColorstring, matching ^#[0-9a-fA-F]{6}$Paneling colour, e.g. #FFFFFF
trim.panellingTypeone of 'wainscot', 'board-batten', 'shiplap', 'raised-panel'The kind of paneling
trim.panellingHasTopRailbooleanA cap rail along the top of the paneling
trim.moldingDepthnumber, ≥ 0, ≤ 30How far the crown molding reaches out from the wall; 0 switches it off, cm (0–30)
trim.moldingColorstring, matching ^#[0-9a-fA-F]{6}$Crown molding colour, e.g. #FFFFFF
trim.moldingProfileone of 'simple', 'cove', 'crown', 'dentil'The crown molding's profile
trim.casingWidthnumber, ≥ 0, ≤ 20Door and window casing face width; 0 switches casings off, cm (0–20)

update_area

Change a room's colour, role, name, cutout flag, or whether its name and size are shown. Send everything one action changes in a single call: a colour sent WITH a role keeps the floor material, a colour sent alone removes it.

ParameterTypeRequiredDescription
areastringyesGUID of the area
colorstringFloor colour, e.g. #CEEDF3; sent alone it removes a floor material, sent with role it keeps it
rolenumberRoomtype number only; set_area_roomtype also writes the name and colour
customNamestringA label of your own, drawn instead of the roomtype's name; it does NOT change what kind of room it is: to make a room a Kitchen or a Dining Room, use set_area_roomtype
isCutoutbooleantrue marks the area as not floor, e.g. a void or stairwell
showNamebooleantrue: its name is drawn on the plan in 2D
showAreabooleantrue: its size in m² is drawn on the plan in 2D

set_area_material

Put a floor material in a room, from a refid the host has seeded. To REMOVE one, set the room's colour with update_area, which is what picking a colour does.

ParameterTypeRequiredDescription
areastringyesGUID of the area
refidstringyesRefid of a floor material the host has seeded

set_area_material_transform

Turn, offset or scale a room's floor material. rotation is degrees; sx/sy are percentages; tx/ty shift it. The polygon does not move.

ParameterTypeRequiredDescription
areastringyesGUID of the area
rotationnumberRotation of the floor material, degrees
txnumberHorizontal shift of the material, cm
tynumberVertical shift of the material, cm
sxnumber, ≥ 1Horizontal scale, % of the material's own size (100 = as is)
synumber, ≥ 1Vertical scale, % of the material's own size (100 = as is)

set_area_roomtype

Make a room a named roomtype — Kitchen, Bedroom, Living Room — from a role number the host has seeded. Writes the number, the name the plan LABELS the room with, and the roomtype's colour together; a label of the room's own (customName) still wins, which facts.customNameWins says. Call list_roomtypes for the numbers.

ParameterTypeRequiredDescription
areastringyesGUID of the area
rolenumberyesRoomtype number from list_roomtypes, e.g. 0 Living, 2 Kitchen, 3 Bedroom
setnumberThe room-type set the role is from, when the caller holds one (a picked row's room_type_set_id); without it the role means what list_roomtypes says

set_area_ceiling

Turn a room's ceiling on or off, or give it a colour or a material from a seeded refid.

ParameterTypeRequiredDescription
areastringyesGUID of the area
enabledbooleanfalse: no ceiling in 3D
colorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$The ceiling colour, #rrggbb; replaces a ceiling material
refidstringA material refid the host has seeded; replaces a ceiling colour

list_rooms

List the rooms: the areas the plan derives from closed wall loops, each with its GUID, name, net floor area in m² (holes subtracted), the GUIDs of the walls around it (sidesUnknown: true with an empty list when they could not be matched to its sides), and its roomtype number as role when it has one. A room keeps its GUID while it stays the same room, even when a wall edit changes its shape; it is retired only when an edit splits it in two or merges it with another, which the mutation reports in facts.guids.

Read-only: answers in facts and changes nothing.

No parameters: pass {}.

list_roomtypes

List the roomtypes this host has seeded — the role number, the name a room gets labelled with, and the colour — which are the numbers set_area_roomtype takes. One roomtype per role: where the account's own set reuses a number, its own name is the one listed.

Read-only: answers in facts and changes nothing.

No parameters: pass {}.

describe_room

Describe one room as facts and a sentence to quote: its inside size and colour, each side by compass (north is the top of the plan) with its length, its doors and windows and where each door leads, which sides are outside walls, which are open to another room (a 0 cm divider), its neighbours, and its furniture by name. Computed from the plan as it is; say what this says rather than working it out.

Read-only: answers in facts and changes nothing.

ParameterTypeRequiredDescription
roomstringyesGUID of the room, from list_rooms

check_room

Check a furnished room as a designer would, as the last step of furnishing it: a bed side-on to its wall, a sofa facing a wall or away from its TV, a coffee table out of reach, a bed without a nightstand or with one out of reach, a dining table with no room to pull a chair out, a rug smaller than the sofa on it, a room too full, and a room missing what its type needs (a bedroom with no bed). Answers findings to fix or name in the reply, and checked, what it could check; nothing is changed.

Read-only: answers in facts and changes nothing.

ParameterTypeRequiredDescription
roomstringyesThe room to check, from list_rooms

Furniture and other items

delete_items

Delete placed furniture and fixtures. What stood on a deleted piece drops to what is under it, reported as dropped; deleting part of a product group reports the group and what is left of it.

ParameterTypeRequiredDescription
itemsstring[]yesGUIDs of the items to delete; every one must exist or nothing is deleted

move_item

Move an item to a point, restacking it and anything that was resting on it.

ParameterTypeRequiredDescription
itemstringyesGUID of the item
to{x, y}yesWhere the item's CENTRE goes, absolute plan coordinates in cm

rotate_item

Set an item’s rotation in degrees, restacking it and anything resting on it.

ParameterTypeRequiredDescription
itemstringyesGUID of the item
rotationnumberyesWhich way it faces, degrees clockwise on screen: 0 faces south (down), 180 north; the same for wall art; any value, taken modulo 360

add_item

Add an item from a cached asset at a point. Requires resources.setAssetsCache to be seeded.

ParameterTypeRequiredDescription
refidstringyesAsset id of the product, from a catalogue the host has seeded; not a GUID
at{x, y}yesWhere the item's CENTRE goes, absolute plan coordinates in cm
rotationnumberWhich way it faces, degrees clockwise on screen: 0 faces south (down), 90 west, 180 north, 270 east; the same for wall art; 0 if omitted
rolestringA free-text label for the item's purpose, e.g. 'sofa'; shown on the moodboard
materialsobjectA variant: material slot to material id, as a search row's materials; the product's defaults if omitted
mirroredbooleanPlace it mirrored left to right, for a piece the catalogue has in one hand only

replace_item

Put another product in an item's place: same GUID, position, rotation and role; the new product's size and materials (or materials for a variant); what stood on it follows. The refid must be in the asset cache.

ParameterTypeRequiredDescription
itemstringyesGUID of the item
refidstringyesAsset id of the new product, from a catalogue the host has seeded; may be the same product
materialsobjectA variant: material slot to material id, as a search row's materials; the product's defaults if omitted

mirror_item

Mirror an item where it stands, about its own centre: left to right by default, or front to back. Run it again to undo the flip.

ParameterTypeRequiredDescription
itemstringyesGUID of the item
axisone of 'left-right', 'front-back''left-right' (the default) swaps its left and right; 'front-back' its front and back

set_item_elevation

Set how high a piece's underside is above the floor, in cm. What rests on it moves with it; it is not restacked.

ParameterTypeRequiredDescription
itemstringyesGUID of the item
elevationnumber, ≥ -500, ≤ 1000yesHeight of the piece's underside above the floor, cm; a wall-mounted piece's too

set_item_size

Resize a placed piece, in cm: width across, depth front to back, height. Only a product the catalogue marks resizable; the piece keeps its centre and what no longer fits on top comes down.

ParameterTypeRequiredDescription
itemstringyesGUID of the item
widthnumber, ≥ 1, ≤ 5000across, side to side, cm
depthnumber, ≥ 1, ≤ 5000front to back, cm
heightnumber, ≥ 1, ≤ 5000floor to top, cm

set_item_name

Give a piece a name of your own, and show or hide it on the plan.

ParameterTypeRequiredDescription
itemstringyesGUID of the item
customNamestringA name of your own, drawn on the plan with showName; "" removes it
showNamebooleantrue: the name is drawn on the plan in 2D

list_items

List every piece of furniture and fitting placed in the plan, with its GUID, refid, position, rotation and size in cm; the GUIDs are what move_item, rotate_item and the selection commands take. refid identifies the PRODUCT, so every copy of one product shares it. When the product is in the asset cache, name is its catalogue name and level where it sits: 0-2 on the floor, 3 on a wall, 4 on the ceiling; both are absent for a product not cached.

Read-only: answers in facts and changes nothing.

No parameters: pass {}.

describe_items

Describe furniture as facts and a sentence to quote: per piece its name and size, its room, which wall it stands against and by which side (its back, front or side), which way it faces and whether it is mirrored, what it stands in front of, beside or on (a rug: standsOn), and whether it stands in a door swing, in front of a door whichever way it opens, or in front of a window. Every item in the plan, or those in one room, or the GUIDs you name. Computed from the plan as it is; say what this says rather than working it out.

Read-only: answers in facts and changes nothing.

ParameterTypeRequiredDescription
roomstringOnly the items in this room
itemsstring[]Only these items

Surfaces

delete_surfaces

Delete free-drawn surfaces (rugs of floor, patches of finish). A room's own floor is not one.

ParameterTypeRequiredDescription
surfacesstring[]yesGUIDs of the surfaces to delete; every one must exist or nothing is deleted

move_surface

Move a whole surface by a delta, control points included.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
delta{x, y}yesHow far to move the surface, cm

rotate_surface

Rotate a surface about its own centroid, in degrees. The editor's buttons use 45.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
degreesnumberyesDegrees to turn about its centroid, clockwise on screen

mirror_surface

Mirror a surface about its centroid. 'y' flips left-to-right, 'x' top-to-bottom.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
aboutone of 'x', 'y'yes'y' flips left-to-right, 'x' flips top-to-bottom

move_surface_vertex

Move one corner of a surface to a point.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
indexnumberyesCorner number, from list_surfaces
to{x, y}yesWhere the corner goes, absolute plan coordinates in cm

move_surface_edge

Drag one edge of a surface sideways, stretching the two edges beside it.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
indexnumberyesEdge number: edge i runs from corner i to corner i+1 (list_surfaces numbers them)
to{x, y}yesA point the moved edge will pass through, cm; its neighbours stretch to meet it

add_surface_vertex

Add a corner on one edge of a surface, splitting the curve if that edge has one.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
indexnumberyesEdge number: edge i runs from corner i to corner i+1 (list_surfaces numbers them)
at{x, y}yesThe new corner, cm, placed exactly as given

dissolve_surface_edge

Remove one edge of a surface, merging its corners where their neighbours meet.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
indexnumberyesEdge number: edge i runs from corner i to corner i+1 (list_surfaces numbers them)

set_surface_edge_apex

Curve one edge so its apex sits at a point — or straighten it, if that is on the chord.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
indexnumberyesEdge number: edge i runs from corner i to corner i+1 (list_surfaces numbers them)
apex{x, y}yesA point the curved edge passes THROUGH, cm; a point on the straight line straightens it

set_surface_elevation

Move a surface to a height, or set one corner's. Without a corner the whole surface moves so its lowest point lands at z, keeping its shape, its ridges and its openings.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
znumberyesHeight in cm. May be negative.
indexnumberOne corner to raise, from list_surfaces. Omit it to MOVE the whole surface so its lowest point sits at z, which keeps the shape it has.

duplicate_surface

Copy a surface, offset by 25cm, with a fresh GUID.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
offset{x, y}Where the copy goes relative to the original, cm; 25 cm right and down if omitted

draw_surface

Paint a surface: a floor region of any outline, given its corners in order around the shape. It has no walls and is not a room. Grey unless a colour is given. Returns {surface, m2, corners, centroid}.

ParameterTypeRequiredDescription
points{x, y}[]yesThe corners in order around the shape, absolute plan cm, at least 3; the outline closes itself
points[].xnumberyes
points[].ynumberyes
colorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$Fill colour, e.g. #c8b89a
namestringA name for the surface
elevationnumberHeight above the floor in cm; 0 if omitted

update_surface

Set what a surface's Settings panel sets: its name and whether its name and size are shown, its 2D transparency, hidden in 3D, a dotted outline, a cut-out, a roof, its thickness.

ParameterTypeRequiredDescription
surfacestringyesGUID of the surface
transparencynumber, ≥ 0, ≤ 100How see-through it is in 2D, %
hideIn3Dbooleantrue: drawn in 2D only
dottedOutlinebooleantrue: a dotted edge in 2D
isCutoutbooleantrue: a hole in what is under it, e.g. a stairwell; drops its finish, name and role
isRoofbooleantrue: drawn as a roof
thicknessnumber, ≥ 0, ≤ 200Slab thickness, cm
customNamestringA name of your own, drawn instead of its roomtype name
showNamebooleantrue: its name is drawn on the plan in 2D
showAreabooleantrue: its size in m² is drawn on the plan in 2D

list_surfaces

List the painted surfaces — floor and ceiling regions, not rooms — each with its GUID, name, colour, area in m², the centroid that rotate and mirror pivot about, and its corners and edges numbered. The numbering is the point: move_surface_vertex and set_surface_elevation take a CORNER index, while move_surface_edge, add_surface_vertex, dissolve_surface_edge and set_surface_edge_apex take an EDGE index, and edge i runs from corner i to the next.

Read-only: answers in facts and changes nothing.

No parameters: pass {}.

Lines

delete_lines

Delete free-standing lines drawn on the plan, not walls.

ParameterTypeRequiredDescription
linesstring[]yesGUIDs of the lines to delete; every one must exist or nothing is deleted

draw_line

Draw a free-standing line on the plan: an annotation, not a wall, so it bounds no room. Solid, black and 2 thick unless a style, thickness or colour is given. Returns {line, a, b, length, style, thickness}.

ParameterTypeRequiredDescription
from{x, y}yesOne end, absolute plan coordinates in cm
to{x, y}yesThe other end, absolute plan coordinates in cm
styleone of 'solid', 'dashed', 'dotted', 'dashdotted'How the line is drawn
thicknessnumber, ≥ 1, ≤ 10Stroke thickness, 1 to 10, as the line panel offers
colorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$Stroke colour, e.g. #000000

update_line

Change a line's ends, style, thickness or colour; what is not given stays. Returns the line as draw_line does.

ParameterTypeRequiredDescription
linestringyesGUID of the line
from{x, y}New position of end a, plan cm
to{x, y}New position of end b, plan cm
styleone of 'solid', 'dashed', 'dotted', 'dashdotted'How the line is drawn
thicknessnumber, ≥ 1, ≤ 10Stroke thickness, 1 to 10, as the line panel offers
colorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$Stroke colour, e.g. #000000

list_lines

List the free-standing lines drawn on the plan — not walls — with GUID, ends, length and thickness in cm; a curved line also reports its control point.

Read-only: answers in facts and changes nothing.

No parameters: pass {}.

Labels

delete_labels

Delete text labels from the plan.

ParameterTypeRequiredDescription
labelsstring[]yesGUIDs of the labels to delete; every one must exist or nothing is deleted

add_label

Put a text label on the plan at a point. 20 px black Arial on a grey box, left aligned, unless styled. Returns {label, at, fontSize, rotation}.

ParameterTypeRequiredDescription
textstring, matching \SyesWhat the label says; not empty
at{x, y}yesWhere the label stands, absolute plan coordinates in cm
fontSizenumber, ≥ 5, ≤ 500Text size, 5 to 500
alignone of 'left', 'center', 'right'How the text lines up on its point
rotationnumber, ≥ -180, ≤ 180Degrees clockwise, -180 to 180
fontColorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$Text colour, e.g. #000000
backgroundColorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$Colour of the box behind the text
boldbooleanBold text
italicbooleanItalic text
outlinebooleanAn outline round the text
letterSpacingnumber, ≥ 0, ≤ 100Space between letters, 0 to 100

update_label

Change a label's text, place or style; what is not given stays. Returns the label as add_label does.

ParameterTypeRequiredDescription
labelstringyesGUID of the label
textstring, matching \SNew text; not empty
at{x, y}New position, plan cm
fontSizenumber, ≥ 5, ≤ 500Text size, 5 to 500
alignone of 'left', 'center', 'right'How the text lines up on its point
rotationnumber, ≥ -180, ≤ 180Degrees clockwise, -180 to 180
fontColorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$Text colour, e.g. #000000
backgroundColorstring, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$Colour of the box behind the text
boldbooleanBold text
italicbooleanItalic text
outlinebooleanAn outline round the text
letterSpacingnumber, ≥ 0, ≤ 100Space between letters, 0 to 100

list_labels

List every free text label with its GUID, text, position and rotation (cm and degrees); the GUIDs are what move_selection and duplicate_selection take.

Read-only: answers in facts and changes nothing.

No parameters: pass {}.

Dimensions

delete_dimensions

Delete custom dimension lines; the generated ones follow the walls and the dimension settings.

ParameterTypeRequiredDescription
dimensionsstring[]yesGUIDs of the dimensions to delete; every one must exist or nothing is deleted

add_dimension

Draw a dimension line between two points; the plan shows the distance between them. It is drawn where its ends are, so put them a little way off a wall to keep it clear of it. Returns {dimension, a, b, length}.

ParameterTypeRequiredDescription
from{x, y}yesOne end, absolute plan coordinates in cm
to{x, y}yesThe other end, absolute plan coordinates in cm
textstring, matching \SText shown instead of the measured length; omit it to show the length

list_dimensions

List the custom dimension lines someone drew, with GUID, ends, length in cm and any typed text; the automatic dimensions are not included because they are derived and carry no GUID.

Read-only: answers in facts and changes nothing.

No parameters: pass {}.

Selection

delete_selection

Delete several kinds at once, as one change: items, surfaces, lines, labels, dimensions, openings and walls by GUID. Reports removed per kind, rooms included. There is no room delete: list its walls.

ParameterTypeRequiredDescription
selectionobjectyesWhat to delete, as GUID lists per kind; at least one kind must name something
selection.itemsstring[]GUIDs of the items to delete; every one must exist or nothing is deleted
selection.surfacesstring[]GUIDs of the surfaces to delete; every one must exist or nothing is deleted
selection.linesstring[]GUIDs of the lines to delete; every one must exist or nothing is deleted
selection.labelsstring[]GUIDs of the labels to delete; every one must exist or nothing is deleted
selection.dimensionsstring[]GUIDs of the dimensions to delete; every one must exist or nothing is deleted
selection.openingsstring[]GUIDs of the openings to delete; every one must exist or nothing is deleted
selection.wallsstring[]GUIDs of the walls to delete; every one must exist or nothing is deleted

move_selection

Move, flip or rotate a group of objects together, replacing them where they were.

ParameterTypeRequiredDescription
selectionobjectyesWhat to transform, as GUID lists per kind; at least one kind must name something
selection.itemsstring[]GUIDs of the items in the group
selection.linesstring[]GUIDs of the lines in the group
selection.wallsstring[]GUIDs of the walls in the group
selection.areasstring[]GUIDs of the areas in the group
selection.labelsstring[]GUIDs of the labels in the group
selection.camerasstring[]GUIDs of the cameras in the group
selection.surfacesstring[]GUIDs of the surfaces in the group
selection.dimensionsstring[]GUIDs of the dimensions in the group
delta{x, y}How far to move the group, cm; applied first
rotationnumberDegrees to turn the group about its bounding box's centre, clockwise on screen; applied last
flip{x, y}Mirror about the group's centre: x 1 mirrors left-right, y 1 mirrors top-bottom; both is a 180° turn
excludedobjectKinds to leave where they are; excluding walls excludes their rooms too
excluded.itemsbooleantrue leaves the selected items behind
excluded.linesbooleantrue leaves the selected lines behind
excluded.wallsbooleantrue leaves the selected walls behind
excluded.areasbooleantrue leaves the selected areas behind
excluded.labelsbooleantrue leaves the selected labels behind
excluded.camerasbooleantrue leaves the selected cameras behind
excluded.surfacesbooleantrue leaves the selected surfaces behind
excluded.dimensionsbooleantrue leaves the selected dimensions behind

duplicate_selection

Copy a group of objects, transformed, with fresh GUIDs, leaving the originals.

ParameterTypeRequiredDescription
selectionobjectyesWhat to transform, as GUID lists per kind; at least one kind must name something
selection.itemsstring[]GUIDs of the items in the group
selection.linesstring[]GUIDs of the lines in the group
selection.wallsstring[]GUIDs of the walls in the group
selection.areasstring[]GUIDs of the areas in the group
selection.labelsstring[]GUIDs of the labels in the group
selection.camerasstring[]GUIDs of the cameras in the group
selection.surfacesstring[]GUIDs of the surfaces in the group
selection.dimensionsstring[]GUIDs of the dimensions in the group
delta{x, y}How far to move the group, cm; applied first
rotationnumberDegrees to turn the group about its bounding box's centre, clockwise on screen; applied last
flip{x, y}Mirror about the group's centre: x 1 mirrors left-right, y 1 mirrors top-bottom; both is a 180° turn
excludedobjectKinds to leave where they are; excluding walls excludes their rooms too
excluded.itemsbooleantrue leaves the selected items behind
excluded.linesbooleantrue leaves the selected lines behind
excluded.wallsbooleantrue leaves the selected walls behind
excluded.areasbooleantrue leaves the selected areas behind
excluded.labelsbooleantrue leaves the selected labels behind
excluded.camerasbooleantrue leaves the selected cameras behind
excluded.surfacesbooleantrue leaves the selected surfaces behind
excluded.dimensionsbooleantrue leaves the selected dimensions behind

The whole design

clear_design

Empty the design: walls, rooms, items, surfaces, labels, lines and dimensions. Cameras are kept, as the toolbar button keeps them, and so is the sketch (the drawing under the plan, to trace), which the toolbar button removes. Every GUID in the plan is retired.

Removes work the user may want to keep; ask before you call it.

No parameters: pass {}.

scale_plan

Scale the whole plan about a point: lengths and positions grow or shrink, thicknesses, opening widths and item sizes stay.

ParameterTypeRequiredDescription
factornumberHow much bigger, e.g. 1.1 for 10% bigger, 0.9 for 10% smaller
roomstringA room whose true floor area you know; give m2 with it
m2numberThe room's true floor area, m2
wallstringA wall whose true length you know; give length with it
lengthnumberThe wall's true length along its centreline, cm
about{x, y}The point that stays put, cm; the plan's centre if omitted

Cameras

list_cameras

List the saved cameras with GUID, name, type (orbital or walkthrough), position, direction and field of view; these are the 3D viewpoints, not the 2D view.

Read-only: answers in facts and changes nothing.

No parameters: pass {}.