Infinity Nexus Multiblock Wiki
Guia do desenvolvedor Minecraft 26.1.2 NeoForge 26.1.2.121 schema_version 2

#Wiki do Desenvolvedor

Guia prático para criar máquinas multibloco com o Infinity Nexus Multiblock.

  • Minecraft: 26.1.2
  • NeoForge: 26.1.2.121
  • Java: 25
  • Idioma dos exemplos: português
  • Schema atual: schema_version: 2

Este guia documenta tudo o que o JSON aceita hoje e mostra exemplos completos. O objetivo é que você consiga sair de uma ideia e chegar a uma máquina formável, com inventário, energia, fluidos, GUI e receita.

Para montar e validar a definição visualmente, abra o Builder de multiblocos. Ele exporta o mesmo JSON descrito neste guia.

#Índice

  1. Como uma máquina funciona
  2. Arquivos, pasta e ID
  3. Estrutura completa do JSON
  4. Pattern
  5. Matchers
  6. Slots de item
  7. Energia e fluidos
  8. GUI
  9. Controller único e receita
  10. Receitas
  11. Herança e templates
  12. Priority, tier e sobreposição
  13. Exportar e importar
  14. Reload e ciclo de vida
  15. Exemplos completos
  16. Erros comuns
  17. Checklist final
  18. Limitações atuais

#1. Como uma máquina funciona

Uma máquina é a combinação de três partes:

  1. O controller único do mod. O bloco, o block entity e o item são registrados uma única vez como infinity_nexus_multiblock:multiblock_controller. Toda definição usa esse mesmo controller; não existe bloco controller por máquina.
  2. Uma definição JSON. Ela diz qual é o pattern, quais blocos formam a estrutura, quais slots existem, qual GUI usar, quais capabilities existem e qual receita processar. O vínculo com o controller é feito pelo componente infinity_nexus_multiblock:multiblock_definition, cujo valor é o id da definição.
  3. Um pattern formado no mundo. O jogador coloca o controller virado para a direção correta e clica nele para montar. Quando todas as células batem, o controller fica formed=true, abre a GUI e passa a processar receitas.

Fluxo resumido:

Startup: registra o controller, o item e o tipo de receita
JSON: schema_version 2 + pattern + slots + capabilities + GUI + recipe opcional
Mundo: controller é colocado com o componente de definição e clicado
Loader: valida o JSON e cria a definição
Estrutura: pattern é validado com rotação
Máquina: inventário, energia, fluidos, GUI e receita funcionam

Não há mais controller nem recipe_type na definição. O controller compartilhado exibe o nome da definição via MultiblockDefinition#displayName(); a chave de tradução é multiblock.<namespace>.<path> e o fallback é o path formatado, como fabrica_de_voxel_cube -> Fabrica De Voxel Cube. O campo opcional textures permite especializar as texturas do controller por definição; veja a seção 9.2.

No JEI, a categoria de receita é filtrada pelo componente de definição do controller. A categoria de estrutura ainda usa o controller genérico como catalisador e pode listar todas as estruturas; trate isso como limitação conhecida até o filtro por definição ser implementado.

A categoria de receita do JEI usa o mesmo layout da GUI da máquina para item_slots x/y e elementos slot, fluid_bar, energy_bar, arrow, entity e title; o fundo é textures/gui/jei_base.png. A categoria de estrutura usa um painel próprio.

Na GUI da máquina, clicar na seta ou na barra de progresso abre as receitas daquela definição no JEI. Na categoria JEI, a transferência move ingredientes de item para slots input compatíveis; fluidos são inseridos manualmente.

#2. Arquivos, pasta e ID

#2.1 Definição de multibloco

data/<namespace>/multiblock/<arquivo>.json

O campo id precisa ser exatamente <namespace>:<arquivo>.

Exemplo:

data/minhamod/multiblock/fornalha.json
"id": "minhamod:fornalha"

Se o id não bater com o caminho, a definição é rejeitada com:

Definition id ... does not match file id ...

#2.2 Receita

data/<namespace>/recipe/<arquivo>.json

Toda receita de máquina usa "type": "infinity_nexus_multiblock:multiblock" e declara "definition": "<namespace>:<path>". Receitas do controller são geradas pelo mod em data/<namespace>/recipe/controller/<path>.json; veja a seção 9.

#2.3 Datapack

meu_datapack/
  pack.mcmeta
  data/
    minhamod/
      multiblock/
        fornalha.json
      recipe/
        ferro.json

Exemplo de pack.mcmeta para 26.1.2:

{
  "pack": {
    "description": "Minhas máquinas",
    "min_format": [101, 1],
    "max_format": 101
  }
}

Depois de colocar o datapack em world/datapacks, use /reload ou reinicie o servidor.

Datapacks e KubeJS podem adicionar ou sobrescrever definições e receitas. O controller é único e já registrado pelo mod, então qualquer namespace pode usar a mesma estrutura. A receita shaped opcional do controller é gerada a partir do JSON empacotado no jar do mod ou de kubejs/data.

#3. Estrutura completa do JSON

#3.1 Campos de nível raiz

Campo Obrigatório Tipo Padrão Regras
schema_version sim inteiro — Hoje só aceita 2.
id sim identifier — Precisa ser igual ao caminho do arquivo.
type sim string — recipe ou storage.
priority não inteiro 0 Usado para resolver sobreposição entre estruturas. Pode ser negativo.
tier não inteiro 1 Mínimo 1. Hoje é apenas metadado; não altera comportamento.
recipe não objeto ausente Receita shaped de crafting table do controller, lida do jar do mod e de kubejs/data; não é lida de datapacks comuns. Veja a seção 9.
inventory_rows não inteiro 3 De 1 a 6. Usado só quando item_slots está vazio.
item_slots não lista [] Define os slots do inventário. Veja a seção 6.
capabilities não objeto vazio Energia e fluidos. Veja a seção 7.
capability_ports não objeto ausente Restringe quais blocos membros expõem item, energia e fluido. Veja a seção 7.3.
textures não objeto ausente Sobrescreve as texturas do controller por definição. Aceita front, side, top, bottom, particle e active. Veja a seção 9.2.
gui não objeto ausente Layout padrão ou customizado. Veja a seção 8.
pattern sim para máquina objeto — Obrigatório para uma definição registrada. Templates podem omitir.

#3.2 Campos de herança

Esses campos são processados antes do schema normal:

Campo Obrigatório Tipo Padrão Regras
extends não identifier — ID do pai. Não use junto com family.
family não identifier — Alias de extends. Não use junto com extends.
overrides não objeto — Aplicado depois dos campos do filho; vence em caso de conflito.
template não booleano false Se true, o arquivo não é registrado como máquina.

Regras:

  • extends e family são a mesma coisa; use apenas um.
  • O pai é resolvido recursivamente.
  • Objetos são mesclados recursivamente.
  • Listas substituem a lista inteira.
  • overrides não pode definir extends, family, overrides ou template.
  • Um template com template: true é sempre ignorado como máquina, mesmo tendo pattern.
  • Um arquivo sem pattern é tratado como template quando é referenciado por outro. Se não for referenciado, é erro de definição.

#3.3 Exemplo mínimo

{
  "schema_version": 2,
  "id": "minhamod:minha_maquina",
  "type": "storage",
  "inventory_rows": 3,
  "pattern": {
    "anchor": "C",
    "layers": [
      [
        "III",
        "III",
        "III"
      ],
      [
        "III",
        "III",
        "ICI"
      ],
      [
        "III",
        "III",
        "III"
      ]
    ],
    "matchers": {
      "I": "minecraft:iron_block"
    }
  }
}

