Voltar para o Blog
Quest Log

Sistema de Crafting na Godot 4 com GDScript do Zero

Bancada de trabalho de artesão com ferramentas, minério e uma poção sendo montada a partir de ingredientes

Como montar um sistema de crafting funcional na Godot 4 com GDScript tipado: item e receita como Resource, inventário, função craft() e UI ligada por sinal.

Ferramenta:Godot

Fabricar itens a partir de ingredientes é uma daquelas mecânicas que parecem simples de fora e viram bagunça quando você senta pra escrever. Poção de vida = 2 ervas + 1 frasco. Espada = 3 lingotes + 1 cabo. Fácil no papel, mas se você chumbar isso direto no código, cada receita nova vira um if gigante e um mês depois ninguém entende mais nada. Este tutorial mostra como montar um sistema de crafting na Godot 4 com GDScript de um jeito que escala: dados separados da lógica, receitas editáveis fora do código e uma UI que conversa por sinal. Todo o código aqui é tipado e roda no Godot 4 real, sem API inventada.

A ideia central é uma só: item e receita são dados, não comportamento. Quem sabe fabricar é uma classe de lógica. Quem mostra os botões é a UI. Cada peça ignora as outras o máximo possível. Vamos por partes.

Modelando o item como Resource

Resource é a classe base da Godot pra dado reutilizável e salvável em arquivo. Você define os campos, dá um class_name, e cada instância vira um arquivo .tres que dá pra editar no Inspector sem abrir o editor de código. É o oposto de espalhar strings mágicas pelos scripts.

Comece pelo item. Crie um script item.gd:

class_name Item
extends Resource

@export var id: String = ""
@export var nome: String = ""
@export var icone: Texture2D
@export_multiline var descricao: String = ""

Salve, e no editor use New Resource -> Item pra criar erva.tres, frasco.tres, pocao_vida.tres e por aí vai. O id é o que importa pra lógica (uma string curta e estável tipo "erva"); o resto é pra mostrar na tela. Manter um id explícito em vez de depender do nome do arquivo evita dor de cabeça quando você renomeia coisas depois.

Modelando a receita

A receita é onde a mágica acontece. Ela precisa de duas coisas: quais ingredientes consome e o que produz. Ingredientes são um mapa de item pra quantidade, então um Dictionary resolve. O resultado é um item mais uma quantidade (algumas receitas rendem mais de uma unidade).

class_name Receita
extends Resource

@export var resultado: Item
@export var quantidade_resultado: int = 1
@export var ingredientes: Dictionary = {}

O ingredientes guarda pares de Item para int. No Inspector você adiciona as chaves arrastando os .tres dos itens e digita a quantidade de cada um. Uma receita de poção fica com { erva.tres: 2, frasco.tres: 1 } e resultado = pocao_vida.tres, quantidade_resultado = 1.

Um detalhe prático: dá pra usar o Item inteiro como chave do dicionário, e funciona, porque cada .tres carregado é uma referência única. Mas se você for salvar o inventário em disco depois, é mais seguro indexar tudo pelo id (a String). Vou usar id como chave no inventário justamente por isso, e converter na hora de checar a receita. Fica explícito e não quebra na hora de serializar.

O inventário

O inventário mais simples que resolve é um dicionário de id do item para quantidade. Nada de lista de objetos, nada de slots ainda: só "quanto de cada coisa eu tenho". Um script inventario.gd que estende Node (pra virar um nó na cena ou um autoload):

class_name Inventario
extends Node

signal inventario_mudou

var itens: Dictionary = {}

func adicionar(id: String, quantidade: int = 1) -> void:
    if quantidade <= 0:
        return
    itens[id] = itens.get(id, 0) + quantidade
    inventario_mudou.emit()

func remover(id: String, quantidade: int = 1) -> bool:
    var atual: int = itens.get(id, 0)
    if atual < quantidade:
        return false
    itens[id] = atual - quantidade
    if itens[id] <= 0:
        itens.erase(id)
    inventario_mudou.emit()
    return true

func tem(id: String, quantidade: int = 1) -> bool:
    return itens.get(id, 0) >= quantidade

