Projects, lists, and geometry

Project import, geometry snapshots, JSON export, and block and item lists in editorAPI.

Choose the method for the kind of data you need. An editable project, a geometry snapshot, and a Minecraft export serve different purposes and are not interchangeable formats.

Goal	Method
Add a saved project’s content to the current scene	`mergeContent`
Get temporary meshes for a custom visual export	`getMeshes`
Get commands and data for an in-game export	`exportToJSON`
Populate a block or item picker	`getBlockList`, `getItemList`

Run the examples after the editor is ready.

mergeContent

await editorAPI.mergeContent(content, decode = false);

Adds the project’s objects to the current root without replacing the entire open project. This asynchronous operation loads models. At the editorAPI level, the Promise resolves to undefined: the internal true/false result is not returned to the caller.

Argument	Format
`content` with `decode = false`	A scene/project JSON string in BDEngine’s format, not a JavaScript object
`content` with `decode = true`	An `ArrayBuffer`, `Uint8Array`, or string representation of a saved project
`decode`	Enables decoding of the container and compatible legacy formats; defaults to `false`

A current project file may contain scene.json and additional resources. The decoder also supports a Base64 string representation, legacy gzip data, and plain JSON. This is data packaging, not encryption. For a project file, pass its bytes and let the editor detect the format:

async function mergeProjectFile(file) {
  const bytes = await file.arrayBuffer();
  await editorAPI.mergeContent(bytes, true);
}

If you already have the project JSON as an object, serialize it first:

async function mergeSceneData(projectData) {
  await editorAPI.mergeContent(JSON.stringify(projectData));
}

A successful merge creates a history command and selects the added objects. Import validates the data, transfers embedded resources, and restores supported objects. The editor handles read errors; switching projects during loading prevents the result from being applied. Content with structure blocks or structure groups is not inserted through this path.

Do not test for success with if (await editorAPI.mergeContent(...)). A completed await means the call has finished, but does not provide boolean confirmation that import succeeded. The current API has no separate structured report for this operation.

The result of exportToJSON(), an HTTP Server API response, and a .bdshowcase file must not be treated as editable project JSON. Each requires its corresponding reading and interpretation logic.

getMeshes

const meshes = editorAPI.getMeshes();

Synchronously returns an array of temporary THREE.Mesh objects from a visual scene snapshot. If the snapshot subsystem is not ready or there are no meshes, returns []. Instances are expanded into ordinary meshes; helper frames, gizmos, and RT light sources do not become exportable objects in this array.

The snapshot uses the current geometry without PT assets. Each mesh has:

cloned geometry;
cloned materials, although their textures may still be shared with the editor;
the source’s world matrix stored in mesh.matrix;
matrixAutoUpdate = false, so changing position alone does not replace that matrix.

Do not rebuild the snapshot matrix from its zero position/rotation values: doing so loses the source object’s coordinates. The array is not a BDEngine scene, does not contain all project data, and does not track later changes.

const meshes = editorAPI.getMeshes();
try {
  const triangles = meshes.reduce((sum, mesh) => {
    const geometry = mesh.geometry;
    return sum + (geometry.index?.count ?? geometry.attributes.position.count) / 3;
  }, 0);
  console.log('Triangles in the snapshot:', triangles);
} finally {
  const materials = new Set();
  for (const mesh of meshes) {
    mesh.removeFromParent();
    mesh.geometry.dispose();
    const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
    list.forEach(material => materials.add(material));
  }
  materials.forEach(material => material.dispose());
}

Dispose of the snapshot’s geometry and materials when processing is complete. Do not call dispose() on their textures: the live scene may still use them. For asynchronous export, clean up only after the export has finished.

exportToJSON

await editorAPI.exportToJSON(fullProject, version);

Asynchronously runs the server export algorithm and returns a plain JavaScript object. fullProject defaults to false. Setting it to true requests a full export and temporarily switches the editor to Animator if needed. A full export may contain animation and sound frames. It does not save an editable project.

