Infinity Nexus Guia de Addons
Guia de addons Minecraft 26.1.2 API api.addon

Criando addons

O Infinity Nexus Multiblock possui um SPI para que addons registrem novos tipos de recurso, como chemical, mana, aura ou essentia, sem que o mod base importe classes do mod dono do recurso.

O addon é responsável por traduzir o seu mod para o contrato genérico do base. O base é responsável por carregar definições, criar storages, expor portas, renderizar barras, executar receitas e persistir os recursos.

Visão geral

Um addon de recurso normalmente faz quatro coisas:

  1. Implementa MultiblockResourceType para descrever o tipo.
  2. Implementa MultiblockResourceStorage para manipular os tanques.
  3. Registra o tipo em MultiblockAddons durante a construção do mod.
  4. Opcionalmente registra uma ponte JEI no cliente.

O base não valida os campos internos do seu mod. Ele entrega o objeto JSON bruto do capabilities.<kind> para o addon. Quem valida os campos específicos é o seu createStorage e o seu describeTanks.

O que o base faz

ÁreaComportamento genérico
capabilities.<kind>Captura o JSON bruto e chama describeTanks / createStorage do tipo registrado.
capability_ports.<kind>Lê uma lista de seletores de porta.
GUIRenderiza resource_bar com capability e slot.
ReceitasDespacha o campo type para o codec do addon.
PersistênciaSalva e restaura StoredResource por kind, tank, id e amount.
JEIUsa o JeiResourceBridge registrado pelo addon.

Se uma definição declarar um kind que não está registrado, o loader falha com uma mensagem parecida com:

Unknown multiblock resource kind 'aura': is the addon installed?

Contrato do addon

MultiblockResourceType

Interface principal em com.Infinity.Nexus.Multiblock.api.addon.MultiblockResourceType.

MétodoResponsabilidade
id()Nome do tipo. Use apenas [a-z][a-z0-9_]*, por exemplo aura.
createStorage(...)Cria o storage real a partir do JSON de capabilities.<kind>.
describeTanks(...)Retorna os tanques declarados no JSON como ResourceTankInfo(id, capacity).
ingredientCodec()Codec de entrada de receita para o seu type.
outputCodec()Codec de saída de receita para o seu type.
validateResourceId(String)Valida um id de recurso do seu mod.
displayName(String)Nome exibido em tooltip.
color(String)Cor ARGB usada pela barra.

Exemplo mínimo para um recurso aura:

public final class AuraResourceType implements MultiblockResourceType {
    public static final String KIND = "aura";

    @Override
    public String id() {
        return KIND;
    }

    @Override
    public MultiblockResourceStorage createStorage(
            MultiblockDefinition definition,
            JsonElement config,
            Runnable onChanged) {
        return new AuraStorage(config, onChanged);
    }

    @Override
    public List<ResourceTankInfo> describeTanks(JsonElement config) {
        return AuraStorage.describe(config);
    }

    @Override
    public MapCodec<? extends MultiblockRecipeIngredient> ingredientCodec() {
        return MultiblockRecipeIngredient.Resource.codec(KIND);
    }

    @Override
    public MapCodec<? extends MultiblockRecipeOutput> outputCodec() {
        return MultiblockRecipeOutput.Resource.codec(KIND);
    }

    @Override
    public DataResult<String> validateResourceId(String resourceId) {
        Identifier id = AuraIds.parse(resourceId);
        if (id == null || !AuraRegistry.contains(id)) {
            return DataResult.error(() -> "Unknown aura: " + resourceId);
        }
        return DataResult.success(resourceId);
    }

    @Override
    public Component displayName(String resourceId) {
        return AuraRegistry.displayName(resourceId);
    }

    @Override
    public int color(String resourceId) {
        return AuraRegistry.color(resourceId);
    }
}

MultiblockResourceStorage

O storage é a ponte entre o seu sistema de recurso e os tanques genéricos do multibloco. Ele deve manter uma ordem estável de índices, porque essa ordem é usada pela GUI, pelas receitas e pela persistência.

MétodoResponsabilidade
kind()Retorna o mesmo id() do tipo.
size()Quantidade de tanques.
tankId(index)Id estável do tanque, igual ao usado no JSON e na GUI.
capacity(index)Capacidade do tanque.
amount(index)Quantidade atual.
resourceId(index)Id do recurso armazenado, ou string vazia.
accepts(index, id)Se o tanque aceita aquele recurso.
insert(...)Insere e retorna quanto foi movido.
extract(...)Extrai e retorna quanto foi movido.
set(...)Define recurso e quantidade diretamente.
allowsPort(...)Restringe a porta do tanque.
snapshot()Lista de StoredResource para drops e persistência.
restore(...)Restaura o snapshot, ignorando ou limitando valores inválidos.
serialize(...)Salva no block entity.
deserialize(...)Carrega do block entity.

Regras práticas:

  • describeTanks e createStorage devem produzir os mesmos ids e capacidades.
  • insert e extract com simulate = true não podem alterar estado.
  • snapshot e restore devem ser simétricos.
  • Capacidade inválida no JSON deve ser rejeitada com log claro.
  • Tanque vazio pode usar id = "" e amount = 0.

Registro do tipo

Registre o tipo na construção do mod, antes das definições de multibloco serem carregadas. Registre só quando o mod dono do recurso estiver presente.