Repare no uso de get(id, 0): se o item nunca entrou no dicionário, tratamos como zero em vez de dar erro. O remover retorna bool porque ele pode falhar (não dá pra tirar 3 ervas de quem tem 1), e quem chama precisa saber disso. E o sinal inventario_mudou avisa a UI que a quantidade mudou, sem o inventário saber nada sobre telas. Esse mesmo padrão de dicionário guia jogos com drag and drop de inventário na Godot, onde os slots visuais leem dessa mesma fonte de dados.

A função que checa os ingredientes

Antes de fabricar, a pergunta é: dá pra fabricar? Isso é uma função separada, e vale que seja separada, porque a UI também vai usar ela pra decidir se o botão fica ativo ou cinza. Ela percorre os ingredientes da receita e confere cada um contra o inventário.

func pode_fabricar(receita: Receita) -> bool:
    if receita == null or receita.resultado == null:
        return false
    for ingrediente in receita.ingredientes:
        var id: String = ingrediente.id
        var necessario: int = receita.ingredientes[ingrediente]
        if not inventario.tem(id, necessario):
            return false
    return true

A validação de null no começo não é frescura: uma receita mal configurada no Inspector (sem resultado, por exemplo) chegaria aqui e explodiria mais na frente, num ponto bem mais difícil de debugar. Barrar cedo é mais barato. O laço sai no primeiro ingrediente que falta com return false; só chega no return true quem passou por todos.

A função craft()

Agora o núcleo. craft() faz três coisas nesta ordem: valida, consome os ingredientes, adiciona o resultado. A ordem importa. Se você adicionar o resultado antes de consumir e algo falhar no meio, o jogador ganha item de graça. Validar tudo primeiro garante que ou a fabricação inteira acontece, ou nada acontece.

signal item_fabricado(resultado: Item, quantidade: int)

func craft(receita: Receita) -> bool:
    if not pode_fabricar(receita):
        return false

    for ingrediente in receita.ingredientes:
        var id: String = ingrediente.id
        var necessario: int = receita.ingredientes[ingrediente]
        inventario.remover(id, necessario)

    inventario.adicionar(receita.resultado.id, receita.quantidade_resultado)
    item_fabricado.emit(receita.resultado, receita.quantidade_resultado)
    return true

Como pode_fabricar já garantiu que tem tudo, o laço de remover nunca vai falhar aqui, e por isso não precisa checar o retorno. Depois de consumir, adiciona o resultado e emite item_fabricado. Esse sinal é o que liga a lógica ao resto do jogo: a UI escuta pra mostrar feedback, um sistema de conquistas pode escutar pra contar "fabricou 10 poções", e nenhum deles precisa conhecer o outro. craft() devolve bool pra quem chamou saber se deu certo.

Um CraftingSystem completo junta tudo:

class_name CraftingSystem
extends Node

signal item_fabricado(resultado: Item, quantidade: int)

@export var inventario: Inventario
@export var receitas: Array[Receita] = []

func pode_fabricar(receita: Receita) -> bool:
    if receita == null or receita.resultado == null:
        return false
    for ingrediente in receita.ingredientes:
        if not inventario.tem(ingrediente.id, receita.ingredientes[ingrediente]):
            return false
    return true

func craft(receita: Receita) -> bool:
    if not pode_fabricar(receita):
        return false
    for ingrediente in receita.ingredientes:
        inventario.remover(ingrediente.id, receita.ingredientes[ingrediente])
    inventario.adicionar(receita.resultado.id, receita.quantidade_resultado)
    item_fabricado.emit(receita.resultado, receita.quantidade_resultado)
    return true

O receitas é um Array[Receita] exportado: você arrasta os .tres das receitas pro Inspector e a lista de crafting do jogo está definida sem uma linha de código. Adicionar receita nova é criar arquivo e soltar na lista.

Curso de Godot
Quer fazer seu primeiro jogo na Godot?

No curso de Godot da CursoGame.Dev você vai do zero ao primeiro jogo, com um desafio prático em cada level e suporte individual no WhatsApp quando travar.

Conhecer o curso de Godot
Suporte no WhatsAppAcesso vitalícioGarantia de 7 dias

Ligando na UI de crafting

A UI não fabrica nada. Ela pergunta ao CraftingSystem o que dá pra fazer, mostra os botões e, quando o jogador clica, chama craft(). Todo o resultado volta pelo sinal. Monte uma cena com um VBoxContainer chamado ListaReceitas e um script:

