Editor commands

🚧

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.

The embedded editor's API object can change the plan from your own code: draw rooms, put in doors and windows, place, move and delete furniture, and read what is there. Every change goes through the same rules as when a person makes it in the editor, is drawn straight away, and is one step on the editor's undo stack.

All commands are listed, with their parameters, in the Editor command reference.

Methods

MethodDescription
api.command(name, payload, options)Runs one command. Returns its result straight away (it is not a Promise).
api.transaction(steps, options)Runs several commands as one change: steps is [{name, payload}, …], at most 100. All or nothing: when one step is refused, nothing changes. One undo step for the whole transaction.
api.commands(names)The commands as {name, description, inputSchema, annotations}, where inputSchema is JSON Schema. Without names it returns every command; with a list of names, those in that order. This is the same format MCP and WebMCP tools use.

options is optional and may contain:

  • dry_run: true: answers what the command would do, with the same facts or the same refusal, and changes nothing.
  • expected_rev: the rev of an earlier answer. If the plan has changed since then (the user edited it, say), the call is refused with stale: true and nothing is changed, so you never edit a plan you have not read.
  • agent: {name, version}: names your integration on the undo steps it makes.

Results

A command never throws for a bad name, a bad payload or something it cannot do. It returns:

// accepted
{ok: true, facts: {...}, summary: 'Drew an unnamed room (befde8f8b015) (12 m²).', rev: 7}

// refused: nothing was changed
{ok: false, error: 'no wall with guid nope in this design', rev: 7}
  • facts is what the command did or found, such as the GUIDs it created or the rooms it listed. Each command's facts are its own.
  • summary is one sentence describing the change, for a log or a chat reply.
  • warnings, when present, lists things the change made true that the user should hear about.
  • error is a readable sentence saying why the command was refused.
  • rev is the plan's revision number. Pass it back as expected_rev.
  • When the user has locked part of the plan in the editor's top bar, a write that touches it is refused with code: 'locked' and a locks list.

GUIDs

Commands refer to walls, rooms, doors, windows and items by their GUID, a short string such as '80c1ed4dc69a'. You get GUIDs from:

  • the read-only list_* commands, such as list_rooms, list_walls and list_items;
  • the facts of the command that created something: facts.guids.minted lists every new GUID by type.

Some edits replace objects. Splitting a wall gives two new walls, and merging two rooms gives one. The old GUIDs are then listed in facts.guids.retired. A GUID you kept from before is refused with an error, so read the plan again with a list_* command.

Coordinates and units

Lengths and coordinates are in centimetres, in plan coordinates: x grows to the east (right) and y to the south (down). Floor areas in facts are in square metres.

Examples

Draw a room of 4 by 3 metres (inside measurements), with its top-left corner at the origin:

const r = api.command('draw_room', {at: {x: 0, y: 0}, width: 400, depth: 300});
// r.facts.room is the new room's GUID; r.facts.guids.minted.walls are its four walls

Draw a room, put a door in its first wall and name it, as one undo step. A string "$N.path" in a payload is the value at path in the facts of step N (counting from 0):

api.transaction([
    {name: 'draw_room', payload: {at: {x: 0, y: 0}, width: 400, depth: 300}},
    {name: 'add_opening', payload: {wall: '$0.guids.minted.walls.0', kind: 'door', t: 0.5}},
    {name: 'update_area', payload: {area: '$0.room', customName: 'Office'}},
]);

Check first, then change:

const check = api.command('move_wall', {wall: guid, delta: {x: 50, y: 0}}, {dry_run: true});
if (check.ok) api.command('move_wall', {wall: guid, delta: {x: 50, y: 0}}, {expected_rev: check.rev});

Products and materials

A command never loads anything over the network, so a product or material has to be in the editor before a command can use its id. Three functions on the API object load them. They return Promises:

MethodDescription
api.loadAssets(refids)Loads products and materials by id. Resolves {ok: true, loaded, notFound}. Call it before add_item, replace_item or a command that sets a material, with ids you already know.
api.searchProducts(text, {limit, category})Searches the furniture catalogue the user sees in the editor's sidebar. Resolves {ok: true, facts: {results: [{refid, name, …}]}}, 5 results by default and 20 at most. Every result is loaded, so its refid can be used straight away.
api.searchMaterials(text, {limit})The same for floor and wall materials.

Where a parameter's description in the reference says "from search_products" or "from search_materials", use api.searchProducts or api.searchMaterials.

const found = await api.searchProducts('sofa');
const sofa = found.facts.results[0];
api.command('add_item', {refid: sofa.refid, at: {x: 200, y: 150}, rotation: 0});