@Mod(MyAddon.MOD_ID)
public final class MyAddon {
    public MyAddon(IEventBus modBus, ModContainer container) {
        if (ModList.get().isLoaded("my_mod")) {
            MultiblockAddons.register(new AuraResourceType());
        }
    }
}

Para JEI, use uma classe client-only e registre a ponte apenas quando JEI estiver disponível:

@Mod(value = MyAddon.MOD_ID, dist = Dist.CLIENT)
public final class MyAddonClient {
    public MyAddonClient(ModContainer container, IEventBus modBus) {
        if (ModList.get().isLoaded("jei")) {
            MultiblockAddons.registerJeiBridge(
                    AuraResourceType.KIND,
                    new AuraJeiBridge());
        }
    }
}

JSON da definição

O base não impõe o formato interno de capabilities.<kind>. O exemplo abaixo é o formato que o addon de chemical usa; um addon de aura pode definir outro schema, desde que describeTanks e createStorage leiam esse schema.

"capabilities": {
  "aura": {
    "tanks": [
      {
        "id": "input",
        "capacity": 100000,
        "max_receive": 100,
        "max_extract": 0,
        "filter": "mymod:ignis"
      }
    ]
  }
},
"capability_ports": {
  "aura": ["A"]
}

O campo capability_ports.aura precisa ser uma lista de seletores. Cada seletor pode ser um símbolo do pattern, um id de bloco ou uma tag, conforme o comportamento do seu storage.

Uma barra de aura na GUI usa o tipo genérico resource_bar:

"gui": {
  "elements": [
    {
      "type": "resource_bar",
      "x": 8,
      "y": 8,
      "width": 8,
      "height": 54,
      "capability": "aura",
      "slot": "input"
    }
  ]
}

capability é o id do tipo (aura) e slot é o id do tanque retornado por describeTanks. O base rejeita a GUI se o tipo não estiver registrado ou se o tanque não existir.

chemical_bar é apenas um alias específico para o tipo chemical e é redirecionado para resource_bar. O tipo mana também usa chemical_bar no JSON final, com capability: "mana" e slot: "mana". Para outros recursos, use resource_bar.

Receitas

O campo type da receita é o id do recurso. O codec padrão de Resource usa id e amount:

"inputs": [
  {
    "type": "aura",
    "id": "mymod:ignis",
    "amount": 100
  }
],
"outputs": [
  {
    "type": "aura",
    "id": "mymod:ignis",
    "amount": 50,
    "tank": "input",
    "chance": 1.0
  }
]

Se quiser um nome de campo específico, use o overload do codec:

@Override
public MapCodec<? extends MultiblockRecipeIngredient> ingredientCodec() {
    return MultiblockRecipeIngredient.Resource.codec(KIND, "aura", true);
}

@Override
public MapCodec<? extends MultiblockRecipeOutput> outputCodec() {
    return MultiblockRecipeOutput.Resource.codec(KIND, "aura", true);
}

Isso permite JSON assim:

{
  "type": "aura",
  "aura": "mymod:ignis",
  "amount": 100
}

O tank de saída é opcional; quando informado, precisa existir e aceitar o recurso.

GUI

Para cada tanque que deve aparecer na GUI, crie um resource_bar. A ordem e a posição são livres; o vínculo é feito por capability e slot.

O addon também define o nome e a cor exibidos pela barra através de displayName(String) e color(String). Se o recurso não existir, retorne um nome vazio e uma cor segura em vez de lançar exceção.

JEI

A ponte é opcional, mas recomendada. Implemente JeiResourceBridge para desenhar a entrada e a saída no formato do seu mod.

MétodoUso
addInput / addOutputDesenha o recurso em um slot visível.
addInvisibleInput / addInvisibleOutputRegistra o recurso para busca e receitas sem ocupar um slot visual.
Overloads com width/heightPermitem renderizadores que dependem do tamanho da barra.

Registre a ponte somente no cliente, depois que JEI e o mod dono do recurso estiverem disponíveis.

Checklist

  • O id() usa apenas [a-z][a-z0-9_]*.
  • O tipo é registrado apenas se o mod dono do recurso estiver carregado.
  • describeTanks e createStorage concordam em ids, capacidades e filtros.
  • validateResourceId é usado pelo codec de receita e rejeita ids desconhecidos.
  • snapshot / restore e serialize / deserialize são simétricos.
  • A GUI usa resource_bar com um tanque que existe.
  • A ponte JEI é registrada apenas no cliente.
  • Testar sem o mod dono do recurso: a definição deve falhar com uma mensagem clara, não corromper o save.

Limitações atuais

  • O base não valida os campos internos de capabilities.<kind>; essa validação pertence ao addon.
  • O builder visual edita energy, fluid, chemical, mana e essentia. Para um recurso novo, edite o JSON manualmente ou estenda o builder.
  • O builder converte resource_bar importado para chemical_bar, exceto quando capability é mana; resource_list é tratado como o caso especial de essentia. Isso precisa ser ajustado antes de usar o builder para outros recursos.
  • Definições que declaram um tipo ausente precisam ficar em um datapack ou jar separado, ou ser protegidas por condições de carregamento.
  • O codec de rede de receitas usa o formato genérico id + amount; campos extras do seu codec podem não sobreviver à sincronização.

Para o exemplo completo de um addon real, consulte o addon de Mekanism incluído no projeto e a wiki principal em Wiki do desenvolvedor.