extends Control

@export var crafting: CraftingSystem
@onready var lista: VBoxContainer = $ListaReceitas

func _ready() -> void:
    crafting.item_fabricado.connect(_ao_fabricar)
    crafting.inventario.inventario_mudou.connect(_atualizar_botoes)
    _montar_lista()

func _montar_lista() -> void:
    for receita in crafting.receitas:
        var botao: Button = Button.new()
        botao.text = receita.resultado.nome
        botao.pressed.connect(_ao_clicar.bind(receita))
        lista.add_child(botao)
    _atualizar_botoes()

func _ao_clicar(receita: Receita) -> void:
    crafting.craft(receita)

func _atualizar_botoes() -> void:
    var indice: int = 0
    for receita in crafting.receitas:
        var botao: Button = lista.get_child(indice) as Button
        botao.disabled = not crafting.pode_fabricar(receita)
        indice += 1

func _ao_fabricar(resultado: Item, quantidade: int) -> void:
    print("Fabricou %d x %s" % [quantidade, resultado.nome])

O bind(receita) amarra a receita específica ao clique daquele botão, então cada botão sabe o que fabrica sem você guardar índices soltos. O _atualizar_botoes roda no _ready e toda vez que o inventário muda: botão de receita sem ingredientes fica desabilitado sozinho. E quando craft dá certo, o sinal item_fabricado cai em _ao_fabricar, que aqui só imprime, mas é onde você toca som, mostra popup ou anima o item novo. Esse mesmo desenho de sinal e botão aparece em qualquer tela transacional, como no sistema de loja e shop de um jogo, que compra e vende com a mesma estrutura de validar, consumir e emitir.

Carregando centenas de receitas de uma pasta

Arrastar .tres um por um no Inspector resolve pra cinco ou dez receitas. Num jogo com dezenas ou centenas, isso vira trabalho manual e fácil de esquecer. A saída é carregar todas de uma pasta automaticamente e indexar por id, do jeito que o FAQ adianta. Guarde todos os .tres de receita numa pasta tipo res://receitas/ e deixe o sistema varrer:

func carregar_receitas(pasta: String) -> Array[Receita]:
    var lista: Array[Receita] = []
    var dir: DirAccess = DirAccess.open(pasta)
    if dir == null:
        push_error("Pasta de receitas nao encontrada: %s" % pasta)
        return lista
    dir.list_dir_begin()
    var arquivo: String = dir.get_next()
    while arquivo != "":
        if arquivo.ends_with(".tres"):
            var recurso: Resource = ResourceLoader.load(pasta.path_join(arquivo))
            if recurso is Receita:
                lista.append(recurso)
        arquivo = dir.get_next()
    dir.list_dir_end()
    return lista

Dois cuidados valem ouro aqui. O if recurso is Receita garante que um .tres solto de outro tipo (um Item, por exemplo) não entre na lista de receitas por engano. E o path_join monta o caminho sem você concatenar String na mão, o que evita o clássico erro de barra a mais ou a menos entre a pasta e o nome do arquivo. Chame isso no _ready do CraftingSystem e o Array[Receita] receitas se popula sozinho:

func _ready() -> void:
    receitas = carregar_receitas("res://receitas/")

A partir daqui, adicionar receita ao jogo é soltar um arquivo na pasta. Nada de código, nada de Inspector. Para busca rápida por id, monte também um Dictionary que mapeia id para Receita logo depois de carregar, e você acessa qualquer receita em tempo constante sem varrer a lista inteira.

Mostrando quanto falta pra fabricar

Desabilitar o botão quando falta ingrediente já ajuda, mas o jogador fica no escuro sobre o que exatamente está faltando. Uma função que devolve a lista do que falta transforma um botão cinza mudo numa dica útil na tela. Ela percorre os ingredientes e, pra cada um que o inventário não cobre, registra o id e quanto falta.

func ingredientes_faltando(receita: Receita) -> Dictionary:
    var faltando: Dictionary = {}
    if receita == null:
        return faltando
    for ingrediente in receita.ingredientes:
        var necessario: int = receita.ingredientes[ingrediente]
        var tem: int = inventario.itens.get(ingrediente.id, 0)
        if tem < necessario:
            faltando[ingrediente.id] = necessario - tem
    return faltando

