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:
- Implementa
MultiblockResourceTypepara descrever o tipo. - Implementa
MultiblockResourceStoragepara manipular os tanques. - Registra o tipo em
MultiblockAddonsdurante a construção do mod. - 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 seucreateStoragee o seudescribeTanks.
O que o base faz
| Área | Comportamento 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. |
| GUI | Renderiza resource_bar com capability e slot. |
| Receitas | Despacha o campo type para o codec do addon. |
| Persistência | Salva e restaura StoredResource por kind, tank, id e amount. |
| JEI | Usa 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étodo | Responsabilidade |
|---|---|
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étodo | Responsabilidade |
|---|---|
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:
describeTanksecreateStoragedevem produzir os mesmos ids e capacidades.inserteextractcomsimulate = truenão podem alterar estado.snapshoterestoredevem ser simétricos.- Capacidade inválida no JSON deve ser rejeitada com log claro.
- Tanque vazio pode usar
id = ""eamount = 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 tipochemicale é redirecionado pararesource_bar. O tipomanatambém usachemical_barno JSON final, comcapability: "mana"eslot: "mana". Para outros recursos, useresource_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étodo | Uso |
|---|---|
addInput / addOutput | Desenha o recurso em um slot visível. |
addInvisibleInput / addInvisibleOutput | Registra o recurso para busca e receitas sem ocupar um slot visual. |
Overloads com width/height | Permitem 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.
describeTanksecreateStorageconcordam em ids, capacidades e filtros.validateResourceIdé usado pelo codec de receita e rejeita ids desconhecidos.snapshot/restoreeserialize/deserializesão simétricos.- A GUI usa
resource_barcom 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,manaeessentia. Para um recurso novo, edite o JSON manualmente ou estenda o builder. - O builder converte
resource_barimportado parachemical_bar, exceto quandocapabilityémana;resource_listé tratado como o caso especial deessentia. 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.