Esse JSON já carrega como definição em qualquer namespace. O item controller recebe o componente de definição com minhamod:minha_maquina; ao colocar o bloco, o block entity usa esse ID. Não é necessário criar bloco por máquina; texturas por definição são opcionais via textures.

#3.4 Migrar do schema 1

  1. Troque "schema_version": 1 por "schema_version": 2.
  2. Remova o objeto controller; o bloco e o block entity agora são compartilhados. Se quiser texturas por máquina, use o novo campo top-level textures.
  3. Remova recipe_type da definição; toda receita de máquina usa infinity_nexus_multiblock:multiblock.
  4. Em cada receita, troque o tipo antigo por "type": "infinity_nexus_multiblock:multiblock" e adicione "definition": "<id da definição>".
  5. Mantenha o campo top-level recipe apenas se quiser gerar a receita shaped do controller.
  6. Gere o controller com /inmb give <id> ou pela aba criativa e rode /reload.

#4. Pattern

#4.1 Regras

  • layers é uma lista de camadas, da base para o topo.
  • Cada camada é uma lista de linhas.
  • Todas as camadas precisam ter a mesma quantidade de linhas.
  • Todas as linhas precisam ter a mesma largura.
  • Espaços (" ") são ignorados como células, mas continuam contando para a largura.
  • anchor é opcional e usa C por padrão.
  • Deve existir exatamente um símbolo de âncora.
  • Cada símbolo usado, exceto a âncora, precisa ter um matcher.
  • A célula da âncora é o controller. Ela não entra na lista de membros e não é testada pelo matcher.
  • O matcher da âncora é opcional e, se existir, é ignorado.
  • A orientação canônica é com o controller virado para SOUTH.
  • Ao validar, montar ou pré-visualizar com o controller em outra direção, posições e states direcionais são rotacionados.

#4.2 Ordem das linhas e colunas

Na orientação canônica (SOUTH):

  • a camada 0 é a mais baixa;
  • a linha 0 fica no norte;
  • linhas seguintes avançam para o sul;
  • a coluna 0 fica no oeste;
  • colunas seguintes avançam para o leste;
  • a âncora C é a posição do controller.

Exemplo de uma camada 3x3:

[
  "III",
  "I I",
  "III"
]

A linha do meio tem um espaço no centro. O espaço não é uma célula, mas a linha continua com largura 3.

#4.3 Rotação

FACING do controller Rotação aplicada
SOUTH nenhuma
NORTH 180 graus
EAST 90 graus anti-horário
WEST 90 graus horário

O JSON sempre descreve a máquina olhando para SOUTH. Se você escrever facing: "north" em um matcher, esse valor será rotacionado junto com a estrutura quando o controller estiver em outra direção.

#4.4 Exemplo de pattern 3x3x3

"pattern": {
  "anchor": "C",
  "layers": [
    [
      "III",
      "III",
      "III"
    ],
    [
      "III",
      "III",
      "ICI"
    ],
    [
      "III",
      "III",
      "III"
    ]
  ],
  "matchers": {
    "I": "minecraft:iron_block"
  }
}

O controller fica na face sul da camada do meio. O resto do cubo é minecraft:iron_block.

#4.5 Tamanho

O loader não impõe um limite de tamanho para o pattern. O limite configurável em export.pattern_scan_limit (padrão 256 blocos) vale para a exportação no criativo, não para a definição.

#5. Matchers

pattern.matchers é um objeto cujo nome da chave é um único caractere e cujo valor pode ser:

  1. uma string com ID de bloco;
  2. uma string com tag de bloco, começando com #;
  3. um objeto com block ou tag e, opcionalmente, state.

#5.1 String de bloco

"matchers": {
  "I": "minecraft:iron_block"
}

O bloco precisa existir no registro.

#5.2 String de tag

"matchers": {
  "I": "#c:storage_blocks/iron"
}

O # é obrigatório nesse formato. A tag é resolvida no registro de blocos.

#5.3 Objeto de matcher

Campo Obrigatório Tipo Regras
block um dos dois string ID de bloco. Não use junto com tag.
tag um dos dois string ID de tag. Pode ter # ou não. Não use junto com block.
state não objeto Mapa de propriedade para valor, ambos strings. Funciona com block ou tag.

Exatamente um entre block e tag precisa existir.

Exemplo com bloco e state:

"matchers": {
  "S": {
    "block": "minecraft:oak_stairs",
    "state": {
      "facing": "north",
      "half": "bottom",
      "shape": "straight",
      "waterlogged": "false"
    }
  }
}

Exemplo com tag:

"matchers": {
  "S": {
    "tag": "#minecraft:stairs"
  }
}

Exemplo com tag e state:

"matchers": {
  "S": {
    "tag": "#minecraft:stairs",
    "state": {
      "facing": "south"
    }
  }
}

Com tag + state, o bloco precisa pertencer à tag e ter as propriedades informadas; membros da tag que não têm essas propriedades são ignorados no match.

#5.4 Como o state funciona

  • Apenas as propriedades listadas em state são verificadas.
  • Propriedades omitidas são ignoradas.
  • Um objeto sem state aceita qualquer state do bloco (ou de qualquer membro da tag).
  • Um objeto com state aceita qualquer combinação que bata com as propriedades informadas.
  • Com tag, cada membro é avaliado individualmente: o bloco precisa estar na tag e ter todas as propriedades informadas.
  • O nome da propriedade e o valor precisam existir no bloco. Em um matcher de tag, membros sem a propriedade ou sem o valor válido não casam.
  • Valores são strings: "true", "false", "north", "1", etc.
  • O state é relativo à orientação canônica SOUTH e é rotacionado junto com a estrutura.

Exemplo de matcher parcial para escada:

"matchers": {
  "S": {
    "block": "minecraft:oak_stairs",
    "state": {
      "facing": "south",
      "half": "bottom"
    }
  }
}

Esse matcher aceita a escada virada para sul e na metade de baixo, independentemente de shape ou waterlogged.

#5.5 O que não existe

  • NBT;
  • listas de alternativas (any);
  • matchers opcionais;
  • expressões ou lógica.

Se precisar de alternativas, use uma tag de bloco.

#6. Slots de item

#6.1 Tamanho do inventário

  • Se item_slots tem entradas, o inventário tem exatamente a quantidade de entradas.
  • Se item_slots está vazio ou ausente, o inventário tem inventory_rows * 9 slots.
  • inventory_rows é validado mesmo quando ignorado, então use de 1 a 6.

Exemplos:

Configuração Tamanho
sem item_slots, inventory_rows: 3 27
sem item_slots, inventory_rows: 6 54
4 entradas em item_slots 4

#6.2 Campos de item_slots[]

Campo Obrigatório Tipo Padrão Regras
id sim string — Único e não vazio.
role sim string — input, output, fuel, upgrade, component, storage ou fluid.
filter não string sem filtro ID de item ou tag com #.
limit não inteiro 64 De 1 a 64. O limite efetivo também considera o tamanho máximo do stack.
faces não objeto padrão do role insert e/ou extract, cada um com uma lista de direções.
x não inteiro ausente Posição horizontal na GUI customizada. Precisa de y. Não pode ser negativo.
y não inteiro ausente Posição vertical na GUI customizada. Precisa de x. Não pode ser negativo.

faces:

"faces": {
  "insert": ["north", "south"],
  "extract": []
}
  • insert: faces que podem inserir no slot.
  • extract: faces que podem extrair do slot.
  • Se um dos campos for omitido, vale o padrão do role.
  • Lista vazia desativa a operação.
  • Direções: north, south, east, west, up, down.

