API

Esta página documenta a API pública em org.z2six.ezactions.api para EZ Actions 2.0.0.0.

Público:

• desenvolvedores de mods
• desenvolvedores de modpack
• usuários de automação avançada

O que a API pode fazer

Resposta curta: tudo o que os usuários podem fazer na GUI, além de controle extra de tempo de execução.

• Leia a árvore do menu
• Adicionar/atualizar/remover/reordenar ações e pacotes
• Marcar entradas como bloqueadas
• Importar/exportar/validar menu JSON
• Abrir telas de editor/config/radial
• Abra radial diretamente em um pacote
• Abra radiais de tempo de execução temporários sem persistir
• Entrada de chave de gatilho e sequenciamento de comando
• Inscreva-se em eventos simples de API

Acesso

import org.z2six.ezactions.api.EzActions;
import org.z2six.ezactions.api.EzActionsApi;

EzActionsApi api = EzActions.get();

Core Concepts

MenuPath

MenuPath endereça pacotes por cadeia de título de pacote da raiz.

MenuPath root = MenuPath.root();
MenuPath p = MenuPath.root().child("Utilities").child("Combat");

Notes:

• a correspondência de caminho diferencia maiúsculas de minúsculas e literal de título.
• caminho vazio = lista raiz.

Entradas bloqueadas

locked=true significa protegido contra fluxos de exclusão no jogo e remoções de API com reconhecimento de bloqueio.

As entradas bloqueadas ainda podem ser removidas por edições manuais de JSON.

Modelo de Persistência

A maioria das chamadas de API mutantes persistem imediatamente.

Geralmente você não precisa de uma chamada extra para salvar.

Rosqueamento

Os retornos de chamada/eventos de API são projetados para uso de thread do cliente.

Tipos de ação

Ação-chave

import org.z2six.ezactions.data.click.ClickActionKey;
import org.z2six.ezactions.helper.InputInjector;

ClickActionKey keyAction = new ClickActionKey(
    "key.inventory",                    // mapping id or label
    false,                              // toggle
    InputInjector.DeliveryMode.AUTO     // AUTO/INPUT/TICK
);

Command Action

import org.z2six.ezactions.data.click.ClickActionCommand;

ClickActionCommand cmd = new ClickActionCommand(
    "/time set day\n/time set night", // multi-line
    10,                                 // delay ticks between lines
    true                                // cycleCommands
);

Item Equip Action

import net.minecraft.client.Minecraft;
import net.minecraft.core.HolderLookup;
import net.minecraft.world.item.ItemStack;
import org.z2six.ezactions.data.click.ClickActionItemEquip;

HolderLookup.Provider regs = Minecraft.getInstance().player.level().registryAccess();
ItemStack stack = Minecraft.getInstance().player.getMainHandItem();

ClickActionItemEquip.StoredItem stored =
    ClickActionItemEquip.StoredItem.fromStack(stack, regs);

ClickActionItemEquip eq = new ClickActionItemEquip(
    java.util.Map.of(ClickActionItemEquip.TargetSlot.MAINHAND, stored)
);

Icons

import org.z2six.ezactions.data.icon.IconSpec;

IconSpec itemIcon = IconSpec.item("minecraft:ender_pearl");
IconSpec customIcon = IconSpec.custom("custom:my_icon");

Top-Level EzActionsApi

MenuLeia

Interface: MenuRead

• org.z2six.ezactions.api
• MenuPath
• locked=true
• openEditor(Screen)

Campos de instantâneo do ApiMenuItem

Noções básicas:

• id, title, note
• isCategory, typeLabel
• iconKind, iconId
• hideFromMainRadial, bundleKeybindEnabled, locked

Detalhes da ação:

• org.z2six.ezactions.api
• MenuPath
• ação principal: keyMappingName, keyToggle, keyMode
• ação de comando: commandRaw, commandDelayTicks, commandCycleCommands
• ação de equipar item: itemEquipSlotsJson

##MenuEscrever

Interface: MenuWrite

Criar

• org.z2six.ezactions.api
• MenuPath
• locked=true
• openEditor(Screen)

Mover

• org.z2six.ezactions.api
• MenuPath

Remover

• org.z2six.ezactions.api
• MenuPath

Atualizar

• org.z2six.ezactions.api
• MenuPath
• locked=true
• openEditor(Screen)

Ajudantes Estruturais

• ensureBundles(path) cria uma cadeia de pacotes ausentes por título.
• upsertFromJson(path, jsonObjectOrArray) adiciona/substitui itens do snippet JSON.

Exemplo: Crie um pacote de utilitários bloqueado

var write = EzActions.get().menuWrite();

MenuPath root = MenuPath.root();
String bundleId = write.addBundle(
    root,
    "Utilities",
    "Pack-defined utilities",
    IconSpec.item("minecraft:shulker_box"),
    false,   // hideFromMainRadial
    true,    // bundleKeybindEnabled
    true     // locked
).orElseThrow();