O retorno é um Dictionary de id pra quantidade que falta, vazio quando dá pra fabricar. Na UI você usa isso no tooltip_text do botão ou numa label embaixo da receita: "Falta 1 erva". O jogador entende na hora por que não consegue craftar, em vez de olhar um botão apagado sem explicação. Repare que a função não consome nada e não emite sinal, ela só lê, então pode ser chamada à vontade pra montar tooltip sem risco de efeito colateral.

Salvando e carregando o inventário em disco

O sistema todo roda em memória, e isso basta até o jogador fechar o jogo. Como o inventário é um Dictionary de String pra int, salvar ele é direto, e é justamente por isso que indexamos tudo por id desde o começo em vez de usar o Item como chave. O formato mais simples e legível é JSON.

const CAMINHO_SAVE: String = "user://inventario.json"

func salvar_inventario() -> void:
    var arquivo: FileAccess = FileAccess.open(CAMINHO_SAVE, FileAccess.WRITE)
    if arquivo == null:
        push_error("Nao foi possivel abrir o save para escrita")
        return
    arquivo.store_string(JSON.stringify(inventario.itens))
    arquivo.close()

func carregar_inventario() -> void:
    if not FileAccess.file_exists(CAMINHO_SAVE):
        return
    var arquivo: FileAccess = FileAccess.open(CAMINHO_SAVE, FileAccess.READ)
    var texto: String = arquivo.get_as_text()
    arquivo.close()
    var dados: Variant = JSON.parse_string(texto)
    if dados is Dictionary:
        var limpo: Dictionary = {}
        for id in dados:
            limpo[id] = int(dados[id])
        inventario.itens = limpo
        inventario.inventario_mudou.emit()

Dois cuidados evitam a dor de cabeça clássica aqui. O JSON.parse_string sempre devolve número como float, então o int(dados[id]) reconverte cada quantidade pra inteiro, senão você acaba com 3.0 ervas e comparações estranhas depois. E o inventario_mudou.emit() no fim do carregamento faz a UI se redesenhar sozinha com os dados restaurados, usando o mesmo sinal que o resto do sistema já escuta. Repare que você salva só o dicionário de quantidades, nunca os Resource: as receitas e os itens continuam vindo dos .tres, e o save guarda apenas quanto de cada id o jogador tem. Se o seu jogo precisa persistir muito mais que o inventário, o sistema de save e load no Godot mostra como organizar isso sem virar uma bagunça de arquivos soltos.

Boas práticas que fazem a diferença

Três coisas separam esse sistema de um que apodrece em três meses.

Dado é dado, lógica é lógica. Item e receita são Resource, sem uma linha de comportamento dentro. Quem sabe fabricar é o CraftingSystem. Esse corte é o que deixa um designer sem programar criar cem receitas em .tres enquanto você mexe no código do jogo. Se você começar a colocar func craft() dentro da classe Item, parabéns, acabou de acoplar dado e lógica e vai se arrepender.

Sinais no lugar de o sistema chamar a UI. O CraftingSystem nunca faz ui.mostrar_mensagem(). Ele emite item_fabricado e segue a vida. Quem quiser reagir se conecta. Isso deixa você trocar a UI inteira, adicionar som, adicionar conquista, tudo sem tocar na lógica de fabricação. É o mesmo princípio de desacoplamento que vale pra efeitos de status como buff e debuff: o sistema aplica o efeito e avisa, quem escuta que reaja.

Escalabilidade vem da arquitetura, não de otimização prematura. Com receitas em Resource, ir de 5 pra 200 receitas não muda o código de craft(), só a quantidade de arquivos. Se um dia forem centenas, você carrega todas de uma pasta com um loop no ResourceLoader e indexa por id num dicionário, mas o núcleo continua igual. Não tente resolver o problema das 200 receitas quando você tem 5; resolva a arquitetura, e as 200 chegam de graça.

Uma escolha que atravessa tudo isso é a linguagem. GDScript, como usei aqui, é direto e integra sem atrito com os Resource e sinais da engine. Pra sistemas muito pesados de CPU tem quem prefira C#, e se essa dúvida te pega, vale ler o comparativo de C# contra GDScript na Godot antes de decidir. Pra 95% dos jogos com crafting, GDScript dá conta sobrando.

