VFXWeaver API

▶YouTube · плеер загрузится по нажатию

Клиентская библиотека/API VFX-эффектов для Minecraft 26.2, 26.1.x и 1.21.11 (Fabric и NeoForge). Кинематографичные эффекты «из коробки» — постобработка экрана, тряска камеры, оверлеи на блоках и сущностях, изображения на экране и настоящие окна с картинками на рабочем столе — всё это можно вызывать из чат-команд, из датапаков или программно из собственного мода через компактный Java API.

Автор: Artition · Лицензия: MIT

Что умеет

• 30+ эффектов постобработки, отрисовываемых через ping-pong FBO (полноэкранные попиксельные шейдеры): хроматическая аберрация, цветокоррекция, искажение, вмятина, градиентная карта, постеризация, размытие, пикселизация, выделение оттенка, виньетка, вспышка экрана, размытие в движении, bloom, зерно плёнки, строчная развёртка, глубина резкости, letterbox, инверсия, вихрь, линии скорости, сдвиг среза, шумовое искажение, соляризация, двоение, веки, радужная шторка, цифровой глитч, VHS, ударная волна, послеизображение, стоп-моушен и текстурные узоры мира/неба.
• Изображения на экране — screen_image рисует картинку (PNG из ресурспака с необязательной анимацией .mcmeta или изображение, зарегистрированное модом) поверх кадра игры на выбранном слое экрана: под GUI, над рукой или поверх всего, включая чат и хотбар.
• Окна с картинками на рабочем столе — window_create / window_control открывают настоящее безрамочное, прозрачное, клики-насквозь окно на рабочем столе и показывают в нём картинку; его можно двигать, менять размер, плавно скрывать и менять заголовок по имени. Это не постобработка и не геометрия мира.
• Эффекты камеры — тряска на основе симплекс-шума с плавной огибающей, наклон (dutch angle), модификатор FOV.
• Оверлеи мира — block_tint / block_outline (геометрия в мировом пространстве), light_beam, pulse_ring, guide_line, particles и block_chain.
• Эффекты сущностей — entity_tint / entity_outline / entity_displace, применяемые к сущностям по UUID (второй проход отрисовки модели, с учётом текстуры).
• Эффекты, задаваемые датапаком — обычный JSON, без кода. Ключевые кадры анимации, кривые сглаживания, привязки к миру/камере/игроку, математические выражения, коллекции, звуки.
• Триггеры сервер → клиент — эффекты, запускаемые серверной командой или из собственного мода по сети.
• Публичный Java API для других модов (VFXAPI), включая registerImage для показа изображения, которое отрисовывает ваш мод.

Требования

Типы эффектов

Постобработка экрана

Изображения на экране и окна рабочего стола

Камера

Оверлеи мира — block_tint, block_outline, light_beam (мягкий вертикальный столб), pulse_ring (расширяющееся кольцо), guide_line (пунктирная дуга параболы), particles (ванильные частицы в анимированных фигурах), block_chain (настоящие связи блок-моделей) Эффекты сущностей — entity_tint, entity_outline (по UUID), entity_displace (смещённое эхо по вершинам)

Быстрый старт

Все изменяющие команды требуют прав оператора (/vfx list доступна всем).

/vfx play vfxweaver:screen_flash
/vfx play vfxweaver:speed_lines {count:80, length:0.8, seed:"t * 2.0"}
/vfx play vfxweaver:screen_image {texture:"vfx_demos:textures/vfx/screen_anim", size_w:0.3, size_h:0.3}
/vfx playat vfxweaver:block_outline 100 64 200
/vfx playentity vfxweaver:entity_outline @e[type=!player,distance=..10]
/vfx stop vfxweaver:speed_lines
/vfx set vfxweaver:motion_blur {intensity:0.8}     # живая замена параметра у работающего эффекта
/vfx list

Эффекты датапаком (без моддинга)

Положи JSON в `data//vfx/.json, выполни /reload, и id эффекта будет :`:

{
  "type": "speed_lines",
  "duration": 60,
  "easing": "ease_out_cubic",
  "params": {
    "count": 80,
    "length": { "expr": "0.4 + 0.4 * t" },
    "seed": { "expr": "t * 2.0" },
    "intensity": 1.0
  }
}

• Анимированные параметры через ключевые кадры (t = 0..1 — прогресс) или математические выражения от состояния игрока (здоровье, голод, скорость, уровень освещения, время суток, позиция).
• Привязки к миру/камере/игроку (bind: screen_x, bind: proximity, ...), чтобы эффекты следовали за миром, а не за экраном.
• Коллекции — проигрывание нескольких дочерних эффектов с индивидуальными задержками.
• Определения автоматически синхронизируются с клиентами при входе и после /reload на выделенных серверах.

Java API (для других модов)

Статическая точка входа dev.vfxweaver.api.VFXAPI — по одной строке на вызов.

// Сервер → клиент
VFXAPI.sendEffect(serverPlayer,
    Identifier.fromNamespaceAndPath("vfxweaver", "screen_flash"),
    Map.of("intensity", 0.8F), null);

// С привязкой к миру (эффекты блоков/сущностей следуют за позицией)
VFXAPI.sendEffect(player, effectId, somePos, Map.of(), null);

// Локально на клиенте (без пакета)
VFXAPI.playEffect(Identifier.fromNamespaceAndPath("vfxweaver", "camera_shake"),
    20, Map.of("amplitude_x", 0.2F), null);

// Показать изображение, которое рендерит твой мод (пиксели ARGB), везде, где принимается id текстуры
VFXAPI.registerImage(Identifier.fromNamespaceAndPath("mymod", "textures/hud/icon"),
    width, height, argbPixels);

// Остановка / живая настройка
VFXAPI.sendStop(player, effectId);
VFXAPI.sendSetParam(player, effectId, "intensity", 0.3F);
VFXAPI.sendKeyframe(player, effectId, "intensity", 10, 1.0F, EasingType.EASE_OUT_CUBIC);

Сетевой слой (vfxweaver:vfx_trigger) версионирован по протоколу; клиент молча игнорирует пакеты с несовместимой версией. Полный API, структура пакетов и доступ к реестру определений описаны в docs/API.md в репозитории.

Документация

Команды, параметры эффектов, формат датапака, привязки — полное руководство по использованию в репозитории проекта. Собери сам через ./gradlew build (требуется JDK 25) или скачай готовый jar во вкладке Releases.

• Репозиторий: https://github.com/Artition/VFX-Weaver
• Документация: https://artition.github.io/VFX-Weaver/