Cave: Guía para Principiantes

En la lección anterior, aprendiste cómo Python puede controlar entidades durante el juego. Pero Python en Cave no se limita al juego en ejecución. También puedes usarlo para crear Herramientas de Editor que te ayuden a construir tu juego más rápido.

Esto es especialmente útil porque muchos proyectos tienen tareas repetitivas. Tal vez a menudo colocas enemigos, creas puntos de control, organizas carpetas, pruebas valores o inspeccionas datos de la escena. En lugar de hacer todo a mano cada vez, puedes crear pequeñas herramientas que automaticen partes de tu flujo de trabajo. Incluso puedes crear editores más avanzados que te permitan hacer niveles generados proceduralmente, construcciones procedurales y mucho más.

En esta lección, aprenderás:

• La diferencia entre los scripts de juego y los scripts de editor.
• Para qué se puede usar una herramienta de editor.
• Cómo está estructurada una herramienta de pestaña de editor.
• Por qué importa #editoronly.
• Cuándo vale la pena crear una herramienta personalizada.

No necesitas construir herramientas de inmediato al comenzar, pero es bueno saber que este sistema existe. Es una de esas características que se vuelve más valiosa a medida que tu proyecto crece.

Scripts de Juego vs Herramientas de Editor

En pocas palabras:

• Scripts de Juego se ejecutan mientras el juego está en reproducción.
• Herramientas de Editor se ejecutan dentro del editor para ayudarte a trabajar en el proyecto.

Por ejemplo, un script de apertura de puerta es lógica de juego porque el jugador debería experimentarlo mientras juega. Una herramienta que coloca diez antorchas a lo largo de un pasillo es lógica de editor porque te ayuda a construir el nivel, pero no necesita existir en el juego exportado.

Por Qué Son Útiles las Herramientas de Editor

Al principio, las herramientas personalizadas pueden sonar como algo que solo necesitan los equipos grandes.

Pero incluso los desarrolladores solitarios pueden beneficiarse de herramientas pequeñas porque reducen el trabajo manual repetido. Si haces la misma tarea muchas veces, un simple script de editor puede hacer que el proyecto se sienta mucho más rápido para trabajar.

Las herramientas de editor pueden ayudar con cosas como:

• Colocar grupos de entidades.
• Verificar si faltan componentes requeridos.
• Crear configuraciones comunes de escena.
• Imprimir información de depuración.
• Probar valores sin entrar en Modo de Reproducción.
• Ayudar a los diseñadores a ajustar datos de juego.

Por ejemplo, imagina que estás construyendo un juego en tercera persona con muchos campamentos enemigos. En lugar de crear manualmente la misma estructura de carpetas cada vez, podrías crear una herramienta que añada un Grupo de Enemigos, unos puntos de generación y un área de activación automáticamente.

Scripts Solo para Editor

Los scripts de editor generalmente comienzan con esta línea:

#editoronly

Esto le dice a Cave que el script está destinado para uso en el editor.

Eso importa porque las herramientas de editor pueden usar APIs o comportamientos que solo tienen sentido dentro del editor. Normalmente no deseas que un ayudante de diseño de niveles o un panel de depuración sea parte de la ejecución de tu juego final.

Esto también es importante para decirle a Cave qué scripts ejecutar al inicio del juego y qué scripts ignorar. Por defecto, ejecuta todos los scripts, así que si deseas que uno sea ignorado, debe incluir este comentario como la primera línea.

Así que, si estás creando un script que existe solo para ayudarte a trabajar dentro del Editor de Cave, hazlo solo para editor.

Herramientas de Pestaña de Editor

Una forma común de crear una herramienta es con una Pestaña de Editor.

Una pestaña de editor es un panel personalizado que aparece dentro del Editor de Cave. Tiene un método draw(), y Cave llama a ese método mientras la pestaña es visible para que la herramienta pueda dibujar botones, texto, propiedades y otros controles.

Una pestaña de editor muy pequeña se ve así:

#editoronly
import cave

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

    def draw(self):
        cave.ui.text("Esta es una herramienta de muestra.")
        cave.ui.separator()

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

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

Este también es el código predeterminado cuando añades una pestaña de editor. Si haces clic para abrirlo en la pestaña de propiedades y luego vas a la pestaña de herramientas de editor, verás la clase de pestaña de ejemplo apareciendo como una pestaña de depuración. Luego, todo lo que necesitas hacer es registrar o recargar la pestaña y estará disponible para ti en la UI:

Este ejemplo es simple, pero ya muestra la idea básica:

• cave.ui.DebugTab crea una pestaña de editor personalizada.
• draw() define lo que muestra la pestaña.
• cave.ui.text() dibuja texto.
• cave.ui.prop() dibuja una propiedad editable.
• cave.ui.buttonDark() crea un botón.
• print() puede ser usado para enviar información a la consola.

