Na lição anterior, você aprendeu como o Python pode controlar entidades durante o gameplay. Mas o Python no Cave não está limitado ao jogo em execução. Você também pode usá-lo para criar Editor Tools que ajudam a construir seu jogo mais rápido.

Isso é especialmente útil porque muitos projetos têm tarefas repetitivas. Talvez você frequentemente coloque inimigos, crie checkpoints, organize pastas, teste valores ou inspecione dados da cena. Em vez de fazer tudo manualmente toda vez, você pode criar pequenas ferramentas que automatizam partes do seu fluxo de trabalho. Você pode até criar editores mais avançados para permitir níveis gerados proceduralmente, construções procedurais e muito mais.

Nesta lição, você vai aprender:

A diferença entre scripts de gameplay e scripts de editor.
Para que uma ferramenta de editor pode ser usada.
Como uma ferramenta de aba do editor é estruturada.
Por que o #editoronly é importante.
Quando vale a pena criar uma ferramenta customizada.

Você não precisa construir ferramentas imediatamente ao começar, mas é bom saber que esse sistema existe. É uma daquelas funcionalidades que se tornam mais valiosas à medida que seu projeto cresce.

Scripts de Gameplay vs Ferramentas de Editor

Resumindo:

Scripts de Gameplay rodam enquanto o jogo está em execução.
Editor Tools rodam dentro do editor para ajudar você a trabalhar no projeto.

Tipo de Script	Roda em	Exemplo
Script de Gameplay	Modo Play e Jogo Exportado.	Movimento do jogador, IA inimiga, portas, pickups.
Editor Tool	Cave Editor.	Auxiliar de nível, rename em lote, inspetor de cena, geração procedural de construções, ferramenta de posicionamento.

Por exemplo, um script para abrir uma porta é lógica de gameplay porque o jogador deve vivenciar isso enquanto joga. Uma ferramenta que posiciona dez tochas ao longo de um corredor é lógica de editor porque ajuda a construir o nível, mas não precisa existir no jogo exportado.

Por que Editor Tools São Úteis

No começo, ferramentas customizadas podem parecer algo apenas para equipes grandes.

Mas até desenvolvedores solo podem se beneficiar de pequenas ferramentas porque elas reduzem trabalho manual repetitivo. Se você faz a mesma tarefa muitas vezes, um script simples de editor pode fazer o projeto parecer muito mais rápido para trabalhar.

Editor tools podem ajudar com coisas como:

Posicionar grupos de entidades.
Verificar se componentes necessários estão faltando.
Criar configurações comuns de cena.
Imprimir informações de debug.
Testar valores sem entrar no Modo Play.
Ajudar designers a ajustar dados de gameplay.

Por exemplo, imagine que você está construindo um jogo em terceira pessoa com muitos acampamentos inimigos. Em vez de criar manualmente a mesma estrutura de pastas toda vez, você poderia criar uma ferramenta que adiciona um Enemy Group, alguns pontos de spawn e uma área de gatilho automaticamente.

Scripts Apenas para Editor

Scripts de editor normalmente começam com esta linha:

#editoronly

Isso diz ao Cave que o script é destinado ao uso no editor.

Isso importa porque ferramentas de editor podem usar APIs ou comportamentos que só fazem sentido no editor. Normalmente você não quer que um auxiliar de design de nível ou painel de debug faça parte do jogo final.

Isso também é importante para dizer ao Cave quais scripts executar na inicialização do jogo e quais ignorar. Por padrão, ele roda todos os scripts, então se você quer que um seja ignorado, ele deve incluir esse comentário na primeira linha.

Portanto, se você está criando um script que existe apenas para ajudar a trabalhar dentro do Cave Editor, torne-o editor-only.

Ferramentas de Aba do Editor

Uma maneira comum de criar uma ferramenta é com uma Editor Tab.

Uma aba do editor é um painel customizado que aparece dentro do Cave Editor. Ela tem um método draw(), e o Cave chama esse método enquanto a aba está visível para que a ferramenta possa desenhar botões, texto, propriedades e outros controles.

Uma aba muito pequena de editor fica assim:

#editoronly
import cave

class ExampleTab(cave.ui.DebugTab):
    def __init__(self):
        super().__init__()
        self.counter = 0

    def draw(self):
        cave.ui.text("Esta é uma ferramenta de exemplo.")
        cave.ui.separator()

        self.counter = cave.ui.prop("Contador", self.counter)

        if cave.ui.buttonDark("Aumentar contador +1"):
            self.counter += 1
            print("Contador aumentado em +1")

Este é também o código padrão ao adicionar uma aba do editor. Se você clicar para abri-la na aba de propriedades e depois for para a aba de ferramentas do editor, verá a classe da aba de exemplo aparecendo como uma aba de debug. Então tudo que você precisa fazer é registrar ou recarregar a aba e ela estará disponível na interface:

Este exemplo é simples, mas já mostra a ideia básica:

