Cave: Guia de Introdução

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

Isso é especialmente útil porque muitos projetos têm tarefas repetitivas. Talvez você frequentemente coloque inimigos, crie pontos de verificação, 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 que você faça níveis gerados proceduralmente, edifícios procedurais e muito mais.

Nesta lição, você 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 guia de editor é estruturada.
• Por que #editoronly é importante.
• Quando vale a pena criar uma ferramenta personalizada.

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

Scripts de Gameplay vs Ferramentas de Editor

Em poucas palavras:

• Scripts de Gameplay são executados enquanto o jogo está em andamento.
• Ferramentas de Editor são executadas dentro do editor para ajudar você a trabalhar no projeto.

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

Por que as Ferramentas de Editor são Úteis

À primeira vista, ferramentas personalizadas podem parecer algo que apenas grandes equipes precisam.

Mas até mesmo desenvolvedores solo podem se beneficiar de pequenas ferramentas, pois elas reduzem o trabalho manual repetido. Se você realiza a mesma tarefa muitas vezes, um simples script de editor pode tornar o projeto muito mais rápido de trabalhar.

As ferramentas de editor podem ajudar com coisas como:

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

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

Scripts Apenas para Editor

Scripts de editor geralmente começam com esta linha:

#editoronly

Isso informa ao Cave que o script é destinado ao uso do editor.

Isso é importante porque ferramentas de editor podem usar APIs ou comportamentos que só fazem sentido dentro do editor. Normalmente, você não quer que um auxiliar de design de nível ou um painel de depuração faça parte do runtime final do seu jogo.

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

Portanto, se você estiver criando um script que existe apenas para ajudar você a trabalhar dentro do Cave Editor, faça-o apenas para editor.

Ferramentas de Guia do Editor

Uma maneira comum de criar uma ferramenta é com uma Guia do Editor.

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

Uma guia de editor muito pequena se parece com isso:

#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 quando você adiciona uma guia de editor. Se você clicar para abri-la na guia de propriedades e depois for para a guia de ferramentas do editor, verá a classe da guia de exemplo aparecendo como uma guia de depuração. Então, tudo o que você precisa fazer é registrar ou recarregar a guia e ela estará disponível para você na interface:

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

• cave.ui.DebugTab cria uma guia de editor personalizada.
• draw() define o que a guia 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 ao console.

É assim que é simples criar Ferramentas personalizadas para o Cave Editor. Você pode usar essa mesma estrutura para construir ferramentas reais mais tarde.

O que o Método draw() Significa

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

Ele é chamado repetidamente enquanto a ferramenta está visível, porque a interface do usuário 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("Criar grupo de inimigos clicado")

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

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

Uma Ideia Prática de Ferramenta

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

• Ambiente
• Inimigos
• Gatilhos de Gameplay
• Iluminação
• Áudio
• Auxiliares de Depuração

Você poderia criar uma ferramenta de editor com um botão chamado Criar Pastas de Nível. Ao clicar, ela poderia criar essas entidades de pasta na cena atual. Lembre-se: uma Pasta no Gráfico de Cena é apenas uma Entidade sem componentes anexados a ela.

Isso pode parecer pequeno, mas ferramentas pequenas como essa facilitam a organização de grandes projetos. Elas também ajudam você a seguir suas próprias convenções de projeto sem precisar lembrar cada passo manualmente.

Componentes do Editor

Às vezes, você quer misturar lógica de gameplay com lógica de editor. Por exemplo, você pode querer ter um componente anexado a uma entidade que também executa lógica de editor, por exemplo, para exibir uma informação de depuração ou uma esfera de depuração indicando o movimento ou a faixa de 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 de editor, mas esse comportamento não deve fazer parte do jogo real.

Por exemplo:

• Um ponto de spawn poderia desenhar informações auxiliares no editor.
• Um volume de ativação poderia expor controles de depuração.
• Um marcador de nível poderia validar se está configurado corretamente.

A ideia importante é que scripts de editor servem para o fluxo de trabalho de criação do jogo. Scripts de gameplay servem para o jogo em si.

IMPORTANTE: Nesse caso, o comportamento é um pouco diferente de um componente regular, porque como é um componente de editor, ele terá um método de atualização de editor que será chamado a cada frame enquanto o editor estiver em execução e o jogo não. Mas, e essa é a diferença mais importante, esse componente será de fato registrado e inicializado e será iniciado com a entidade, independentemente de estar no modo de jogo ou não. Portanto, se você colocar uma lógica no método de início deste componente, ela será chamada mesmo fora do modo de jogo.

Isso pode ser potencialmente perigoso, por exemplo: se você colocar uma lógica no método de início de um componente de editor que obtém todas as entidades na cena e as exclui, então seu jogo será completamente deletado no editor de uma maneira destrutiva (não pode desfazer). Isso não é uma falha, não é um bug, é assim que funciona por design. Portanto, esteja ciente disso.

Se você quiser uma maneira mais segura de fazer isso, você pode usar o Componente de Código Python, porque ele tem um método de atualização de editor, e ter essa atualização de editor escrita não interferirá em se os métodos de início e fim serão chamados no editor ou não (não serão). Verifique o Inimigo no projeto inicial que o Cave cria, pois ele usa o Componente de Código Python para desenhar uma esfera de depuração ao redor dos inimigos, indicando o raio que eles podem vagar. É uma boa maneira de aprender mais sobre isso.

Quando Deveria Criar uma Ferramenta?

Não crie uma ferramenta personalizada para cada ação pequena.

Construa uma ferramenta quando ela resolver um problema real de 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 mais limpa para alterar valores.
• Um protótipo precisa de botões de depuração rápidos.

Para um iniciante, é melhor primeiro construir o objeto do jogo manualmente. Depois, uma vez que você entenda 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á em execução. Scripts de editor ajudam você a construir, inspecionar, depurar 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.