write.addAction(
    root.child("Utilities"),
    "Open Inventory",
    "Quick inventory",
    IconSpec.item("minecraft:chest"),
    new ClickActionKey("key.inventory", false, InputInjector.DeliveryMode.AUTO),
    true
);

ImportExport

Interface: ImportExport

• org.z2six.ezactions.api
• MenuPath
• locked=true
• openEditor(Screen)
• openConfig(Screen)

Regras de validação (alto nível)

• root deve ser objeto ou array
• cada item deve conter exatamente um dos seguintes:
• org.z2six.ezactions.api
• MenuPath
• o objeto de ação deve incluir type válido
• booleanos opcionais (hideFromMainRadial, bundleKeybindEnabled, locked) devem ser booleanos quando presentes

Operações de entrada

Interface: InputOps

• org.z2six.ezactions.api
• MenuPath

Exemplo:

var input = EzActions.get().inputOps();

input.deliver("key.inventory", false, InputOps.Mode.AUTO);
input.enqueueCommands(new String[]{"/time set day", "/weather clear"}, 10);

EditorOps

Interface: EditorOps

• org.z2six.ezactions.api
• MenuPath
• locked=true
• openEditor(Screen)
• openConfig(Screen)

Estilo radial temporário dinâmico

Classe: DynamicRadialStyle

Todos os campos são substituições anuláveis ​​opcionais.

Cores:

• org.z2six.ezactions.api
• MenuPath
• locked=true
• openEditor(Screen)

Animação:

• org.z2six.ezactions.api
• MenuPath
• locked=true
• openEditor(Screen)
• openConfig(Screen)
• openStyle (WIPE|FADE|NONE)
• openDirection (CW|CCW)
• hoverStyle (FILL_SCALE|FILL_ONLY|SCALE_ONLY|NONE)

Projeto:

• org.z2six.ezactions.api
• MenuPath
• locked=true
• openEditor(Screen)
• openConfig(Screen)
• openRadial()
• designStyle (SOLID|SEGMENTED|OUTLINE|GLASS)

Exemplo: Temporário Radial

String json = """
[
  {
    "id": "tmp_inv",
    "title": "Inventory",
    "icon": "minecraft:chest",
    "action": { "type": "KEY", "name": "key.inventory", "toggle": false, "mode": "AUTO" }
  },
  {
    "id": "tmp_day",
    "title": "Day",
    "icon": "minecraft:sunflower",
    "action": { "type": "COMMAND", "command": "/time set day", "delayTicks": 0, "cycleCommands": false }
  }
]
""";

DynamicRadialStyle style = new DynamicRadialStyle(
    0xAA000000, 0xFFF20044, 0x66FFFFFF, 0xFFFFFFFF,
    true, true, true,
    125, 0.05,
    "WIPE", "CW", "FILL_SCALE",
    18, 72, 28,
    8, 6, 0,
    "SOLID"
);

EzActions.get().editorOps().openTemporaryRadial(json, style);

Events

Classe: ApiEvents

• org.z2six.ezactions.api
• MenuPath

Cargas úteis:

• MenuChanged.path, MenuChanged.reason
• ImportEvent.target, ImportEvent.json, ImportEvent.count

Exemplo:

var events = EzActions.get().events();

events.onMenuChanged(evt -> {
    System.out.println("Menu changed: " + evt.reason + " at " + evt.path);
});

events.onImported(evt -> {
    System.out.println("Imported " + evt.count + " entries into " + evt.target);
});

JSON Item Schema (API + Import/Export)

{
  "id": "string",
  "title": "string or text component",
  "note": "string or text component",
  "icon": "minecraft:item_id",
  "hideFromMainRadial": false,
  "bundleKeybindEnabled": false,
  "locked": false,
  "action": {
    "type": "KEY | COMMAND | ITEM_EQUIP"
  },
  "children": []
}

Rules:

• use action para itens de ação
• use children para pacotes
• não inclua ambos no mesmo objeto

Padrão de interoperabilidade estilo KubeJS

A sintaxe exata depende da configuração do KubeJS, mas o fluxo geralmente é:

Primeiro, carregue a classe API Java

1. obtenha singleton via EzActions.get()
2. chame os métodos menuWrite() / editorOps()

Pseudo-fluxo:

// pseudo example, adapt to your exact loader bridge
const EzActions = Java.loadClass('org.z2six.ezactions.api.EzActions')
const api = EzActions.get()

// use api.menuWrite(), api.importExport(), api.editorOps(), etc.

API Notes For Pack Authors

• Se as gravações da sua API permitirem atalhos de teclado de pacote, os usuários ainda precisarão reiniciar para registro de atalhos de teclado.
• EZ Actions agora notifica os usuários no chat quando a reinicialização é necessária para novos atalhos de teclado.
• Mantenha IDs/títulos estáveis ​​se você planeja corrigir menus ao longo do tempo.