Así de simple es crear herramientas personalizadas para el Editor de Cave. Puedes usar esta misma estructura para construir herramientas reales más tarde.

Lo Que Significa el Método draw()

El método draw() no es como start() en un componente de juego.

Se llama repetidamente mientras la herramienta es visible, porque la UI del editor necesita ser dibujada y actualizada. Esto significa que el código dentro de draw() debería describir la interfaz actual de la herramienta.

Por ejemplo:

def draw(self):
    cave.ui.text("Ayudante de Nivel:")

    if cave.ui.buttonDark("Crear Grupo de Enemigos"):
        print("Grupo de enemigos creado")

El botón se dibuja cada vez que se actualiza la pestaña, pero el código dentro del if solo se ejecuta cuando el usuario hace clic en el botón.

Ese patrón es muy común en herramientas de editor.

Una Idea de Herramienta Práctica

Supongamos que estás construyendo un nivel y a menudo necesitas las mismas carpetas básicas:

• Entorno
• Enemigos
• Disparadores de Juego
• Iluminación
• Audio
• Ayudantes de Depuración

Podrías crear una herramienta de editor con un botón llamado Crear Carpetas de Nivel. Cuando se hace clic, podría crear esas entidades de carpeta en la escena actual. Recuerda: una Carpeta en el Grafo de Escena es solo una Entidad sin componentes adjuntos.

Eso puede sonar pequeño, pero herramientas pequeñas como esta hacen que proyectos grandes sean más fáciles de mantener organizados. También te ayudan a seguir las convenciones de tu propio proyecto sin tener que recordar cada paso manualmente.

Componentes de Editor

A veces, deseas mezclar la lógica de juego con la lógica de editor. Por ejemplo, es posible que desees tener un componente adjunto a una entidad que también ejecute lógica de editor, por ejemplo, para mostrar información de depuración o una esfera de depuración que indique el rango de movimiento o ataque de un enemigo. En este caso, en lugar de usar cave.Component, usas cave.EditorComponent.

Esto es útil cuando una entidad necesita un comportamiento especial en el editor, pero ese comportamiento no debe ser parte del juego real.

Por ejemplo:

• Un punto de generación podría dibujar información de ayuda en el editor.
• Un volumen de activación podría exponer controles de depuración.
• Un marcador de nivel podría validar si está configurado correctamente.

La idea importante es que los scripts de editor son para el flujo de trabajo en torno a la creación del juego. Los scripts de juego son para el propio juego.

IMPORTANTE: En este caso, el comportamiento es un poco diferente al de un componente regular, porque dado que es un componente de editor, tendrá un método de actualización de editor que se llamará cada cuadro mientras el editor se esté ejecutando y el juego no. Pero, y esta es la diferencia más importante, este componente será registrado e inicializado y se iniciará con la entidad en sí, independientemente de si está en modo de reproducción o no. Así que si pones una lógica en el método de inicio de este componente, se llamará incluso fuera del modo de reproducción.

Esto puede ser potencialmente peligroso, por ejemplo: si pones una lógica en el método de inicio de un componente de editor que obtiene todas las entidades en la escena y las elimina, entonces tu juego se eliminará por completo en el editor de manera destructiva (no se puede deshacer). Eso no es un fallo, no es un error, es cómo funciona por diseño. Así que ten cuidado con eso.

Si deseas una forma más segura de hacer esto, puedes usar el Componente de Código Python, porque sí tiene un método de actualización de editor, y tener esta actualización de editor escrita no interferirá con si se llaman las actualizaciones de inicio y fin en el editor o no (no lo harán). Revisa el Enemigo en el proyecto inicial que crea Cave, porque utiliza el Componente de Código Python para dibujar una esfera de depuración alrededor de los enemigos, indicando el radio en el que puede deambular. Es una buena forma de aprender más sobre ello.

¿Cuándo Deberías Construir una Herramienta?

No crees una herramienta personalizada para cada acción pequeña.

Construye una herramienta cuando resuelva un problema real de flujo de trabajo, como:

• Repites la misma tarea muchas veces.
• Un ajuste es fácil de olvidar.
• Se necesita validación en una escena.
• Un diseñador necesita una interfaz más limpia para cambiar valores.
• Un prototipo necesita botones de depuración rápidos.

Para un principiante, es mejor construir primero el objeto del juego manualmente. Luego, una vez que entiendas los pasos, puedes automatizar la parte aburrida.

Lo Que Deberías Recordar

Python en Cave puede ser usado tanto para la jugabilidad como para las herramientas de editor.

Los scripts de juego controlan lo que sucede mientras el juego está en funcionamiento. Los scripts de editor te ayudan a construir, inspeccionar, depurar u organizar el proyecto dentro del Editor de Cave.

No necesitas herramientas de editor para hacer tu primer juego, pero son poderosas cuando tu proyecto comienza a crecer. Una pequeña herramienta que ahorra cinco minutos hoy puede ahorrar horas más tarde.