Erros comuns que quebram o crafting

Alguns tropeços aparecem sempre quando alguém monta esse sistema pela primeira vez. Dá pra evitar todos.

Adicionar o resultado antes de consumir os ingredientes. É o erro mais caro. Se a ordem no craft() for "adiciona resultado, depois remove ingredientes" e algo falhar no meio, o jogador ganha item de graça. Valide tudo primeiro, consuma depois, adicione por último. A operação tem que ser atômica: ou acontece inteira, ou não acontece.

Usar o Item como chave e tentar salvar o inventário. Funciona em memória porque cada .tres é uma referência única, mas na hora de serializar pro disco vira dor de cabeça. Indexe o inventário por id (String) desde o começo, como fizemos aqui, e você não precisa reescrever nada quando for implementar o save.

Esquecer de checar null na receita. Uma receita arrastada no Inspector sem resultado definido chega no craft() e explode num ponto difícil de rastrear. O if receita == null or receita.resultado == null no topo do pode_fabricar barra isso cedo, onde o erro é óbvio.

Fazer a UI consultar o inventário direto em vez de ouvir o sinal. Se a tela varre o dicionário toda frame pra atualizar botão, você acopla UI e dados e ainda gasta CPU à toa. Conecte no inventario_mudou e no item_fabricado e deixe a UI reagir só quando algo muda de verdade.

Colocar lógica dentro da classe Item. No momento em que você escreve func craft() dentro do Item, dado e comportamento viram a mesma coisa e a arquitetura começa a apodrecer. Item é dado puro; quem fabrica é o CraftingSystem.

Se quiser se aprofundar na engine antes de estender esse sistema, as ferramentas e guias de Godot do CursoGame.Dev reúnem o que você precisa pra ir de um crafting básico a um sistema completo de RPG.

Fechando

Você tem um sistema de crafting completo: Item e Receita como Resource editáveis fora do código, um Inventario que é só um dicionário com sinal, pode_fabricar pra validar, craft pra executar de forma atômica e uma UI que se liga por sinal e não conhece as tripas da lógica. Daqui dá pra crescer em qualquer direção: adicionar tempo de fabricação, exigir uma bancada por perto, dar chance de falha, categorizar receitas. Todas essas extensões cabem sem reescrever o núcleo, justamente porque os dados estão separados da lógica desde o começo. Comece pequeno, com duas ou três receitas rodando de ponta a ponta, e só depois adicione tempero. Aqui no CursoGame.Dev a gente insiste nisso: sistema que escala é sistema que nasceu organizado, não o que ficou esperto demais cedo demais.

Perguntas frequentes

Por que modelar item e receita como Resource em vez de dicionário puro?

Resource dá arquivos .tres editáveis no Inspector, reuso entre cenas e tipagem forte com class_name. Você cria uma receita nova sem tocar em código, só duplicando um arquivo e trocando os campos. Dicionário solto no script vira uma pilha de strings mágicas que ninguém consegue manter depois de vinte itens.

Como valido se o jogador tem os ingredientes antes de fabricar?

Percorra o dicionário de ingredientes da receita e compare cada quantidade com o que o inventário tem. Se qualquer item faltar ou tiver quantidade insuficiente, retorne false imediatamente. Só depois de passar por todos os ingredientes é que a fabricação pode consumir e adicionar o resultado.

Preciso de banco de dados para o crafting funcionar?

Não para começar. Um dicionário de itens em memória mais os arquivos .tres das receitas resolvem um jogo pequeno ou médio inteiro. Banco de dados só entra se você tem inventário persistente entre sessões, e aí o que você salva é o dicionário de quantidades, não os Resources.

Como a UI sabe que um item foi fabricado?

A lógica emite um sinal quando o craft dá certo, tipo item_fabricado(resultado, quantidade). A UI conecta nesse sinal e reage: mostra a mensagem, atualiza a lista, toca um som. Assim a lógica não conhece a interface e você troca a UI sem mexer no sistema de crafting.

Esse sistema serve para jogo grande com centenas de receitas?

Serve como base. Com item e receita em Resource, adicionar receita é criar arquivo, não editar código. Para centenas delas vale carregar tudo de uma pasta com um loop no ResourceLoader e indexar por id, mas a arquitetura de dados separados da lógica continua a mesma.