Проекты, списки и геометрия

Импорт проектов, снимки геометрии, JSON-экспорт и списки блоков и предметов в editorAPI.

Выбирайте метод по виду данных. Редактируемый проект, снимок геометрии и экспорт для Minecraft решают разные задачи и не являются взаимозаменяемыми форматами.

Нужно	Метод
Добавить содержимое сохранённого проекта в текущую сцену	`mergeContent`
Получить временные меши для собственного визуального экспорта	`getMeshes`
Получить команды и данные игрового экспорта	`exportToJSON`
Заполнить выбор блока или предмета	`getBlockList`, `getItemList`

Примеры выполняются после готовности редактора.

mergeContent

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

Добавляет объекты проекта к текущему корню, не заменяя открытый проект целиком. Это асинхронная операция с загрузкой моделей. На уровне editorAPI Promise разрешается значением undefined: внутренний результат true/false наружу не передаётся.

Аргумент	Формат
`content` при `decode = false`	Строка JSON сцены/проекта в формате BDEngine, а не JavaScript-объект
`content` при `decode = true`	`ArrayBuffer`, `Uint8Array` или строковое представление сохранённого проекта
`decode`	Включает декодирование контейнера и совместимых старых форматов; по умолчанию `false`

Современный файл может содержать scene.json и дополнительные ресурсы. Декодер также поддерживает строковое Base64-представление, старые данные gzip и обычный JSON. Это упаковка данных, а не шифрование. Для файла проекта удобнее передать байты и дать редактору распознать формат:

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

Если JSON проекта уже получен в виде объекта, сначала сериализуйте его:

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

После успешного слияния создаётся команда истории, добавленные объекты выделяются. Импорт проверяет данные, переносит вложенные ресурсы и восстанавливает поддерживаемые объекты. Ошибки чтения обрабатываются редактором; смена проекта во время загрузки прерывает применение. Содержимое со структурными блоками или группами структур этим путём не вставляется.

Не проверяйте успех через if (await editorAPI.mergeContent(...)). Завершённое ожидание означает завершение вызова, но не даёт boolean-подтверждения импорта. В текущем API нет отдельного структурированного отчёта об этой операции.

Результат exportToJSON(), HTTP-ответ Server API и файл .bdshowcase нельзя считать JSON редактируемого проекта. Для них нужны соответствующие способы чтения и интерпретации.

getMeshes

const meshes = editorAPI.getMeshes();

Синхронно возвращает массив временных THREE.Mesh из снимка визуальной сцены. Если подсистема снимка ещё не готова или мешей нет, результат - []. Инстансы разворачиваются в обычные меши; вспомогательные рамки, gizmo и RT-источники света не становятся экспортируемыми объектами этого массива.

Снимок использует текущую геометрию без PT-ресурсов. У каждого меша:

геометрия клонирована;
материалы клонированы, но связанные текстуры могут оставаться общими с редактором;
мировая матрица источника записана в mesh.matrix;
matrixAutoUpdate = false, поэтому изменение position само по себе не заменит эту матрицу.

Не пересобирайте матрицу снимка из нулевых position/rotation: так потеряются координаты исходного объекта. Массив не является сценой BDEngine, не содержит всех данных проекта и не подписан на дальнейшие изменения.

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);
} 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() у их текстур: они могут использоваться живой сценой. Если экспорт асинхронный, очищайте ресурсы только после его завершения.

exportToJSON

await editorAPI.exportToJSON(fullProject, version);

Асинхронно запускает алгоритм серверного экспорта и возвращает обычный JavaScript-объект. fullProject по умолчанию равен false. Значение true запрашивает полный экспорт и при необходимости временно переводит редактор в Animator. Полный экспорт может содержать кадры анимаций и звуков. Это не сохранение редактируемого проекта.

