LoVisual/mod/docs/api/addons.md

LoVisual Addon API (api/v0)

Аддоны — обычные Fabric-моды, которые расширяют LoVisual. Точка входа lovisual:addon в fabric.mod.json. Можно свободно менять публичный API при рефакторинге — владелец разрешил ломать совместимость ради KISS.

Entrypoint

fabric.mod.json:

{
  "schemaVersion": 1,
  "id": "my-addon",
  "name": "My Addon",
  "entrypoints": {
    "lovisual:addon": ["com.example.MyAddon"]
  },
  "custom": {
    "lovisual:addon": { "api": 0, "icon": "assets/my-addon/icon.png" }
  }
}

Класс:

public class MyAddon implements LoVisualAddon {
    public void onConfigureModules(LoVisualModuleLoadContext ctx) {
        ctx.disableBuiltInModule("killAura"); // выключить встроенный модуль до его создания
    }
    public void onInitialize(LoVisualAddonContext ctx) {
        ctx.registerModule(MyModule.class);
        ctx.registerDraggableHudElement(MyHud.class);
        ctx.registerStaticHudElement(MyStaticHud.class);
        ctx.registerCommand(new MyCommand());
        ctx.registerClickGuiSection(new MySection());
        ctx.addRenderCallback(LoVisualRenderStage.HUD_RAW, (c) -> { /* 2D */ });
    }
    public void onClientReady(LoVisualAddonRuntimeContext ctx) {}
    public void onShutdown(LoVisualAddonRuntimeContext ctx) {}
    public void onRuntimeSuspended(LoVisualAddonRuntimeContext ctx) {} // при выкл. аддона
    public void onRuntimeResumed(LoVisualAddonRuntimeContext ctx) {}
}

LoVisualAddon.API_VERSION = 0 — сверяется в AddonManager.java:438, несовпадение → WARNING.

Жизнь аддона (AddonManager.java:39)

1. discoverEntrypoints:211 — FabricLoader.getEntrypointContainers → ADDONS map, ENABLED_OVERRIDES из AddonStateStore (вкл/выкл сохраняется).
2. prepareModuleLoading:58 — configureEnabledAddons:230 → onConfigureModules (до ModuleAutoLoader).
3. init:65 — reconcileModuleExclusions:255 + initializeEnabledAddons:272 → onInitialize.
4. notifyClientReady:79 — onClientReady после загрузки конфигов.
5. Вкл/выкл из LoVisualAddonManagerScreen.java:548 AddonManager.setEnabled:160 — suspend/resumeRuntimeContributions:363 глушит модули/HUD, пишет AddonStateStore.

Статусы AddonStatus.java:12: DISCOVERED → ACTIVE / DISABLED / ERROR / SUSPENDED.

Что может аддон

• Модули ctx.registerModule(Class<? extends Module>) — обычный @ModuleInfo, попадёт в ModuleManager, конфиг addon:ID:module:ID.
• HUD registerDraggableHudElement / registerStaticHudElement — @HudElementInfo / @HudElementRegister, конфиг addon:ID:hud.*.
• Команды registerCommand(ClientCommand) — @CommandInfo, префикс %.
• ClickGui секции registerClickGuiSection(LoVisualClickGuiSection).
• Рендер addRenderCallback(stage, callback) / addPostProcessCallback — LoVisualRenderStage (HUD_RAW, WORLD_*).
• Расширения модулей LoVisualModuleExtension — beforeEnable/afterTick и т.д. через ModuleExtensionManager.

Профили: AddonManager.moduleProfileOwnerId:129 → addon:ID:module:ID для .lvcfg.

Пример минимального аддона

См. api/v0 JavaDoc и addon/core/AddonManager.java:211, addon/pipeline/AddonSnapshot.java:14, features/gui/mainmenu/LoVisualAddonManagerScreen.java:48 (UI).

Примечание по рефакторингу

Публичный Java API аддонов можно ломать свободно — KISS важнее обратной совместимости (решение владельца 2026-09-05, TODO.md:9). При рефакторе меняй сигнатуры, удаляй делегирование, обновляй вызывающих.