#6.3 Faces padrão por role

Role Insere por Extrai por Uso atual
input todas nenhuma Participa do matching de receita.
output nenhuma todas Recebe o resultado da receita.
fuel todas nenhuma Sem comportamento de receita embutido.
upgrade todas nenhuma Sem comportamento de receita embutido.
component todas nenhuma Sem comportamento de receita embutido.
storage todas todas Armazenamento/automação.
fluid todas nenhuma Slot de item; não é um tanque de fluido.

Apenas input e output têm comportamento automático no processamento de receitas. Os outros roles são úteis para automação, filtros, limites e GUIs; outros mods podem acessá-los pelo inventário.

#6.4 Filtro e limite

  • filter aceita ID de item (minecraft:iron_ingot) ou tag (#c:ingots/iron).
  • O filtro vale para o jogador e para automação.
  • O limite vale para o slot e também para o resultado.
  • O jogador pode retirar de qualquer slot visível, mesmo que a face não permita extração por automação.

#6.5 Faces e rotação

As faces de item_slots são direções do mundo. Elas não são rotacionadas junto com o FACING do controller.

Exemplo: "insert": ["north"] continua significando norte do mundo, mesmo que a máquina esteja virada para leste. Para evitar confusão, use faces amplas ou documente a orientação da sua máquina.

#6.6 Slots e GUI

Há dois jeitos de posicionar slots na GUI customizada:

Formato atual: item_slots[] com x/y.

"item_slots": [
  {
    "id": "input_0",
    "role": "input",
    "x": 44,
    "y": 17
  },
  {
    "id": "output_0",
    "role": "output",
    "x": 116,
    "y": 26
  }
]
  • Slots com x/y aparecem na GUI.
  • Slots sem x/y ficam ocultos, mas continuam existindo para automação e receitas.
  • Todos os slots visíveis precisam caber em gui.width/gui.height.

Formato antigo: elementos slot dentro de gui.elements.

{
  "type": "slot",
  "slot": "input_0",
  "x": 44,
  "y": 17
}
  • O slot precisa existir em item_slots[].
  • Cada slot pode aparecer uma vez.
  • Não misture elementos slot com x/y em item_slots[].
  • O tamanho do slot é fixo em 18x18; width/height do elemento são ignorados.

No layout padrão (sem gui.elements), slots com x/y que caibam em 176x166 são respeitados; os demais são distribuídos automaticamente. A grade usa 9 colunas, ou 8 quando há barras de energia/fluido ou barra de progresso.

#6.7 Exemplo de item_slots

"item_slots": [
  {
    "id": "input_0",
    "role": "input",
    "filter": "minecraft:raw_iron",
    "limit": 16
  },
  {
    "id": "input_1",
    "role": "input",
    "filter": "minecraft:coal"
  },
  {
    "id": "output_0",
    "role": "output",
    "filter": "minecraft:iron_ingot"
  },
  {
    "id": "upgrade_0",
    "role": "upgrade",
    "faces": {
      "insert": ["north", "south"],
      "extract": []
    }
  }
]

#7. Energia e fluidos

capabilities é opcional e fica no nível raiz. item_slots não fica dentro de capabilities.

#7.1 Energia

"capabilities": {
  "energy": {
    "id": "energy",
    "capacity": 100000,
    "max_receive": 1000,
    "max_extract": 0
  }
}
Campo Obrigatório Tipo Padrão Regras
id sim string — Não vazio. Usado pela GUI e para identificar a capability.
capacity sim inteiro — Mínimo 1, em FE.
max_receive não inteiro 0 FE aceitos por operação de inserção. 0 desativa a inserção.
max_extract não inteiro 0 FE liberados por operação de extração. 0 desativa a extração.

#7.2 Fluidos

"capabilities": {
  "fluids": [
    {
      "id": "water_tank",
      "capacity": 10000,
      "max_receive": 1000,
      "max_extract": 0,
      "filter": "minecraft:water",
      "port": "F"
    }
  ]
}
Campo Obrigatório Tipo Padrão Regras
id sim string — Único entre os tanques e diferente do energy.id.
capacity sim inteiro — Mínimo 1, em mB.
max_receive não inteiro 0 mB aceitos por inserção. 0 desativa.
max_extract não inteiro 0 mB liberados por extração. 0 desativa.
filter não string sem filtro ID de fluido ou tag com #.
port não string qualquer porta Key do pattern, ID de bloco ou tag que dá acesso ao tanque.

O port é opcional. Quando definido, o tanque só é exposto nos blocos de fluido que casarem com esse seletor; a key precisa existir no pattern e, quando capability_ports.fluid existe, também precisa estar selecionada lá. Tanques sem port continuam acessíveis por qualquer porta de fluido. Isso permite, por exemplo, um tanque de água acessível só pela key F e um de lava só pela key L.

As portas respeitam max_receive/max_extract e filter do tanque. O slot fluid usa os tanques como origem/destino manual: ele ignora max_receive e max_extract (limites de automação), mas respeita capacity e filter. A troca é all-or-nothing por stack: N baldes exigem N*1000 mB livres no tanque.

#7.3 Portas de capability (capability_ports)

capability_ports é opcional e fica no nível raiz, irmão de capabilities.

"capability_ports": {
  "item": ["I"],
  "energy": ["C"],
  "fluid": ["F", "#minecraft:glass"]
}
Campo Obrigatório Tipo Padrão Regras
item não lista todos Blocos que expõem a capability de item.
energy não lista todos Blocos que expõem a capability de energia.
fluid não lista todos Blocos que expõem as capabilities de fluido.

Cada item da lista aceita:

  • um símbolo de 1 caractere do pattern (C, I, F...);
  • um ID de bloco (namespace:path);
  • uma tag de bloco (#namespace:path).

Regras:

  • As três chaves são independentes. Omitir uma chave expõe aquela capability em todos os blocos formados; lista vazia ([]) não expõe em nenhum.
  • O controller só expõe uma capability se ele próprio for selecionado (pelo símbolo C ou pelo ID do bloco controller).
  • Um símbolo que não existe no pattern falha o carregamento da definição.
  • A whitelist controla apenas as capabilities do multiblock; capabilities nativas de um bloco membro continuam disponíveis.
  • Não há configuração por face: um bloco selecionado expõe a capability em todas as suas faces.
  • item não é uma chave de capabilities: todo multiblock tem inventário (item_slots ou inventory_rows) e expõe item por padrão. Use capability_ports.item para limitar as portas ou [] para não expor item.
  • energy e fluid só têm efeito quando a máquina define capabilities.energy ou pelo menos um tanque em capabilities.fluids. Um tanque somente de fluido é possível com capabilities.fluids e, se quiser esconder o inventário, "capability_ports": {"item": []}. A GUI customizada pode ter só fluid_bar e player_inventory, sem item_slots.

As portas são recalculadas na próxima validação da estrutura (a cada 20 ticks ou quando um vizinho muda). /reload atualiza a definição e agenda essa revalidação; não é preciso quebrar e montar de novo.

No builder, os campos de capability_ports ficam na etapa Capabilities. Campo vazio omite a chave e libera a capability em qualquer bloco; [] não expõe nenhum bloco; símbolos, IDs e tags podem ser separados por vírgula ou espaço. As portas energy/fluid ficam desabilitadas enquanto a capability correspondente não existir.

#7.4 Onde as capabilities aparecem

  • Padrão: todos os blocos membros formados e o controller expõem as capabilities configuradas.
  • Com capability_ports: apenas os blocos selecionados para cada capability.
  • Itens: um hopper encostado em qualquer porta de item acessa o mesmo inventário.
  • Energia e fluidos: normalmente expostos só no controller, incluindo C na lista correspondente.
  • Tanques com port: só aparecem nas portas de fluido que casarem com a key/bloco/tag configurada; as demais portas veem apenas os tanques sem port (e os que casarem com elas).
  • O energy.id e os fluids[].id são usados pela GUI para localizar as barras. Eles não mudam as portas.

#7.5 Energia em receitas

Um input de energia usa { "type": "energy", "amount": 1000 }. A maquina precisa ter capabilities.energy; sem armazenamento, a receita nem inicia.

O custo e distribuido ao longo dos ticks. Uma receita com amount: 1000 e time: 100 consome aproximadamente 10 FE por tick. Se a energia acabar, o progresso pausa. Um output de energia e inserido no storage ao completar.

#7.6 Fluidos em receitas

Se a receita tem inputs do tipo fluid, a maquina precisa ter tanques suficientes. Cada ingrediente de fluido procura um tanque que aceite o fluido e tenha a quantidade necessaria. Cada tanque satisfaz no maximo um ingrediente por craft.

#7.7 Reload

/reload atualiza a definição, mas não recria nem reconfigura capabilities de energia/fluidos já existentes. Se você mudar capacity, max_receive, max_extract ou filter, quebre e coloque o controller de novo, ou reinicie o mundo, para criar as capabilities com os novos valores.

#8. GUI

#8.1 Layout padrão

Sem gui, ou com gui.elements vazio, o layout é automático:

  • slots do inventário em grade automática (9 colunas, ou 8 quando há barras/progresso); posições x/y que caibam em 176x166 são respeitadas;
  • título no topo;
  • uma barra de energia, se existir;
  • uma barra para cada tanque de fluido, se existirem;
  • uma barra de progresso à direita, se type=recipe;
  • inventário do jogador abaixo dos slots;
  • largura fixa em 176 e altura calculada para caber tudo (mínimo 166).

Se você definir gui sem elements, ainda pode definir texture, width, height, texture_width e texture_height; o layout continua automático, mas usa esses valores.

#8.2 Layout customizado

Com gui.elements não vazio:

  • item_slots só é obrigatório quando houver elementos slot ou posições x/y; uma GUI somente de fluidos pode omitir slots de item;
  • os slots visíveis são os que têm x/y em item_slots[], ou os elementos slot no formato antigo;
  • slots sem posição ficam ocultos, mas funcionam para automação/receita;
  • não misture x/y em item_slots[] com elementos slot;
  • exatamente um player_inventory é obrigatório;
  • energy_bar.capability precisa ser igual a energy.id;
  • fluid_bar.capability precisa ser igual a um fluids[].id;
  • progress_bar, arrow e entity só são aceitos em type=recipe;
  • slots, player inventory, barras e entity precisam caber em width/height;
  • title e text não têm validação de limites; cuidado para não desenhar fora da tela.
  • Em title/text, x/y representam o canto superior esquerdo da linha de texto, não a baseline; a tela compensa 1 px para alinhar o desenho ao referencial do builder.
  • No builder, novos elementos começam com o layout do spawner: title em 8,4, text em 8,75, player_inventory em 8,84, energy_bar/fluid_bar/progress_bar em 158/148/138,16 com 8x54, e entity em 82,16 com 54x54.
  • Slots novos começam em 8,16 e avançam 18 px por coluna, com 9 colunas por linha (ou 8 quando há barras de energia/fluido ou barra de progresso) antes de descer para a próxima linha.

#8.3 Campos de gui

Campo Obrigatório Tipo Padrão Regras
texture não identifier sem textura Caminho completo do PNG, por exemplo minhamod:textures/gui/minha_maquina.png. Sem textura, a tela desenha um painel cinza.
width não inteiro 176 De 1 a 4096. Área visível da GUI.
height não inteiro 166 De 1 a 4096. Área visível da GUI.
texture_width não inteiro 256 De 1 a 4096. Largura da textura.
texture_height não inteiro 256 De 1 a 4096. Altura da textura.
elements não lista [] Se vazio, usa o layout padrão.

#8.4 Campos de gui.elements[]

Campo Obrigatório Tipo Padrão Regras
type sim string — Veja a tabela de tipos abaixo.
x não inteiro 0 Posição horizontal.
y não inteiro 0 Posição vertical.
width não inteiro 16 De 0 a 4096. Barras e entity precisam de valor positivo.
height não inteiro 16 De 0 a 4096. Barras e entity precisam de valor positivo.
text não string "" Chave de tradução ou texto literal.
slot não string "" Só para o tipo slot; ID de item_slots[].
capability não string "" ID de energia ou tanque para barras.
color não inteiro ou string depende do tipo ARGB em inteiro decimal ou hexadecimal. Padrões: 0xFF404040 (texto), 0xFFFF0000 (energy_bar) e 0xFF00AA00 (progress_bar). Alpha 0 vira 0xFF.
shadow não booleano true Sombra do texto.
direction não string up up, down, left ou right.
u não inteiro -1 Origem horizontal do sprite. Se -1, usa x.
v não inteiro -1 Origem vertical do sprite. Se -1, usa y.

O campo color é ARGB e aceita inteiro decimal ou string hexadecimal. Exemplos equivalentes: 4285257290, "0xFF6BD64A", "#6BD64A" ou "#FF6BD64A".

#8.5 Tipos de elemento

Tipo O que faz Campos importantes
title Desenha o título. Se text estiver vazio, usa o nome do bloco. x, y, text, color, shadow
text Desenha um texto. Se text estiver vazio, não desenha. x, y, text, color, shadow
player_inventory Desenha o rótulo do inventário do jogador e posiciona os slots do jogador. Exatamente um. x, y, text, color, shadow
slot Formato antigo para posicionar um slot. Tamanho fixo 18x18. slot, x, y
energy_bar Barra de energia. capability, x, y, width, height, direction, color
fluid_bar Barra de fluido. capability, x, y, width, height
progress_bar Barra de progresso da receita. x, y, width, height, direction, color, u, v
arrow Seta de progresso, como a da fornalha. x, y, width, height, direction, u, v
entity Área que renderiza as entidades de inputs e outputs da receita. x, y, width, height

#8.6 Detalhes por tipo

title e text

  • text é uma chave de tradução ou um texto literal.
  • title vazio usa o nome do bloco.
  • Se não houver nenhum title, a tela desenha o título padrão em 8,6.
  • Não há validação de limites para title/text.

player_inventory

  • Ocupa 162x76 (3 linhas + hotbar).
  • O rótulo é desenhado 11 pixels acima de y.
  • text vazio usa container.inventory.
  • Precisa caber em width/height.

slot

  • slot precisa ser o ID de um item_slots[].
  • O slot é desenhado em x,y com 18x18.
  • width/height, text e capability são ignorados.
  • Cada slot pode aparecer uma vez.

energy_bar

  • capability precisa ser igual ao energy.id.
  • width/height precisam ser positivos.
  • direction define o sentido do preenchimento: up, down, left ou right.
  • color define a cor do preenchimento.
  • Tooltip mostra energia/capacidade em FE.
  • Sem textura, desenha um fundo escuro. Com textura, a textura precisa incluir o fundo.

fluid_bar

  • capability precisa ser igual a um fluids[].id.
  • width/height precisam ser positivos.
  • Sempre preenche de baixo para cima; direction e color são ignorados.
  • Tooltip mostra o fluido e a quantidade.
  • Sem textura, desenha um fundo escuro.

progress_bar

  • Só em type=recipe.
  • width/height precisam ser positivos.
  • direction define o sentido do preenchimento.
  • color define a cor do preenchimento.
  • Com textura, desenha o sprite em u/v como fundo e depois o preenchimento.
  • Sem textura, desenha o fundo escuro.
  • Tooltip mostra a porcentagem do craft atual.

arrow

  • Só em type=recipe.
  • width/height precisam ser positivos.
  • direction define o sentido do recorte.
  • Usa u/v como origem do sprite.
  • Precisa de textura; sem textura, a seta não é desenhada.
  • Não desenha fundo.
  • Tooltip mostra a porcentagem do craft atual.

entity

  • Só em type=recipe.
  • width/height precisam ser positivos e caber na GUI.
  • As entidades vêm dos inputs e outputs do tipo entity da receita exibida; o elemento não tem campo de ID.
  • O fundo é preto e a borda é cinza, no mesmo estilo das barras.
  • Várias entidades são distribuídas lado a lado dentro da área; o tooltip do JEI identifica entrada/saída e a chance.
  • Renderiza no JEI e no controller; no controller, só aparece quando uma receita está ativa/reconhecida.
  • Entidades vivas usam o renderer de inventário; entidades não-vivas usam o render state genérico.

#8.7 Exemplo de GUI customizada

O arquivo exemplos/exemplo_storage.json usa item_slots[] com x/y, barras e player_inventory.

Trecho:

"gui": {
  "width": 176,
  "height": 166,
  "texture_width": 256,
  "texture_height": 256,
  "elements": [
    {
      "type": "title",
      "text": "gui.minhamod.minha_maquina.title",
      "x": 8,
      "y": 6
    },
    {
      "type": "energy_bar",
      "capability": "energy",
      "x": 8,
      "y": 17,
      "width": 12,
      "height": 52,
      "direction": "up"
    },
    {
      "type": "fluid_bar",
      "capability": "water_tank",
      "x": 26,
      "y": 17,
      "width": 12,
      "height": 52
    },
    {
      "type": "player_inventory",
      "x": 8,
      "y": 84,
      "text": "container.inventory"
    }
  ]
}

#8.8 Exemplo com slot antigo e progresso

"gui": {
  "width": 176,
  "height": 166,
  "elements": [
    { "type": "title", "x": 8, "y": 6 },
    { "type": "energy_bar", "capability": "energy", "x": 8, "y": 17, "width": 12, "height": 52 },
    { "type": "slot", "slot": "input_0", "x": 44, "y": 17 },
    { "type": "slot", "slot": "input_1", "x": 44, "y": 35 },
    { "type": "slot", "slot": "output_0", "x": 116, "y": 26 },
    { "type": "progress_bar", "x": 80, "y": 35, "width": 12, "height": 20, "direction": "right" },
    { "type": "player_inventory", "x": 8, "y": 84 }
  ]
}

Nesse formato, os item_slots[] não podem ter x/y.

#9. Controller único e receita

#9.1 O controller compartilhado

Todas as definições usam o mesmo bloco, block entity e item:

infinity_nexus_multiblock:multiblock_controller

O vínculo com a definição é o componente:

infinity_nexus_multiblock:multiblock_definition = <namespace>:<path>

A aba criativa gera uma variante do controller para cada definição carregada. Colocar um controller sem esse componente é bloqueado. Ao quebrar, clonar ou dropar o bloco, o componente é preservado.

Para obter uma variante:

/inmb give minhamod:minha_maquina

/inmb list lista as definições e cria links clicáveis para o comando give.

#9.2 Texturas por definição

O campo top-level textures é opcional e sobrescreve as texturas do modelo compartilhado para uma definição. O bloco e o item continuam os mesmos; o cliente re-bakeia o modelo do controller quando a definição ou o estado processing muda.

{
  "textures": {
    "front": "minhamod:block/fornalha_front",
    "side": "minhamod:block/fornalha_side",
    "top": "minhamod:block/fornalha_top",
    "bottom": "minhamod:block/fornalha_top",
    "particle": "minhamod:block/fornalha_front",
    "active": {
      "front": "minhamod:block/fornalha_front_on",
      "side": "minhamod:block/fornalha_side_on"
    }
  }
}

Regras:

  • Faces aceitas: front, side, top, bottom e particle.
  • Os valores são identifiers completos, como minecraft:block/stone, e a textura precisa existir em assets/<namespace>/textures/block/... para entrar no atlas de blocos.
  • Faces omitidas usam o modelo/textura padrão do controller.
  • active é opcional e é aplicado enquanto o controller está processando. Faces omitidas em active herdam a textura idle correspondente.
  • particle vazio usa front; sem front, usa a partícula padrão do modelo.
  • Como os demais objetos, textures é mesclado recursivamente por extends, family e overrides; o objeto active é mesclado face a face.
  • Se uma textura não estiver no atlas de blocos do cliente, o controller volta ao modelo padrão e registra um aviso no log; o JSON continua carregando no servidor.
  • A troca idle/active não exige quebrar o bloco; ela acompanha o estado processing do controller.

#9.3 Como o vínculo é aplicado

  1. O item possui o componente com o id da definição.
  2. Ao colocar o bloco, o componente é copiado para o block entity.
  3. O block entity carrega a definição pelo id e configura inventário, capabilities, GUI e receitas.
  4. Ao clicar com o bloco ainda não formado, a estrutura é validada.
  5. Se o pattern bater, o controller passa a formed=true e processa receitas.

O mesmo controller pode representar qualquer máquina; o bloco é compartilhado e as texturas podem ser especializadas por definição via textures.

#9.4 Receita shaped opcional do controller

O campo top-level recipe descreve a receita de crafting table que produz o controller já com o componente daquela definição:

{
  "recipe": {
    "pattern": [
      "ICI",
      "CGC",
      "ICI"
    ],
    "key": {
      "I": "minecraft:iron_ingot",
      "C": "minecraft:copper_ingot",
      "G": "minecraft:glass"
    }
  }
}

Regras:

  • pattern é uma lista de 1 a 3 strings de crafting shaped.
  • key mapeia cada símbolo a um ingredient.
  • A receita gerada produz infinity_nexus_multiblock:multiblock_controller com infinity_nexus_multiblock:multiblock_definition igual ao id do arquivo.
  • A receita é gerada automaticamente pelo pack embutido infinity_nexus_multiblock:controller_recipes.
  • Definições são lidas do jar do mod e de kubejs/data; datapacks comuns carregam a máquina, mas não geram a receita de crafting do controller.
  • Templates e definições sem pattern não geram receita.
  • Uma definição precisa estar em schema_version: 2 para gerar receita.

O arquivo gerado aparece como:

data/<namespace>/recipe/controller/<path>.json

Exemplo de resultado:

{
  "type": "minecraft:crafting_shaped",
  "category": "misc",
  "pattern": ["ICI", "CGC", "ICI"],
  "key": {
    "I": "minecraft:iron_ingot",
    "C": "minecraft:copper_ingot",
    "G": "minecraft:glass"
  },
  "result": {
    "id": "infinity_nexus_multiblock:multiblock_controller",
    "count": 1,
    "components": {
      "infinity_nexus_multiblock:multiblock_definition": "minhamod:minha_maquina"
    }
  }
}

#9.5 API Java

Para integrações em Java, use:

  • ModBlocks.controllerWithDefinition(Identifier) para criar o item com o componente.
  • MultiblockControllerBlockEntity#definitionId() para ler o ID configurado.
  • MultiblockControllerBlockEntity#definition() para obter a definição carregada.
  • MultiblockDefinitions#get(Identifier) e MultiblockDefinitions#all() para consultar definições.

Não é necessário registrar um MultiblockControllerItem, bloco ou block entity por máquina.

#10. Receitas

#10.1 Arquivo

data/<namespace>/recipe/<arquivo>.json
{
  "type": "infinity_nexus_multiblock:multiblock",
  "definition": "infinity_nexus_multiblock:exemplo_recipe"
}

O tipo infinity_nexus_multiblock:multiblock e unico e registrado pelo mod. A receita so e usada pela maquina cuja definicao tem o mesmo id indicado em definition. O campo antigo recipe_type nao existe mais na definicao.

#10.2 Campos da receita

CampoObrigatorioDescricao
typesimFixo em infinity_nexus_multiblock:multiblock.
definitionsimid da definicao que processa esta receita.
inputssimLista tipada de itens, fluidos, entidades e energia consumidos.
outputssimLista tipada de resultados; cada entrada tem chance opcional.
timesimTicks de processamento; inteiro de 1 a 72000, default 100.

O codec ainda aceita os campos antigos ingredients, fluid_ingredients, output, energy e result para migracao, mas o builder exporta somente inputs e outputs. Receitas novas devem usar o schema tipado.

#10.3 inputs

Cada entrada tem um type e os campos do tipo escolhido:

"inputs": [
  { "type": "item", "ingredient": "minecraft:raw_iron", "count": 2 },
  { "type": "item", "ingredient": "#c:raw_materials/copper" },
  { "type": "fluid", "ingredient": "minecraft:water", "amount": 1000 },
  { "type": "entity", "id": "minecraft:pig", "spawn": "C" },
  { "type": "energy", "amount": 500 }
]
  • item: ingredient aceita id, tag #, JSON de ingrediente ou objeto com components; count e opcional e vai de 1 a 99.
  • fluid: ingredient aceita id ou tag; amount e obrigatorio e limitado pela maior capacidade de tanque.
  • entity: id (entity type) ou tag (tag de entity type, com #), exatamente um; spawn e opcional e aceita simbolo do pattern, bloco ou tag. A entidade precisa estar dentro da area do multibloco ou perto do seletor e e removida ao completar a receita.
  • energy: amount e o custo total em FE, consumido aos poucos durante o progresso.
  • Pelo menos um input e obrigatorio; a maquina tambem procura receitas que tenham somente energia ou entidade, sem item/fluido.

#10.4 outputs

"outputs": [
  {
    "type": "item",
    "id": "minecraft:gold_ingot",
    "count": 2,
    "components": { "minecraft:custom_name": "Ouro" },
    "chance": 0.5
  },
  { "type": "fluid", "id": "minecraft:water", "amount": 500, "chance": 1.0 },
  { "type": "entity", "id": "minecraft:pig", "spawn": "C", "chance": 0.25 },
  { "type": "energy", "amount": 1000, "chance": 1.0 }
]
  • chance e um numero de 0 a 1; default 1.0. Cada output rola separadamente no momento de completar.
  • Chance 0 nunca gera o resultado, mas os inputs ainda sao consumidos.
  • Itens usam count de 1 a 99 e podem ter components; fluidos usam amount; entidades usam id ou tag (exatamente um) e spawn opcional (sem seletor, a entidade de saída surge dentro da área do multibloco); energia vai para o storage do controller.
  • O runtime valida todos os outputs antes de iniciar o craft, mesmo os que tem chance menor que 1.

#10.5 Matching e validacao

  • Itens de input sao distribuidos por slots input com busca em profundidade; um slot so pode satisfazer uma entrada por craft.
  • Fluidos seguem a mesma regra nos tanques, respeitando capacidade e filtro.
  • Entidades de input sao procuradas no AABB do multibloco inflado em 1 bloco; com spawn baseado em simbolo/bloco/tag, a busca fica perto da key correspondente.
  • Entidades de output usam o seletor spawn quando informado; sem seletor, o controller procura um piso com dois blocos livres dentro da area do multibloco.
  • Energia de input e consumida aos poucos durante o progresso; sem energia no storage o craft pausa.
  • Antes de completar, o controller simula o consumo dos inputs de fluido e depois encaixa todos os outputs em copias do inventario e dos tanques. Se nao houver espaco para todos, o progresso fica parado.
  • Itens e fluidos gerados sao distribuidos entre os slots/tanks disponiveis; tanques usados por inputs podem ser reaproveitados para outputs depois do consumo. Energia gerada fica no storage interno do controller e pode ser extraida pelas portas de energia.

#10.6 Execucao e chance

Ao completar, os inputs sao consumidos e cada output rola sua chance de forma independente. Uma falha de chance nao devolve os inputs. Se o estado da maquina mudou e os outputs nao cabem mais, o craft nao completa e os inputs nao sao consumidos (a energia ja gasta nao volta); o planner revalida o espaco antes de cada avanco.

#10.7 Energia e tempo

Um input energy com amount: 1000 e time: 100 consome cerca de 10 FE por tick. Se a energia acabar, o progresso pausa. Um output energy e adicionado ao storage ao completar e respeita a capacidade maxima.

#10.8 Limites

  • Numero de inputs de item nao pode passar do numero de slots input.
  • Soma dos count de inputs nao pode passar da soma dos limit dos slots.
  • Cada input de item precisa caber em um unico slot, e cada input de fluido precisa caber em um unico tanque.
  • O mesmo vale para outputs e para a quantidade/capacidade dos tanques.
  • amount de energia nao pode passar da capacidade de capabilities.energy.
  • O builder bloqueia exportacao quando qualquer limite e violado; o runtime apenas nao inicia/completa o craft.

#10.9 Exemplo completo

Exemplos prontos:

  • docks/wiki/exemplos/exemplo_recipe.json
  • docks/wiki/exemplos/exemplo_recipe_iron.json

Abra o Builder de multiblocos para montar a receita visualmente e copiar o JSON validado.

#10.10 Gerar JSON com o comando

Use /inmb hand para copiar o objeto do item na mao. No builder, cole esse JSON no campo id/tag de um input ou output: o parser separa id/items, count e components. Use /inmb look para copiar o matcher do bloco olhado.

#11. Herança e templates

#11.1 Pai e filho

{
  "schema_version": 2,
  "id": "minhamod:fornalha_base",
  "template": true,
  "type": "recipe",
  "capabilities": {
    "energy": {
      "id": "energy",
      "capacity": 100000,
      "max_receive": 1000,
      "max_extract": 0
    }
  }
}
{
  "id": "minhamod:fornalha_avancada",
  "extends": "minhamod:fornalha_base",
  "tier": 2,
  "item_slots": [
    { "id": "input_0", "role": "input" },
    { "id": "output_0", "role": "output" }
  ],
  "pattern": {
    "anchor": "C",
    "layers": [
      [
        "III",
        "III",
        "III"
      ],
      [
        "III",
        "III",
        "ICI"
      ],
      [
        "III",
        "III",
        "III"
      ]
    ],
    "matchers": {
      "I": "minecraft:iron_block"
    }
  },
  "overrides": {
    "capabilities": {
      "energy": {
        "capacity": 250000,
        "max_receive": 2500
      }
    }
  }
}

O filho herda type e capabilities.energy, mas troca capacity e max_receive via overrides. As receitas da máquina usam definition: "minhamod:fornalha_avancada".

#11.2 Regras de merge

  • Objetos são mesclados recursivamente.
  • Listas substituem a lista inteira.
  • Campos do filho são aplicados antes de overrides.
  • Se o mesmo campo aparecer no filho e em overrides, overrides vence.
  • extends, family, overrides e template não são herdados.
  • O filho precisa do próprio id.
  • A receita aponta para o id final do filho em definition.
  • Ciclos, pai inexistente, extends + family juntos e overrides que não seja objeto geram erro.

#11.3 Templates

  • template: true nunca registra a máquina.
  • Um arquivo sem pattern é tratado como template quando referenciado.
  • Se um arquivo sem pattern não for referenciado, ele falha ao carregar.

#12. Priority, tier e sobreposição

#12.1 priority

Quando duas estruturas formadas disputam o mesmo bloco:

  • a maior priority vence;
  • a estrutura perdedora é desfeita;
  • em empate, vence o controller com o menor BlockPos.asLong();
  • o controller perdedor não forma a estrutura.

Para evitar surpresas, use prioridades diferentes em máquinas que podem se sobrepor.

#12.2 tier

tier é apenas metadado. Ele não altera velocidade, consumo, slots ou receitas. Use para exibir ou para outros mods que leiam a definição.

#13. Exportar e importar

#13.1 Exportar

No modo criativo:

  1. Segure shift.
  2. Clique com o botão direito em um controller.
  3. O JSON da estrutura conectada vai para o clipboard.
  4. A actionbar confirma e toca um som.

O scan:

  • começa no controller;
  • anda em seis direções;
  • ignora ar;
  • inclui o controller;
  • para no limite configurado em export.pattern_scan_limit (padrão 256; máximo 4096);
  • se houver mais, exporta até o limite e avisa na actionbar.

#13.2 O que o JSON exportado contém

{
  "schema_version": 2,
  "id": "infinity_nexus_multiblock:exported_0_64_0",
  "type": "storage",
  "pattern": {
    "layers": [],
    "anchor": "C",
    "matchers": {}
  }
}

Ele contém apenas:

  • schema_version;
  • id baseado nas coordenadas do controller;
  • type: "storage";
  • pattern com layers, anchor e matchers de bloco + state.

Ele não contém item_slots, capabilities, gui, receita ou prioridade. Use como ponto de partida para o pattern.

#13.3 Normalização

A exportação normaliza posições e states para a orientação canônica SOUTH. Se você exportou uma máquina virada para norte, o JSON ainda descreve a máquina olhando para sul. Isso permite reutilizar o pattern com qualquer FACING.

#13.4 Transformar em definição

  1. Salve o JSON em data/<namespace>/multiblock/<arquivo>.json.
  2. Troque o id para <namespace>:<arquivo>.
  3. Troque type para recipe se a máquina processar receitas.
  4. Adicione item_slots, capabilities, textures e gui conforme necessário.
  5. Crie as receitas com type: infinity_nexus_multiblock:multiblock e definition igual ao id.
  6. Rode /reload; o controller compartilhado já existe, então não é preciso reiniciar.

Não há um exemplo exportado no repositório; use o JSON do clipboard como ponto de partida.

#13.5 Limitações da exportação

  • limite configurável em export.pattern_scan_limit (padrão 256; máximo 4096);
  • flood-fill pode incluir blocos vizinhos que não fazem parte da máquina;
  • não exporta capabilities, slots, texturas, GUI, receita ou vínculo de controller;
  • o id precisa ser ajustado;
  • o type exportado é sempre storage.

#14. Reload e ciclo de vida

Use /reload no servidor.

O que acontece:

  • as definições são recarregadas e revalidadas;
  • controllers formados usam a definição mais recente do mesmo id;
  • se a definição não existir mais, a estrutura é invalidada;
  • inventário e layout da GUI são reconfigurados quando a definição muda;
  • stacks que não cabem no novo inventário são descartados;
  • capabilities de energia/fluidos já existentes não são recriadas nem reconfiguradas;
  • capabilities ausentes podem ser criadas quando a definição fica disponível;
  • as definições resolvidas são enviadas aos clientes para a preview;
  • receitas de controller são regeneradas a partir do jar do mod e de kubejs/data;
  • o layout da GUI é persistido no block entity para sobreviver ao carregamento.

Se você mudou capacity, max_receive, max_extract ou filter de uma capability existente, quebre e coloque o controller de novo, ou reinicie o mundo.

Para adicionar ou remover uma definição, basta /reload; o bloco controller é compartilhado e já está registrado.

#15. Exemplos completos

Os arquivos ficam em exemplos/.

Arquivo O que mostra
exemplo_storage.json type=storage, item slots com filtros/limites/faces, energia, fluido e GUI customizada com slots via x/y.
exemplo_recipe.json type=recipe, dois inputs, um output, energia, fluido e GUI padrão com barra de progresso.
exemplo_recipe_iron.json Receita com tipo infinity_nexus_multiblock:multiblock, definition apontando para o exemplo e ingredientes de item/fluido.

#15.1 Como testar

  1. Copie os arquivos para um datapack:
data/infinity_nexus_multiblock/multiblock/exemplo_storage.json
data/infinity_nexus_multiblock/multiblock/exemplo_recipe.json
data/infinity_nexus_multiblock/recipe/exemplo_recipe_iron.json
  1. Os id já batem com os nomes dos arquivos.
  2. Coloque o datapack em world/datapacks.
  3. Rode /reload.
  4. Obtenha o controller com /inmb give infinity_nexus_multiblock:exemplo_recipe ou /inmb give infinity_nexus_multiblock:exemplo_storage.

O controller é compartilhado. Os exemplos não precisam declarar controller, recipe_type nem texturas. A receita de crafting do controller só é gerada automaticamente quando a definição está no jar do mod ou em kubejs/data; em um datapack comum, use /inmb give.

#15.2 Sobrescrever uma definição existente

Use o mesmo caminho e o mesmo id da definição original:

data/infinity_nexus_multiblock/multiblock/<arquivo>.json

Depois rode /reload. O controller já existe, então não é preciso reiniciar o jogo. Se a definição estiver em um datapack e você quiser gerar a receita de crafting do controller, mova o JSON para kubejs/data ou para o jar do mod.

#15.3 Receita shaped do controller

Para que uma definição gere uma receita de crafting do controller, adicione o campo top-level recipe:

{
  "schema_version": 2,
  "id": "minhamod:minha_maquina",
  "type": "recipe",
  "recipe": {
    "pattern": ["ICI", "CGC", "ICI"],
    "key": {
      "I": "minecraft:iron_ingot",
      "C": "minecraft:copper_ingot",
      "G": "minecraft:glass"
    }
  },
  "pattern": {
    "anchor": "C",
    "layers": [["III", "III", "III"], ["III", "III", "ICI"], ["III", "III", "III"]],
    "matchers": {
      "I": "minecraft:iron_block"
    }
  }
}

A receita gerada produz o controller com o componente infinity_nexus_multiblock:multiblock_definition igual a minhamod:minha_maquina. Veja a seção 9.4 para o formato completo.

#16. Erros comuns

Mensagem / sintoma Causa Correção
Definition id ... does not match file id id diferente do caminho. Use <namespace>:<arquivo>.
Unsupported schema_version Versão diferente de 2. Use "schema_version": 2.
Unknown multiblock type type inválido. Use recipe ou storage.
Unknown parent multiblock extends/family aponta para ID inexistente. Confira o ID e o caminho do pai.
Circular extends involving Herança em ciclo. Remova o ciclo.
Use either extends or family, not both Os dois campos juntos. Use só um.
overrides must be an object overrides não é objeto. Use { ... }.
template must be a boolean template não é booleano. Use true ou false.
Unknown block ID de bloco inexistente. Confira o registro.
Unknown block state property Propriedade não existe no bloco. Confira o blockstate do bloco.
Invalid value ... for block state property Valor inválido para a propriedade. Use um valor válido.
No matcher registered for pattern symbol Símbolo sem matcher. Adicione o matcher.
needs exactly one anchor Nenhuma ou mais de uma âncora. Deixe exatamente um C.
same number of rows Camadas com quantidades diferentes de linhas. Alinhe as camadas.
same width Linhas com larguras diferentes. Alinhe as larguras.
Duplicate item slot id IDs de slot repetidos. Use IDs únicos.
Item slot id cannot be blank id vazio. Use um ID não vazio.
Item slot ... must define both x and y Só um dos dois. Informe os dois ou nenhum.
Slot position cannot be negative x/y negativo. Use valores >= 0.
Capability port symbol 'X' is not used by the pattern Símbolo de capability_ports não existe no pattern. Use um símbolo presente ou ajuste o pattern.
Unknown item ID de item no filtro inexistente. Confira o registro.
Duplicate fluid tank id Tanques com mesmo ID. Use IDs únicos.
Energy capability id conflicts with a fluid tank id energy.id igual a um tanque. Troque um dos IDs.
Unknown fluid ID de fluido no filtro inexistente. Confira o registro.
Custom gui elements with slot entries require item_slots gui.elements sem item_slots. Adicione item_slots.
Define slot positions in item_slots x/y or gui slot elements, not both Misturou os dois formatos. Escolha um.
Unknown item slot id in gui Elemento slot aponta para ID inexistente. Confira o ID.
Duplicate slot element for item slot Slot repetido em elementos. Use uma vez.
Custom gui elements require a player_inventory element Falta player_inventory. Adicione exatamente um.
gui has an energy_bar but the multiblock has no energy capability Barra sem energia. Adicione capabilities.energy ou remova a barra.
Unknown energy capability in gui capability diferente de energy.id. Corrija o ID.
Unknown fluid tank id in gui capability de tanque inexistente. Corrija o ID.
gui has a progress_bar/arrow but the multiblock is not a recipe multiblock Barra/seta em storage. Use type=recipe.
gui has an entity element but the multiblock is not a recipe multiblock entity em storage. Use type=recipe.
exceeds gui bounds Elemento fora da GUI. Aumente width/height ou mova.
Receita não carrega Caminho, type ou IDs errados. Confira data/<namespace>/recipe, type e ingredientes.
Receita não aparece na máquina definition diferente do id da definição. Use exatamente o mesmo identifier.
Definição não carrega Caminho/ID/schema errados. Confira o log do servidor.
Controller não pode ser colocado Item sem o componente infinity_nexus_multiblock:multiblock_definition. Use /inmb give <definition> ou a aba criativa.

O log fica em logs/latest.log.

Se o controller não puder ser colocado, confira se o item tem o componente de definição. Use /inmb give <definition> para obter a variante correta.

#17. Checklist final

Antes de testar, confirme:

  • O JSON está em data/<namespace>/multiblock/<arquivo>.json.
  • id é <namespace>:<arquivo>.
  • schema_version é 2.
  • type é recipe ou storage.
  • O pattern tem exatamente uma âncora.
  • Todas as camadas têm o mesmo número de linhas.
  • Todas as linhas têm a mesma largura.
  • Todo símbolo não-âncora tem matcher.
  • A receita de máquina usa type: infinity_nexus_multiblock:multiblock.
  • O campo definition da receita é igual ao id da definição.
  • O controller é obtido por /inmb give <definition> ou pela aba criativa.
  • item_slots tem IDs únicos e filtros válidos.
  • x/y aparecem juntos.
  • capabilities tem IDs únicos e energy.id diferente dos tanques.
  • Se usar capability_ports, os símbolos existem no pattern e cada capability lista as portas desejadas.
  • A GUI tem exatamente um player_inventory.
  • Barras de energia/fluido apontam para IDs existentes.
  • progress_bar/arrow/entity só existem em recipe.
  • A receita está em data/<namespace>/recipe/<arquivo>.json.
  • A receita tem pelo menos um ingrediente.
  • A máquina tem slot output para saída de item, tanque para saída de fluido e spawn válido para entidade quando o seletor for informado.
  • Se a receita usa energia/fluido, a máquina tem as capabilities.
  • Você rodou /reload e conferiu logs/latest.log.

#18. Limitações atuais

#18.1 Controller único

  • Existe um único bloco/item controller: infinity_nexus_multiblock:multiblock_controller.
  • O vínculo com a máquina vem do componente infinity_nexus_multiblock:multiblock_definition; não há bloco ou item por definição, mas o modelo do controller pode ser especializado com textures.
  • A aba criativa mostra uma variante do controller para cada definição carregada.
  • /reload atualiza definições e receitas; não é necessário reiniciar para adicionar, remover ou sobrescrever uma definição.
  • O antigo bloco nexus_core e os controllers dinâmicos foram removidos. Mundos antigos podem gerar avisos de registry; faça backup antes de atualizar.

#18.2 Máquinas, receitas e automação

  • Toda receita de máquina usa type: infinity_nexus_multiblock:multiblock e definition: <id>. Não há tipo independente por máquina.
  • type=storage já funciona como inventário/capabilities/GUI, mas não tem comportamento especializado de armazenamento dedicado. tier é apenas metadado.
  • Receitas produzem uma única saída item, fluid ou entity; não há energia como saída, subproduto, múltiplas saídas simultâneas ou chance.
  • Não há prioridade entre receitas; a primeira receita compatível encontrada é usada.
  • Energia e fluidos não têm configuração por lado; as capabilities do controller e dos membros selecionados aceitam todas as faces. capability_ports escolhe blocos, não faces.
  • As faces de item_slots são direções do mundo e não giram com o controller/estrutura.
  • Matchers aceitam bloco, tag e state; não aceitam NBT, listas de alternativas ou matchers opcionais.

#18.3 Assets, JEI e reload

  • O controller compartilhado tem blockstate, modelo base, loot e traduções próprios; texturas por definição vêm de textures e são aplicadas em runtime.
  • O nome exibido usa multiblock.<namespace>.<path> e cai no path formatado quando não há tradução.
  • A categoria JEI de receitas é filtrada pela definição do controller.
  • A categoria JEI de estruturas ainda usa um catalisador genérico e pode listar todas as estruturas; o filtro por definição é uma melhoria pendente.
  • A transferência JEI de itens existe, mas ainda não foi validada visualmente no cliente; fluidos continuam manuais.
  • /reload recarrega definições, receitas de controller e o pack de dados; não recria capabilities já existentes.

#18.4 Exportação

  • A exportação é limitada por export.pattern_scan_limit na config comum do mod (config/infinity_nexus_multiblock-common.toml): padrão 256, máximo 4096.
  • O JSON exportado contém apenas schema_version, id, type e pattern (blocos e states); não inclui item_slots, capabilities, textures, gui, receita ou prioridade, e o type exportado é sempre storage.

#18.5 Metas ainda não atendidas

  • Comportamento especializado de type=storage além do básico já implementado (inventário, capabilities e GUI): regras dedicadas de armazenamento de item, fluido e energia.
  • Entidades como entrada de receitas dentro da área do multibloco; itens, fluidos e energia já são aceitos.
  • Saída de energia em receitas; fluidos e entidades já são suportados.
  • Filtro da categoria JEI de estruturas por definição e validação visual da transferência JEI.
  • Adaptadores para receitas vanilla.