false не переводит редактор обратно из Animator в режим модели. Поэтому из обычного режима результат обычно имеет type: "modelOnly", а из уже открытого Animator - type: "full", даже при fullProject = false. Читайте type фактического результата; один аргумент не гарантирует состав полей. После экспорта редактор восстанавливает временно изменённое состояние режима и анимации, если пользователь не сменил проект.

version - числовой индекс целевой версии Minecraft, начиная с 1. Если аргумент опущен, выбирается последний поддерживаемый индекс, а не текущее значение в интерфейсе. Метод меняет тип и выбранную версию в окне экспорта, сохраняет выбор версии в настройках и показывает это окно.

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));
}

Вызов не публикует экспорт в Server API и не выдаёт временный ID. Объект находится непосредственно в результате, без HTTP-оболочки content. Маркер [BDESERVERTAG] в тегах и командах сохраняется: HTTP-параметр tag здесь не применяется.

Результат	Значение
Объект	Подготовленные данные экспорта
`false`	Экспорт не выполнен, например не завершена публикация текстур HeadPaint, запущен другой экспорт, превышен допустимый объём или данные не поддерживаются
Отклонённый Promise	Непредвиденная ошибка, которую нужно обработать в вызывающем коде

У метода сохраняются ограничения серверного формата: например, настоящие структурные блоки и разделение модели по группам для отдельных точек отсчёта могут блокировать этот экспорт. Произвольные файлы пользовательских функций датапака не становятся полями серверного JSON.

Точный состав полей: структура JSON. Поддержка разных объектов и каналов: ограничения экспорта.

Индекс версии и формат результата

Аргумент version и поле result.version имеют разный тип. Аргумент - индекс, поле результата - строка версии Minecraft. Например, индекс 13 соответствует "1.21.4". Это не версия editorAPI, не протокольный номер Minecraft и не meta.schema.

В текущих исходниках доступны следующие индексы:

Индекс	Minecraft	Индекс	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

Передавайте целое число из таблицы. Числа вне диапазона ограничиваются его границами, но это не замена корректной валидации дробного значения или NaN. При добавлении новых версий значение по умолчанию меняется.

Если нужен текущий выбор пользователя, его можно прочитать из editor.settingsEditor.exportMine.commandVersion. Это обращение к внутреннему editor, для которого проверяется совместимость между версиями; отдельного публичного метода чтения выбранного индекса сейчас нет.

Списки блоков и предметов

getBlockList

editorAPI.getBlockList() синхронно возвращает массив строк состояний блоков из каталога редактора. Идентификаторы записаны без префикса minecraft:; строка может содержать свойства в квадратных скобках.

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

Это список предложений для выбора, а не полный реестр всех возможных сочетаний block state. Передайте строку целиком в add, чтобы сохранить её свойства.

getItemList

editorAPI.getItemList() синхронно возвращает объект, а не массив. Его ключи - идентификаторы предметов без minecraft:, значения в текущем каталоге равны false. Это не отметка запрета использования предмета.

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

Оба списка формируются из каталога текущего редактора. Они не фильтруются по индексу, переданному в exportToJSON, поэтому присутствие в списке не означает поддержку предмета или блока любой старой версией Minecraft.

getAvailabilityStatus

editorAPI.getAvailabilityStatus() синхронно возвращает строковый ключ выбранной конфигурации серверов: в текущем коде 'default' или 'international'. До определения конфигурации может быть пустая строка.

Это не boolean-проверка соединения и не статус HTTP API. При переходе в офлайн-режим редактор тоже назначает 'default'. Метод не выполняет запрос к серверу и не подтверждает, что сеть доступна сейчас.

console.log('Конфигурация серверов:', editorAPI.getAvailabilityStatus());

Применить на практике

Получить данные проекта и JSON-экспортВыбрать правильный вид данных: проект для слияния, геометрию или JSON игрового экспорта.

Добавить импорт или экспорт в меню «Файл»Добавить пользовательское действие импорта/экспорта в меню «Файл».