Раздел в процессе написания и будет часто обновляться.

Важно: Server API предназначен в первую очередь для разработчиков серверных плагинов и пользовательских интеграций. Официальных плагинов для работы с этим API нет.

Server API позволяет получить опубликованную модель по её ID в формате JSON.
Этот JSON можно использовать на стороне сервера для создания собственной интеграции: спавна модели, добавления хитбоксов, воспроизведения звуков и запуска анимаций.

ID модели является временным и действует только в течение 5 минут с момента публикации. После истечения этого времени ID удаляется с сервиса и больше не может быть использован для получения модели.

Публикация модели

После экспорта в режим Minecraft Server модель публикуется на стороне сервиса и становится доступной по уникальному ID.
Пользователю показывается сообщение об успешной публикации, ID модели и quick command для примера интеграции.

Получение ID модели

Основной идентификатор модели — это числовой ID, например 241235.
Именно этот ID нужно передать в Server API для получения JSON-описания модели.

Важно: полученный ID живёт только 5 минут. Если плагин или сервер не успел запросить данные модели за это время, модель необходимо опубликовать заново и получить новый ID.

Quick command вида /bde spawn 241235 — это лишь пример того, как серверный плагин может использовать ID модели. Логика выполнения этой команды полностью зависит от реализации плагина.

Для получения данных модели выполните GET-запрос по следующему адресу:

GET https://block-display.com/server-api/?id=MODEL_ID

Пример:

GET https://block-display.com/server-api/?id=241235

Параметр tag является необязательным.
Он позволяет задать пользовательский тег, который будет подставлен в данные модели.
Если параметр не указан, используется значение bde.

Пример запроса с пользовательским тегом:

GET https://block-display.com/server-api/?id=241235&tag=my_model_1

ID, передаваемый в запросе, действителен только в течение 5 минут после публикации модели.

В случае успеха API возвращает JSON с полем content, внутри которого содержатся данные модели.

Основные поля

content.version — версия формата данных.
content.type — тип экспортированного содержимого.
content.passengers — визуальные части модели.
content.datapack.anim_keyframes — ключевые кадры анимаций.
content.datapack.sound_keyframes — ключевые кадры звуков.
content.hitbox — данные для создания хитбоксов.

Точная интерпретация этих полей зависит от вашей серверной реализации. API не навязывает конкретный способ обработки данных.

Поле passengers содержит список частей модели.
Каждая запись представляет собой строку с данными сущности, которую можно использовать для построения визуальной части модели на сервере.

{
  "passengers": [
    "{id:\"minecraft:block_display\",block_state:{Name:\"minecraft:oak_log\",Properties:{axis:\"x\"}},transformation:[1f,0f,0f,0.5625f,0f,1f,0f,0f,0f,0f,1f,0.25f,0f,0f,0f,1f],Tags:[\"bde_0\"]}"
  ]
}

Поле content.datapack.anim_keyframes содержит набор анимаций и их ключевых кадров.
Внутри каждого кадра находится список команд, которые должны быть применены к соответствующим сущностям модели.

{
  "anim_keyframes": {
    "default": {
      "0": [
        "data merge entity @e[type=block_display,tag=bde_0,distance=..1,limit=1,sort=nearest] {transformation:[1f,0f,0f,0.5625f,0f,1f,0f,0f,0f,0f,1f,0.25f,0f,0f,0f,1f],interpolation_duration:0}"
      ]
    }
  }
}

Серверный плагин сам решает, выполнять ли эти команды напрямую, преобразовывать их в собственные структуры данных или использовать любую другую логику воспроизведения анимации.

Поле content.datapack.sound_keyframes содержит звуковые события, распределённые по кадрам.
Обычно внутри кадра хранится список команд воспроизведения звука.

{
  "sound_keyframes": {
    "default": {
      "3": [
        "playsound ambient.basalt_deltas.additions block @a ~ ~ ~ 1 1.125"
      ]
    }
  }
}

Поле hitbox содержит данные для создания хитбоксов.
Это отдельные сущности, которые могут использоваться для коллизии, взаимодействия или иных серверных задач.

{
  "hitbox": [
    "summon block_display ~1.4375 ~-0.3125 ~1.5 {Passengers:[{id:\"minecraft:shulker\",NoGravity:1b,Silent:1b,NoAI:1b,Invulnerable:1b,AttachFace:0b,active_effects:[{id:\"minecraft:invisibility\",amplifier:0,duration:-1,show_particles:0b}],attributes:[{id:\"minecraft:scale\",base:3}]}],Tags:[\"bde\",\"bde_hitbox\"]}"
  ]
}

Функции проекта не входят в ответ Server API, даже если они были созданы внутри проекта.

Server API передаёт только данные, необходимые для пользовательской серверной реализации: части модели, анимации, звуки и хитбоксы.

Разработчик плагина свободен в том, как использовать данные из API.
Вы можете:

- самостоятельно создавать модель по данным из passengers;
- использовать anim_keyframes для собственной системы анимаций;
- подключать sound_keyframes к проигрыванию звуков;
- создавать отдельные сущности хитбоксов из hitbox.

{
  "content": {
    "version": "26.1",
    "type": "full",
    "passengers": [
      "{id:\"minecraft:block_display\",block_state:{Name:\"minecraft:oak_log\",Properties:{axis:\"x\"}},transformation:[1f,0f,0f,0.5625f,0f,1f,0f,0f,0f,0f,1f,0.25f,0f,0f,0f,1f],Tags:[\"bde_0\"]}"
    ],
    "datapack": {
      "anim_keyframes": {
        "default": {
          "0": [
            "data merge entity @e[type=block_display,tag=bde_0,distance=..1,limit=1,sort=nearest] {transformation:[1f,0f,0f,0.5625f,0f,1f,0f,0f,0f,0f,1f,0.25f,0f,0f,0f,1f],interpolation_duration:0}"
          ],
          "1": [
            "data merge entity @e[type=block_display,tag=bde_0,distance=..1,limit=1,sort=nearest] {transformation:[1f,0f,0f,0.504375f,0f,1f,0f,0f,0f,0f,1f,0.358125f,0f,0f,0f,1f],interpolation_duration:2,start_interpolation:0}"
          ]
        }
      },
      "sound_keyframes": {
        "default": {
          "3": [
            "playsound ambient.basalt_deltas.additions block @a ~ ~ ~ 1 1.125"
          ]
        }
      }
    },
    "hitbox": [
      "summon block_display ~1.4375 ~-0.3125 ~1.5 {Passengers:[{id:\"minecraft:shulker\",NoGravity:1b,Silent:1b,NoAI:1b,Invulnerable:1b,AttachFace:0b,active_effects:[{id:\"minecraft:invisibility\",amplifier:0,duration:-1,show_particles:0b}],attributes:[{id:\"minecraft:scale\",base:3}]}],Tags:[\"bde\",\"bde_hitbox\"]}"
    ]
  }
}