BetaThe command API is in beta: command names, parameters and results may still change between
editor releases. Pin an editor release with theversionoption ofinitFPEditorif 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_wall_heightSet a wall's height, measured from each end's own base elevation.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
height | number, ≥ 0 | yes | Height in cm, measured from each end's own base |
set_wall_elevation
set_wall_elevationRaise or lower a wall's base, keeping each end's height.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
elevation | number, ≥ -400, ≤ 400 | yes | Height of the wall's base above the floor, cm; negative lowers it |
set_wall_thickness
set_wall_thicknessSet a wall's thickness. At zero it can hold no openings, and loses them.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
thickness | number, ≥ 0 | yes | Thickness in cm; at 0 the wall loses its openings |
set_wall_balance
set_wall_balanceSet which side of its centreline a wall's thickness falls on: 0 right, 0.5 centred, 1 left.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
balance | number, ≥ 0, ≤ 1 | yes | Which 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
set_wall_decorPaint one side of a wall, or both, with a colour or a cached material.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
side | one of 'left', 'right', 'both' | yes | Which face: left or right looking from end a towards end b, or both |
color | string | Paint colour, e.g. #D04C44; send color OR material, or neither to strip the side bare | |
material | string | Refid of a material the host has seeded; send material OR color |
set_wall_texture
set_wall_texturePlace an image on one side of a wall, or remove it by omitting src.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
side | one of 'left', 'right' | yes | Which face: left or right looking from end a towards end b |
src | string | Image URL; omit it to remove the texture | |
fit | one of 'free', 'no-stretch', 'fill', 'contain', 'tile-horizontally', 'tile-vertically', 'tile-both' | How the image fills its rectangle | |
tlx | number | Image rectangle's left edge, cm from the wall face's top-left | |
tly | number | Image rectangle's top edge, cm from the wall face's top-left | |
brx | number | Image rectangle's right edge, cm from the wall face's top-left | |
bry | number | Image rectangle's bottom edge, cm from the wall face's top-left |
set_wall_material_transform
set_wall_material_transformScale or rotate the material on one side of a wall, or both. Percentages and degrees.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
side | one of 'left', 'right', 'both' | yes | Which face: left or right looking from end a towards end b, or both |
sx | number, ≥ 1, ≤ 1000 | Horizontal scale, % of the material's own size (100 = as is) | |
sy | number, ≥ 1, ≤ 1000 | Vertical scale, % of the material's own size (100 = as is) | |
rotation | number, ≥ -360, ≤ 360 | Rotation of the material, degrees |
set_wall_trim
set_wall_trimSet 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
side | one of 'left', 'right', 'both' | yes | Which face: left or right looking from end a towards end b, or both |
trim | object | Only 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.style | one of 'classic', 'artdeco', 'craftsman', 'modern', 'wainscot', 'shiplap' | A named profile family; the sizes beside it are still what is used | |
trim.skirtingHeight | number, ≥ 0, ≤ 50 | Baseboard height; 0 switches it off, cm (0–50) | |
trim.skirtingThickness | number, ≥ 0.5, ≤ 5 | How far the baseboard stands off the wall, cm (0.5–5) | |
trim.skirtingColor | string, matching ^#[0-9a-fA-F]{6}$ | Baseboard colour, e.g. #FFFFFF | |
trim.skirtingProfile | one of 'flat', 'rounded', 'beveled' | The baseboard's top edge | |
trim.panellingHeight | number, ≥ 0, ≤ 250 | Paneling height from the floor; 0 switches it off, cm (0–250) | |
trim.panellingColor | string, matching ^#[0-9a-fA-F]{6}$ | Paneling colour, e.g. #FFFFFF | |
trim.panellingType | one of 'wainscot', 'board-batten', 'shiplap', 'raised-panel' | The kind of paneling | |
trim.panellingHasTopRail | boolean | A cap rail along the top of the paneling | |
trim.moldingDepth | number, ≥ 0, ≤ 30 | How far the crown molding reaches out from the wall; 0 switches it off, cm (0–30) | |
trim.moldingColor | string, matching ^#[0-9a-fA-F]{6}$ | Crown molding colour, e.g. #FFFFFF | |
trim.moldingProfile | one of 'simple', 'cove', 'crown', 'dentil' | The crown molding's profile | |
trim.casingWidth | number, ≥ 0, ≤ 20 | Door and window casing face width; 0 switches casings off, cm (0–20) |
move_wall
move_wallMove a wall sideways, keeping the walls it meets attached and its openings in place.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
delta | {x, y} | yes | How far to move the wall, cm; ends that meet other walls slide along them, so facts says where they landed |
snap | boolean | false 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_wallSplit a wall in two at a point, dividing its openings between the halves.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
at | {x, y} | yes | Where to split, cm; projected onto the wall, so a point near it is enough |
set_wall_curve
set_wall_curveBend 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID 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_wallDraw 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
from | {x, y} | yes | Start of the wall's centreline (end a), absolute plan coordinates in cm |
to | {x, y} | yes | End of the wall's centreline (end b), absolute plan coordinates in cm |
thickness | number, ≥ 0 | Thickness in cm; the plan's default if omitted | |
height | number, ≥ 0 | Height in cm; the plan's default if omitted | |
elevation | number | Height of the base above the floor, cm; 0 if omitted | |
snap | boolean | false keeps the ends exactly as given instead of joining them onto a wall they almost touch | |
balance | number, ≥ 0, ≤ 1 | Which side of the centreline the thickness falls on, looking from from towards to: 0 right, 0.5 centred (default), 1 left |
draw_room
draw_roomDraw 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
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 | |
beside | object | Draw 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.room | string | GUID of the room, from list_rooms; leave out for the whole plan | |
beside.side | one of 'north', 'east', 'south', 'west' | yes | The neighbour's side the new room goes against |
beside.align | one of 'start', 'centre', 'end' | Where along that side: start (the north or west end, default), centre or end | |
beside.offset | number | cm further along the side from align, towards east or south | |
width | number, ≥ 1 | yes | Size along x, cm; the inside measurement unless inside is false |
depth | number, ≥ 1 | yes | Size along y, cm; the inside measurement unless inside is false |
inside | boolean | true (default): width and depth are inside measurements, as the editor shows, so the room grows one wall thickness beyond them; false: centreline measurements | |
thickness | number, ≥ 0 | Wall thickness in cm; the plan's default if omitted | |
height | number, ≥ 0 | Wall height in cm; the plan's default if omitted | |
elevation | number | Height of the walls' base above the floor, cm; 0 if omitted | |
snap | boolean | false keeps at exactly as given instead of joining it onto a wall it almost touches | |
role | number | Roomtype number from list_roomtypes, e.g. 0 Living, 2 Kitchen, 3 Bedroom; sets the roomtype's name and colour | |
customName | string | A label of the room's own, drawn instead of the roomtype's name | |
color | string | Floor colour, e.g. #CEEDF3; with role it replaces the roomtype's colour | |
material | string | Refid of a floor material from search_materials |
delete_walls
delete_wallsDelete 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
walls | string[] | yes | GUIDs of the walls to delete; every one must exist or nothing is deleted |
set_wall_name
set_wall_nameGive a wall a name of your own, and show or hide it on the plan.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
customName | string | A name of your own, drawn on the plan with showName; "" removes it | |
showName | boolean | true: the name is drawn on the plan in 2D |
list_walls
list_wallsList 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
room | string | Only the walls with this room on either side, from list_rooms |
open_ends
open_endsThe 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
reach | number | cm: how far short of another wall an end is still listed with it; default 30, at most 100 |
Corners
move_corner
move_cornerMove 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
end | one of 'a', 'b' | yes | Which end of that wall is the corner: its start (a) or its end (b) |
to | {x, y} | yes | Where the corner goes, absolute plan coordinates in cm |
snap | boolean | false 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
delete_cornerRemove a redundant corner by merging the two collinear walls that meet at it into one.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | yes | GUID of the wall |
end | one of 'a', 'b' | yes | Which end of that wall is the corner to remove: its start (a) or its end (b) |
Doors and windows
delete_openings
delete_openingsDelete doors and windows; the wall they were in stays, closed where they were.
| Parameter | Type | Required | Description |
|---|---|---|---|
openings | string[] | yes | GUIDs of the openings to delete; every one must exist or nothing is deleted |
set_opening_position
set_opening_positionMove an opening along its wall, or to another wall. t is 0 at the wall's a end and 1 at its b end.
| Parameter | Type | Required | Description |
|---|---|---|---|
opening | string | yes | GUID of the opening |
t | number, ≥ 0, ≤ 1 | yes | Where the opening's CENTRE sits along the wall: 0 at end a, 1 at end b |
wall | string | GUID of the wall |
duplicate_opening
duplicate_openingCopy an opening onto a wall at a given position, with a fresh GUID.
| Parameter | Type | Required | Description |
|---|---|---|---|
opening | string | yes | GUID of the opening |
t | number, ≥ 0, ≤ 1 | yes | Where the copy's CENTRE sits along the wall: 0 at end a, 1 at end b |
wall | string | GUID of the wall |
add_opening
add_openingPut 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
wall | string | GUID of the wall; with from and to it may be left out, and the wall they lie on is found | |
kind | one 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 | |
refid | string | Instead 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 | |
t | number, ≥ 0, ≤ 1 | Where 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 | |
width | number, ≥ 1 | Width in cm; the opening's own default if omitted | |
z | number, ≥ 0 | Height of its bottom above the floor, cm (a window sill); its default if omitted | |
z_height | number, ≥ 1 | Its height in cm; its default if omitted | |
swing_into | string | The room the door opens into, by GUID, or "outside", or the side of the wall it opens to: north, south, east or west | |
hinge | one 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_opening_widthSet an opening's width. Widening one near a wall's end can push it off, which facts.offWall reports.
| Parameter | Type | Required | Description |
|---|---|---|---|
opening | string | yes | GUID of the opening |
width | number, ≥ 1 | yes | New width in cm, keeping its centre where it is |
set_opening_swing
set_opening_swingSet 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
opening | string | yes | GUID of the opening |
swing_into | string | The room the door opens into, by GUID, or "outside", or the side of the wall it opens to: north, south, east or west | |
hinge | one 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_opening_heightSet 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
opening | string | yes | GUID of the opening |
height | number, ≥ 1, ≤ 1000 | How tall it is, cm | |
elevation | number, ≥ -500, ≤ 1000 | Its bottom's height off the floor, cm: a window's sill, 0 for a door |
set_opening_finish
set_opening_finishSet 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
opening | string | yes | GUID of the opening |
frame_color | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | The frame, #rrggbb; doors and windows | |
door_color | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | The leaf, #rrggbb; doors only | |
materials | object | Any 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 | |
threshold | string | A door threshold: a #rrggbb colour, or a material refid from search_materials | |
front_door | boolean | true marks it the front door | |
internal_door | boolean | true marks it an internal door |
set_opening_product
set_opening_productSwap 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
opening | string | yes | GUID of the opening |
kind | one 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 | |
refid | string | Instead of kind: a built-in opening id, or a door or window refid from search_products |
set_opening_name
set_opening_nameGive a door or window a name of your own, and show or hide it on the plan.
| Parameter | Type | Required | Description |
|---|---|---|---|
opening | string | yes | GUID of the opening |
customName | string | A name of your own, drawn on the plan with showName; "" removes it | |
showName | boolean | true: the name is drawn on the plan in 2D |
Rooms
set_room_decor
set_room_decorPaint 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
area | string | yes | The room, from list_rooms |
color | string | Paint colour, e.g. #D04C44; send color OR material, or neither to strip the faces bare | |
material | string | Refid of a wall material the host has seeded; send material OR color | |
walls | string[] | Only these walls of the room (GUIDs from list_rooms), on its own side; leave it out for all | |
replace | string | Only 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_area_trimSet 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
area | string | yes | GUID of the area |
trim | object | The room's trim, whole: it replaces what is there. Omit it to remove the trim | |
trim.style | one of 'classic', 'artdeco', 'craftsman', 'modern', 'wainscot', 'shiplap' | A named profile family; the sizes beside it are still what is used | |
trim.skirtingHeight | number, ≥ 0, ≤ 50 | Baseboard height; 0 switches it off, cm (0–50) | |
trim.skirtingThickness | number, ≥ 0.5, ≤ 5 | How far the baseboard stands off the wall, cm (0.5–5) | |
trim.skirtingColor | string, matching ^#[0-9a-fA-F]{6}$ | Baseboard colour, e.g. #FFFFFF | |
trim.skirtingProfile | one of 'flat', 'rounded', 'beveled' | The baseboard's top edge | |
trim.panellingHeight | number, ≥ 0, ≤ 250 | Paneling height from the floor; 0 switches it off, cm (0–250) | |
trim.panellingColor | string, matching ^#[0-9a-fA-F]{6}$ | Paneling colour, e.g. #FFFFFF | |
trim.panellingType | one of 'wainscot', 'board-batten', 'shiplap', 'raised-panel' | The kind of paneling | |
trim.panellingHasTopRail | boolean | A cap rail along the top of the paneling | |
trim.moldingDepth | number, ≥ 0, ≤ 30 | How far the crown molding reaches out from the wall; 0 switches it off, cm (0–30) | |
trim.moldingColor | string, matching ^#[0-9a-fA-F]{6}$ | Crown molding colour, e.g. #FFFFFF | |
trim.moldingProfile | one of 'simple', 'cove', 'crown', 'dentil' | The crown molding's profile | |
trim.casingWidth | number, ≥ 0, ≤ 20 | Door and window casing face width; 0 switches casings off, cm (0–20) |
update_area
update_areaChange 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
area | string | yes | GUID of the area |
color | string | Floor colour, e.g. #CEEDF3; sent alone it removes a floor material, sent with role it keeps it | |
role | number | Roomtype number only; set_area_roomtype also writes the name and colour | |
customName | string | A 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 | |
isCutout | boolean | true marks the area as not floor, e.g. a void or stairwell | |
showName | boolean | true: its name is drawn on the plan in 2D | |
showArea | boolean | true: its size in m² is drawn on the plan in 2D |
set_area_material
set_area_materialPut 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
area | string | yes | GUID of the area |
refid | string | yes | Refid of a floor material the host has seeded |
set_area_material_transform
set_area_material_transformTurn, offset or scale a room's floor material. rotation is degrees; sx/sy are percentages; tx/ty shift it. The polygon does not move.
| Parameter | Type | Required | Description |
|---|---|---|---|
area | string | yes | GUID of the area |
rotation | number | Rotation of the floor material, degrees | |
tx | number | Horizontal shift of the material, cm | |
ty | number | Vertical shift of the material, cm | |
sx | number, ≥ 1 | Horizontal scale, % of the material's own size (100 = as is) | |
sy | number, ≥ 1 | Vertical scale, % of the material's own size (100 = as is) |
set_area_roomtype
set_area_roomtypeMake 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
area | string | yes | GUID of the area |
role | number | yes | Roomtype number from list_roomtypes, e.g. 0 Living, 2 Kitchen, 3 Bedroom |
set | number | The 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
set_area_ceilingTurn a room's ceiling on or off, or give it a colour or a material from a seeded refid.
| Parameter | Type | Required | Description |
|---|---|---|---|
area | string | yes | GUID of the area |
enabled | boolean | false: no ceiling in 3D | |
color | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | The ceiling colour, #rrggbb; replaces a ceiling material | |
refid | string | A material refid the host has seeded; replaces a ceiling colour |
list_rooms
list_roomsList 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_roomtypesList 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_roomDescribe 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
room | string | yes | GUID of the room, from list_rooms |
check_room
check_roomCheck 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
room | string | yes | The room to check, from list_rooms |
Furniture and other items
delete_items
delete_itemsDelete 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
items | string[] | yes | GUIDs of the items to delete; every one must exist or nothing is deleted |
move_item
move_itemMove an item to a point, restacking it and anything that was resting on it.
| Parameter | Type | Required | Description |
|---|---|---|---|
item | string | yes | GUID of the item |
to | {x, y} | yes | Where the item's CENTRE goes, absolute plan coordinates in cm |
rotate_item
rotate_itemSet an item’s rotation in degrees, restacking it and anything resting on it.
| Parameter | Type | Required | Description |
|---|---|---|---|
item | string | yes | GUID of the item |
rotation | number | yes | Which 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_itemAdd an item from a cached asset at a point. Requires resources.setAssetsCache to be seeded.
| Parameter | Type | Required | Description |
|---|---|---|---|
refid | string | yes | Asset id of the product, from a catalogue the host has seeded; not a GUID |
at | {x, y} | yes | Where the item's CENTRE goes, absolute plan coordinates in cm |
rotation | number | Which 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 | |
role | string | A free-text label for the item's purpose, e.g. 'sofa'; shown on the moodboard | |
materials | object | A variant: material slot to material id, as a search row's materials; the product's defaults if omitted | |
mirrored | boolean | Place it mirrored left to right, for a piece the catalogue has in one hand only |
replace_item
replace_itemPut 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
item | string | yes | GUID of the item |
refid | string | yes | Asset id of the new product, from a catalogue the host has seeded; may be the same product |
materials | object | A variant: material slot to material id, as a search row's materials; the product's defaults if omitted |
mirror_item
mirror_itemMirror 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
item | string | yes | GUID of the item |
axis | one of 'left-right', 'front-back' | 'left-right' (the default) swaps its left and right; 'front-back' its front and back |
set_item_elevation
set_item_elevationSet how high a piece's underside is above the floor, in cm. What rests on it moves with it; it is not restacked.
| Parameter | Type | Required | Description |
|---|---|---|---|
item | string | yes | GUID of the item |
elevation | number, ≥ -500, ≤ 1000 | yes | Height of the piece's underside above the floor, cm; a wall-mounted piece's too |
set_item_size
set_item_sizeResize 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
item | string | yes | GUID of the item |
width | number, ≥ 1, ≤ 5000 | across, side to side, cm | |
depth | number, ≥ 1, ≤ 5000 | front to back, cm | |
height | number, ≥ 1, ≤ 5000 | floor to top, cm |
set_item_name
set_item_nameGive a piece a name of your own, and show or hide it on the plan.
| Parameter | Type | Required | Description |
|---|---|---|---|
item | string | yes | GUID of the item |
customName | string | A name of your own, drawn on the plan with showName; "" removes it | |
showName | boolean | true: the name is drawn on the plan in 2D |
list_items
list_itemsList 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_itemsDescribe 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
room | string | Only the items in this room | |
items | string[] | Only these items |
Surfaces
delete_surfaces
delete_surfacesDelete free-drawn surfaces (rugs of floor, patches of finish). A room's own floor is not one.
| Parameter | Type | Required | Description |
|---|---|---|---|
surfaces | string[] | yes | GUIDs of the surfaces to delete; every one must exist or nothing is deleted |
move_surface
move_surfaceMove a whole surface by a delta, control points included.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
delta | {x, y} | yes | How far to move the surface, cm |
rotate_surface
rotate_surfaceRotate a surface about its own centroid, in degrees. The editor's buttons use 45.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
degrees | number | yes | Degrees to turn about its centroid, clockwise on screen |
mirror_surface
mirror_surfaceMirror a surface about its centroid. 'y' flips left-to-right, 'x' top-to-bottom.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
about | one of 'x', 'y' | yes | 'y' flips left-to-right, 'x' flips top-to-bottom |
move_surface_vertex
move_surface_vertexMove one corner of a surface to a point.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
index | number | yes | Corner number, from list_surfaces |
to | {x, y} | yes | Where the corner goes, absolute plan coordinates in cm |
move_surface_edge
move_surface_edgeDrag one edge of a surface sideways, stretching the two edges beside it.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
index | number | yes | Edge number: edge i runs from corner i to corner i+1 (list_surfaces numbers them) |
to | {x, y} | yes | A point the moved edge will pass through, cm; its neighbours stretch to meet it |
add_surface_vertex
add_surface_vertexAdd a corner on one edge of a surface, splitting the curve if that edge has one.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
index | number | yes | Edge number: edge i runs from corner i to corner i+1 (list_surfaces numbers them) |
at | {x, y} | yes | The new corner, cm, placed exactly as given |
dissolve_surface_edge
dissolve_surface_edgeRemove one edge of a surface, merging its corners where their neighbours meet.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
index | number | yes | Edge number: edge i runs from corner i to corner i+1 (list_surfaces numbers them) |
set_surface_edge_apex
set_surface_edge_apexCurve one edge so its apex sits at a point — or straighten it, if that is on the chord.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
index | number | yes | Edge number: edge i runs from corner i to corner i+1 (list_surfaces numbers them) |
apex | {x, y} | yes | A point the curved edge passes THROUGH, cm; a point on the straight line straightens it |
set_surface_elevation
set_surface_elevationMove 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
z | number | yes | Height in cm. May be negative. |
index | number | One 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
duplicate_surfaceCopy a surface, offset by 25cm, with a fresh GUID.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
offset | {x, y} | Where the copy goes relative to the original, cm; 25 cm right and down if omitted |
draw_surface
draw_surfacePaint 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}.
| Parameter | Type | Required | Description |
|---|---|---|---|
points | {x, y}[] | yes | The corners in order around the shape, absolute plan cm, at least 3; the outline closes itself |
points[].x | number | yes | |
points[].y | number | yes | |
color | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | Fill colour, e.g. #c8b89a | |
name | string | A name for the surface | |
elevation | number | Height above the floor in cm; 0 if omitted |
update_surface
update_surfaceSet 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
surface | string | yes | GUID of the surface |
transparency | number, ≥ 0, ≤ 100 | How see-through it is in 2D, % | |
hideIn3D | boolean | true: drawn in 2D only | |
dottedOutline | boolean | true: a dotted edge in 2D | |
isCutout | boolean | true: a hole in what is under it, e.g. a stairwell; drops its finish, name and role | |
isRoof | boolean | true: drawn as a roof | |
thickness | number, ≥ 0, ≤ 200 | Slab thickness, cm | |
customName | string | A name of your own, drawn instead of its roomtype name | |
showName | boolean | true: its name is drawn on the plan in 2D | |
showArea | boolean | true: its size in m² is drawn on the plan in 2D |
list_surfaces
list_surfacesList 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_linesDelete free-standing lines drawn on the plan, not walls.
| Parameter | Type | Required | Description |
|---|---|---|---|
lines | string[] | yes | GUIDs of the lines to delete; every one must exist or nothing is deleted |
draw_line
draw_lineDraw 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}.
| Parameter | Type | Required | Description |
|---|---|---|---|
from | {x, y} | yes | One end, absolute plan coordinates in cm |
to | {x, y} | yes | The other end, absolute plan coordinates in cm |
style | one of 'solid', 'dashed', 'dotted', 'dashdotted' | How the line is drawn | |
thickness | number, ≥ 1, ≤ 10 | Stroke thickness, 1 to 10, as the line panel offers | |
color | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | Stroke colour, e.g. #000000 |
update_line
update_lineChange a line's ends, style, thickness or colour; what is not given stays. Returns the line as draw_line does.
| Parameter | Type | Required | Description |
|---|---|---|---|
line | string | yes | GUID of the line |
from | {x, y} | New position of end a, plan cm | |
to | {x, y} | New position of end b, plan cm | |
style | one of 'solid', 'dashed', 'dotted', 'dashdotted' | How the line is drawn | |
thickness | number, ≥ 1, ≤ 10 | Stroke thickness, 1 to 10, as the line panel offers | |
color | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | Stroke colour, e.g. #000000 |
list_lines
list_linesList 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_labelsDelete text labels from the plan.
| Parameter | Type | Required | Description |
|---|---|---|---|
labels | string[] | yes | GUIDs of the labels to delete; every one must exist or nothing is deleted |
add_label
add_labelPut 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}.
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string, matching \S | yes | What the label says; not empty |
at | {x, y} | yes | Where the label stands, absolute plan coordinates in cm |
fontSize | number, ≥ 5, ≤ 500 | Text size, 5 to 500 | |
align | one of 'left', 'center', 'right' | How the text lines up on its point | |
rotation | number, ≥ -180, ≤ 180 | Degrees clockwise, -180 to 180 | |
fontColor | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | Text colour, e.g. #000000 | |
backgroundColor | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | Colour of the box behind the text | |
bold | boolean | Bold text | |
italic | boolean | Italic text | |
outline | boolean | An outline round the text | |
letterSpacing | number, ≥ 0, ≤ 100 | Space between letters, 0 to 100 |
update_label
update_labelChange a label's text, place or style; what is not given stays. Returns the label as add_label does.
| Parameter | Type | Required | Description |
|---|---|---|---|
label | string | yes | GUID of the label |
text | string, matching \S | New text; not empty | |
at | {x, y} | New position, plan cm | |
fontSize | number, ≥ 5, ≤ 500 | Text size, 5 to 500 | |
align | one of 'left', 'center', 'right' | How the text lines up on its point | |
rotation | number, ≥ -180, ≤ 180 | Degrees clockwise, -180 to 180 | |
fontColor | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | Text colour, e.g. #000000 | |
backgroundColor | string, matching ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$ | Colour of the box behind the text | |
bold | boolean | Bold text | |
italic | boolean | Italic text | |
outline | boolean | An outline round the text | |
letterSpacing | number, ≥ 0, ≤ 100 | Space between letters, 0 to 100 |
list_labels
list_labelsList 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_dimensionsDelete custom dimension lines; the generated ones follow the walls and the dimension settings.
| Parameter | Type | Required | Description |
|---|---|---|---|
dimensions | string[] | yes | GUIDs of the dimensions to delete; every one must exist or nothing is deleted |
add_dimension
add_dimensionDraw 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}.
| Parameter | Type | Required | Description |
|---|---|---|---|
from | {x, y} | yes | One end, absolute plan coordinates in cm |
to | {x, y} | yes | The other end, absolute plan coordinates in cm |
text | string, matching \S | Text shown instead of the measured length; omit it to show the length |
list_dimensions
list_dimensionsList 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_selectionDelete 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
selection | object | yes | What to delete, as GUID lists per kind; at least one kind must name something |
selection.items | string[] | GUIDs of the items to delete; every one must exist or nothing is deleted | |
selection.surfaces | string[] | GUIDs of the surfaces to delete; every one must exist or nothing is deleted | |
selection.lines | string[] | GUIDs of the lines to delete; every one must exist or nothing is deleted | |
selection.labels | string[] | GUIDs of the labels to delete; every one must exist or nothing is deleted | |
selection.dimensions | string[] | GUIDs of the dimensions to delete; every one must exist or nothing is deleted | |
selection.openings | string[] | GUIDs of the openings to delete; every one must exist or nothing is deleted | |
selection.walls | string[] | GUIDs of the walls to delete; every one must exist or nothing is deleted |
move_selection
move_selectionMove, flip or rotate a group of objects together, replacing them where they were.
| Parameter | Type | Required | Description |
|---|---|---|---|
selection | object | yes | What to transform, as GUID lists per kind; at least one kind must name something |
selection.items | string[] | GUIDs of the items in the group | |
selection.lines | string[] | GUIDs of the lines in the group | |
selection.walls | string[] | GUIDs of the walls in the group | |
selection.areas | string[] | GUIDs of the areas in the group | |
selection.labels | string[] | GUIDs of the labels in the group | |
selection.cameras | string[] | GUIDs of the cameras in the group | |
selection.surfaces | string[] | GUIDs of the surfaces in the group | |
selection.dimensions | string[] | GUIDs of the dimensions in the group | |
delta | {x, y} | How far to move the group, cm; applied first | |
rotation | number | Degrees 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 | |
excluded | object | Kinds to leave where they are; excluding walls excludes their rooms too | |
excluded.items | boolean | true leaves the selected items behind | |
excluded.lines | boolean | true leaves the selected lines behind | |
excluded.walls | boolean | true leaves the selected walls behind | |
excluded.areas | boolean | true leaves the selected areas behind | |
excluded.labels | boolean | true leaves the selected labels behind | |
excluded.cameras | boolean | true leaves the selected cameras behind | |
excluded.surfaces | boolean | true leaves the selected surfaces behind | |
excluded.dimensions | boolean | true leaves the selected dimensions behind |
duplicate_selection
duplicate_selectionCopy a group of objects, transformed, with fresh GUIDs, leaving the originals.
| Parameter | Type | Required | Description |
|---|---|---|---|
selection | object | yes | What to transform, as GUID lists per kind; at least one kind must name something |
selection.items | string[] | GUIDs of the items in the group | |
selection.lines | string[] | GUIDs of the lines in the group | |
selection.walls | string[] | GUIDs of the walls in the group | |
selection.areas | string[] | GUIDs of the areas in the group | |
selection.labels | string[] | GUIDs of the labels in the group | |
selection.cameras | string[] | GUIDs of the cameras in the group | |
selection.surfaces | string[] | GUIDs of the surfaces in the group | |
selection.dimensions | string[] | GUIDs of the dimensions in the group | |
delta | {x, y} | How far to move the group, cm; applied first | |
rotation | number | Degrees 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 | |
excluded | object | Kinds to leave where they are; excluding walls excludes their rooms too | |
excluded.items | boolean | true leaves the selected items behind | |
excluded.lines | boolean | true leaves the selected lines behind | |
excluded.walls | boolean | true leaves the selected walls behind | |
excluded.areas | boolean | true leaves the selected areas behind | |
excluded.labels | boolean | true leaves the selected labels behind | |
excluded.cameras | boolean | true leaves the selected cameras behind | |
excluded.surfaces | boolean | true leaves the selected surfaces behind | |
excluded.dimensions | boolean | true leaves the selected dimensions behind |
The whole design
clear_design
clear_designEmpty 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_planScale the whole plan about a point: lengths and positions grow or shrink, thicknesses, opening widths and item sizes stay.
| Parameter | Type | Required | Description |
|---|---|---|---|
factor | number | How much bigger, e.g. 1.1 for 10% bigger, 0.9 for 10% smaller | |
room | string | A room whose true floor area you know; give m2 with it | |
m2 | number | The room's true floor area, m2 | |
wall | string | A wall whose true length you know; give length with it | |
length | number | The 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_camerasList 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 {}.
