Objects and selection

editorAPI provides operations on live objects in the current project. A returned object remains part of the scene: changing its properties changes the project. Transform methods and their units are described in the Selectable reference.

The examples assume that the editor is ready. For initialization order, see Events and lifecycle.

add

await editorAPI.add(
  identifier, type, parent = null, save = true,
  objPos = undefined, noReply = false, options = {}
);

Asynchronously creates a built-in object, loads its model, and adds it to the parent. Returns the created object. If the operation is refused, canceled because the project changed, or fails, the result may be false or undefined; check it before using it.

Parameter	Meaning
identifier	A block state, item identifier, or text, depending on type
type	One of the types in the table below, with the exact capitalization shown
parent	An existing parent object in the current project; null selects the project root for displays. StructureBlock uses a structure group, as described below
save	When true, adds a command to Undo/Redo if noReply = false. This does not save a file
objPos	Optional THREE.Vector3 with a position in world coordinates
noReply	When true, disables broadcasting the addition to Share Party participants, recording history, and the loading indicator
options.skipEditorUpdate	When true, skips the UI and HeadPaint grid update after adding the object. Defaults to false

type	identifier	Requirements
BlockDisplay	For example, 'stone' or a state from getBlockList()	Normal editing mode
ItemDisplay	For example, 'diamond_sword'	Normal editing mode
TextDisplay	A text string, such as 'Hello!'	May require loading a font
StructureBlock	A real block’s state	Structure editing mode only; uses the supplied structure group or its root

This method does not create other type values, including 'Collection'. Trying to add a regular display in structure mode returns false. Regular displays also cannot be added inside a structure group this way. For StructureBlock, if parent is missing or is not a structure group, the editor selects or creates its root through the structure subsystem.

objPos is converted from world coordinates to the parent’s local coordinates, then added to the object’s initial position. Pass a THREE.Vector3, not a plain object with x/y/z. A player_head has its own initial offset of 0.5 on Y, so objPos is not always the final position. A StructureBlock position is rounded to integer coordinates.

const block = await editorAPI.add(
  'stone', 'BlockDisplay', null, true,
  new THREE.Vector3(0, 1, 0)
);
if (block) {
  console.log(block.uuid, block.getPosition());
}

The method updates the UI during a normal call. For a series of additions, you can skip intermediate updates and call update() once afterward:

async function addTwoBlocks() {
  try {
    for (let x = 0; x < 2; x++) {
      const block = await editorAPI.add(
        'stone', 'BlockDisplay', null, true,
        new THREE.Vector3(x, 0, 0), false,
        { skipEditorUpdate: true }
      );
      if (!block) break;
    }
  } finally {
    editorAPI.update();
  }
}

In this example, each successful add remains a separate Undo command and a separate Share Party message. skipEditorUpdate does not combine commands into a transaction.

addObject

const inserted = editorAPI.addObject(object, parent = null);

Synchronously calls parent.add(object), or editor.objects.add(object) if no parent is supplied. Returns the same object, or null for an empty value. The object must be suitable for a Three.js hierarchy, for example, an instance of a Selectable subclass.

addObject does not load a Minecraft model, add a history command, broadcast the addition to Share Party, or call editorAPI.update(). It follows a different path from add.

// customObject has already been created by your Selectable subclass.
editorAPI.addObject(customObject);
editorAPI.update();

See Creating a custom object. Adding an object alone does not provide persistence, Undo restoration, or Minecraft export for arbitrary geometry.

find

const objects = editorAPI.find(key, val = true);

Synchronously searches the project root and its descendants for a direct property with an exact value. Returns an array of references, or [] if there are no matches. It does not search the entire editor.scene or a nested path such as 'position.x'.

const blocks = editorAPI.find('isBlockDisplay');
const named = editorAPI.find('name', 'My object');
const selected = editorAPI.find('selected');

The default value is boolean true, not a test for any truthy value. For example, find('name') does not mean “objects with a name”. Object-valued properties are compared by reference. A search may return different object types; check the type or method availability before calling type-specific methods.

getSelectedObjects

const objects = editorAPI.getSelectedObjects();

Synchronously returns the result of find('selected', true): an array of selected objects, or []. A selection may contain groups, displays, and utility objects. You can filter the array, but its elements are not copies of scene objects.

const blocks = editorAPI.getSelectedObjects()
  .filter(object => object.isBlockDisplay);
console.log('Selected block displays:', blocks.length);

This is a snapshot of which objects were selected at the time of the call. Read the selection again for each button click: the user may have switched projects or deleted objects.

delete

editorAPI.delete(objects);

Accepts an array of live objects and runs the standard deletion workflow: normalizes the targets, creates an Undo/Redo command, broadcasts deletions to Share Party, and updates the selection controller. Duplicate objects and descendants of a parent already being deleted are not deleted twice; stale references are discarded. Returns undefined; the public method does not return a Promise.

An empty array does not mean “do nothing”. If the argument is not a nonempty array, the editor uses the current selection. Check a filtered result before deleting:

const blocks = editorAPI.getSelectedObjects()
  .filter(object => object.isBlockDisplay);
if (blocks.length > 0) {
  editorAPI.delete(blocks);
}

Structure mode restrictions still apply: its parts cannot be deleted outside that mode, while the structure root itself and unrelated objects cannot be deleted within it. For an arbitrary custom class, restoration depends on whether the editor supports its serialization.

deleteSelected

editorAPI.deleteSelected();

Deletes the current selection through the same path as delete. Does nothing if the selection is empty. Returns undefined. The method does not display a separate deletion confirmation.

removeObject

editorAPI.removeObject(object);

For a supplied object, runs standard deletion on the array [object]. Does nothing for null or undefined. Synchronously returns undefined.

The name does not mean “silently detach from the Three.js scene”: the method uses the same history, restrictions, and network path as delete. It does not automatically clean up every resource created by a third-party plugin.

update

editorAPI.update(withControl = false);

Updates panels, the object list, properties, and the scene display. If withControl = true, it also rebuilds the controller’s temporary selection from the currently selected objects. Returns undefined.

const object = editorAPI.getSelectedObjects()
  .find(item => typeof item.setPosition === 'function');
if (object) {
  const position = object.getPosition();
  object.setPosition({ y: position.y + 1 });
  editorAPI.update(true);
}

update does not save a file, create an Undo command, or broadcast arbitrary changes to Share Party. The setter in this example changes the object directly; no transform history command is added.

Parent, history, and repeated operations

Operation	History	Share Party	Update
add(...) with normal parameters	Addition command	Broadcasts the added object	Yes
add(..., save = false)	No	Yes, while noReply = false	Yes, unless skipEditorUpdate is set
add(..., noReply = true)	No, even with save = true	No	Yes, unless skipEditorUpdate is set
addObject	No	No	Call update
delete, deleteSelected, removeObject	Standard deletion command	Broadcasts deletions	Updates the controller
Position, rotation, and scale setters	Not created automatically	Not broadcast automatically	Call update(true) if you changed the selection
update	No	No	Yes

The parent passed to add must be in the current project. If the project, history, or parent changes during loading, the addition is aborted. Do not keep references to objects from a previous project for future operations.

You can use editor for custom grouping, history, and network behavior. It is an accessible internal interface whose implementation can change; document that dependency and check it when updating the editor. Its difference from the stable API is explained in editorAPI and the internal editor.

Put it into practice

Process selected objectsApply a controlled operation to selected objects and handle empty, mixed and nested selections.

Build a generator with built-in objectsGenerate a parameterized row of built-in BDEngine objects with input validation and failure handling.