cave.ui.DebugTab cria uma aba customizada no editor.
draw() define o que a aba mostra.
cave.ui.text() desenha texto.
cave.ui.prop() desenha uma propriedade editável.
cave.ui.buttonDark() cria um botão.
print() pode ser usado para enviar informações para o console.

É assim que é simples criar ferramentas customizadas para o Cave Editor. Você pode usar essa mesma estrutura para construir ferramentas reais depois.

O Que Significa o Método `draw()`

O método draw() não é como o start() em um componente de gameplay.

Ele é chamado repetidamente enquanto a ferramenta está visível, pois a UI do editor precisa ser desenhada e atualizada. Isso significa que o código dentro de draw() deve descrever a interface atual da ferramenta.

Por exemplo:

def draw(self):
    cave.ui.text("Auxiliar de Nível:")

    if cave.ui.buttonDark("Criar Grupo de Inimigos"):
        print("Clique para criar grupo de inimigos")

O botão é desenhado toda vez que a aba atualiza, mas o código dentro do if só roda quando o usuário clica no botão.

Esse padrão é muito comum em ferramentas de editor.

Uma Ideia Prática de Ferramenta

Imagine que você está construindo um nível e frequentemente precisa das mesmas pastas básicas:

Environment
Enemies
Gameplay Triggers
Lighting
Audio
Debug Helpers

Você poderia criar uma ferramenta de editor com um botão chamado Create Level Folders. Quando clicado, ele criaria essas entidades de pasta na cena atual. Lembre-se: uma Pasta no Scene Graph é apenas uma Entity sem componentes anexados.

Pode parecer algo pequeno, mas ferramentas assim tornam projetos grandes mais fáceis de manter organizados. Também ajudam a seguir suas próprias convenções de projeto sem precisar lembrar cada passo manualmente.

Componentes de Editor

Às vezes, você quer misturar lógica de gameplay com lógica de editor. Por exemplo, pode querer um componente anexado a uma entidade que também execute lógica do editor, como mostrar uma informação de debug ou uma esfera indicativa da área de movimento ou ataque de um inimigo. Nesse caso, em vez de usar cave.Component, você usa cave.EditorComponent.

Isso é útil quando uma entidade precisa de um comportamento especial no editor, mas esse comportamento não deve fazer parte do jogo final.

Por exemplo:

Um ponto de spawn pode mostrar informações auxiliares no editor.
Um volume de gatilho pode expor controles de debug.
Um marcador de nível pode validar se está configurado corretamente.

A ideia importante é que scripts de editor são para o fluxo de trabalho ao fazer o jogo. Scripts de gameplay são para o jogo em si.

IMPORTANTE: Neste caso, o comportamento é um pouco diferente de um componente regular, porque sendo um componente de editor, ele terá um método de atualização do editor que será chamado a cada frame enquanto o editor estiver rodando e o jogo não. Mas, e essa é a diferença mais importante, esse componente será registrado, inicializado e iniciado com a própria entidade, independente se está no modo play ou não. Então, se você colocar uma lógica no método start deste componente, ela será chamada mesmo fora do modo play.

Isso pode ser potencialmente perigoso, por exemplo: se você colocar uma lógica no método start de um componente de editor que pega todas as entidades da cena e as deleta, então seu jogo será completamente deletado no editor de maneira destrutiva (sem possibilidade de desfazer). Isso não é uma falha, não é um bug, é como funciona por design. Portanto, esteja ciente disso.

Se você quiser uma forma mais segura de fazer isso, pode usar o Python Code Component, pois ele tem um método de atualização do editor, e ter essa atualização escrita não interferirá se os métodos start e end serão chamados no editor ou não (eles não serão). Veja o Enemy no projeto inicial que o Cave cria, pois ele usa o Python Code Component para desenhar uma esfera de debug ao redor dos inimigos, indicando o raio em que podem vagar. É uma boa forma de aprender mais sobre isso.

Quando Devo Criar Uma Ferramenta?

Não crie uma ferramenta customizada para cada ação minúscula.

Crie uma ferramenta quando ela resolver um problema real no fluxo de trabalho, como:

Você repete a mesma tarefa muitas vezes.
Uma configuração é fácil de esquecer.
Uma cena precisa de validação.
Um designer precisa de uma interface limpa para alterar valores.
Um protótipo precisa de botões rápidos para debug.

Para um iniciante, é melhor primeiro construir o objeto do jogo manualmente. Depois, quando entender os passos, pode automatizar a parte chata.

O Que Você Deve Lembrar

Python no Cave pode ser usado tanto para gameplay quanto para ferramentas de editor.

Scripts de gameplay controlam o que acontece enquanto o jogo está rodando. Scripts de editor ajudam a construir, inspecionar, debugar ou organizar o projeto dentro do Cave Editor.

Você não precisa de ferramentas de editor para fazer seu primeiro jogo, mas elas são poderosas quando seu projeto começa a crescer. Uma pequena ferramenta que economiza cinco minutos hoje pode economizar horas depois.

Cave: Guia de Introdução