false does not switch the editor back from Animator to model mode. As a result, normal editing mode usually produces type: "modelOnly", while an already open Animator produces type: "full", even with fullProject = false. Read type from the actual result; the argument alone does not guarantee which fields it contains. After export, the editor restores the mode and animation state it temporarily changed, provided the user has not switched projects.

version is the numeric index of the target Minecraft version, starting at 1. If omitted, it selects the latest supported index rather than the current UI selection. The method changes the type and selected version in the export window, saves the version choice in settings, and shows that window.

async function inspectExport() {
  const data = await editorAPI.exportToJSON(false, 13); // Minecraft 1.21.4
  if (data === false) return;
  console.log(data.version, data.type);
  console.log(JSON.stringify(data, null, 2));
}

The call does not publish an export to Server API or issue a temporary ID. The export object is the direct result, without the HTTP content wrapper. The [BDESERVERTAG] marker remains in tags and commands: the HTTP tag parameter is not applied here.

Result	Meaning
Object	Prepared export data
`false`	Export did not complete, for example because HeadPaint texture publishing is unfinished, another export is running, an output limit is exceeded, or the data is unsupported
Rejected Promise	An unexpected error that the caller must handle

Server format restrictions still apply: for example, real structure blocks and splitting the model into groups with separate origins may block this export. Arbitrary custom datapack function files do not become fields in the server JSON.

For the exact fields, see JSON structure. For support across object types and export channels, see Export limitations.

Version index and result format

The version argument and result.version have different types. The argument is an index, while the result field is a Minecraft version string. For example, index 13 corresponds to "1.21.4". It is not an editorAPI version, Minecraft protocol number, or meta.schema.

The current source code defines these indices:

Index	Minecraft	Index	Minecraft
1	1.19.4	14	1.21.5
2	1.20	15	1.21.6
3	1.20.1	16	1.21.7
4	1.20.2	17	1.21.8
5	1.20.3	18	1.21.9
6	1.20.4	19	1.21.10
7	1.20.5	20	1.21.11
8	1.20.6	21	26.1
9	1.21	22	26.1.1
10	1.21.1	23	26.1.2
11	1.21.2	24	26.2
12	1.21.3	25	26.3
13	1.21.4

Pass an integer from the table. Out-of-range numbers are clamped to the boundaries, but this does not replace proper validation of fractional values or NaN. The default changes when new versions are added.

To preserve the user’s current choice, you can read editor.settingsEditor.exportMine.commandVersion. This uses the internal editor and requires compatibility checks between versions; there is currently no separate public getter for the selected index.

Block and item lists

getBlockList

editorAPI.getBlockList() synchronously returns an array of block state strings from the editor’s catalog. Identifiers omit the minecraft: prefix; a string may contain properties in square brackets.

const blocks = editorAPI.getBlockList();
console.log(blocks.slice(0, 10));
const stone = blocks.find(state => state === 'stone');
if (stone) await editorAPI.add(stone, 'BlockDisplay');

This is a list of picker choices, not a complete registry of every possible block state combination. Pass the entire string to add to preserve its properties.

getItemList

editorAPI.getItemList() synchronously returns an object, not an array. Its keys are item identifiers without minecraft:; values in the current catalog are false. This does not mark the item as unavailable for use.

const itemIds = Object.keys(editorAPI.getItemList());
console.log(itemIds.filter(id => id.includes('sword')));

Both lists come from the current editor’s catalog. They are not filtered by the index passed to exportToJSON, so appearing in a list does not mean a block or item is supported by every older Minecraft version.

getAvailabilityStatus

editorAPI.getAvailabilityStatus() synchronously returns the selected server configuration’s string key: 'default' or 'international' in the current code. Before the configuration is determined, it may be an empty string.

This is not a boolean connectivity check or an HTTP API status. The editor also assigns 'default' when it falls back to offline mode. The method does not make a server request or confirm that the network is currently available.

console.log('Server configuration:', editorAPI.getAvailabilityStatus());

Put it into practice

Read project data and export JSONChoose the right data format: a project to merge, scene geometry, or JSON for a Minecraft integration.

Add import or export actions to the File menuRegister custom File menu actions and handle file selection, asynchronous work and export errors.