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 del Editor que te ayuden a construir tu juego más rápido.

Esto es especialmente útil porque muchos proyectos tienen tareas repetitivas. Quizás a menudo colocas enemigos, creas puntos de control, organizas carpetas, pruebas valores o inspeccionas datos de la escena. En lugar de hacer todo manualmente 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, edificios procedurales y mucho más.

En esta lección aprenderás:

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

No necesitas crear herramientas inmediatamente al empezar, pero es bueno saber que este sistema existe. Es una de esas funciones que se vuelve más valiosa a medida que tu proyecto crece.

Scripts de Juego vs Herramientas de Editor

En resumen:

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

Tipo de Script	Se Ejecuta En	Ejemplo
Script de Juego	Modo Play y Juego Exportado.	Movimiento del jugador, IA de enemigos, puertas, objetos recogibles.
Herramienta de Editor	Cave Editor.	Ayudante de nivel, renombrador masivo, inspector de escenas, generador de edificios procedurales, herramienta de colocación.

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

Por qué las Herramientas de Editor Son Útiles

Al principio, las herramientas personalizadas pueden parecer algo solo para equipos grandes.

Pero incluso los desarrolladores en solitario pueden beneficiarse de pequeñas herramientas porque reducen el trabajo manual repetitivo. Si haces la misma tarea muchas veces, un script simple de editor puede hacer que el proyecto se sienta mucho más rápido de 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 Play.
Ayudar a diseñadores a ajustar datos de juego.

Por ejemplo, imagina que construyes un juego en tercera persona con muchos campamentos de enemigos. En lugar de crear manualmente la misma estructura de carpetas cada vez, podrías crear una herramienta que agregue automáticamente un Enemy Group, varios puntos de aparición y un área de activación.

Scripts Solo para Editor

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

#editoronly

Esto le indica a Cave que el script está pensado para uso en el editor.

Esto importa porque las herramientas de editor pueden usar APIs o comportamientos que solo tienen sentido dentro del editor. Normalmente no quieres que un asistente de diseño de niveles o un panel de depuración formen parte del runtime final del juego.

Esto también es importante para indicarle a Cave qué scripts ejecutar al iniciar el juego y cuáles ignorar. Por defecto, ejecuta todos los scripts, así que si quieres que uno sea ignorado, debe incluir este comentario como primera línea.

Entonces, si creas un script que existe solo para ayudarte a trabajar dentro de Cave Editor, haz que sea solo para editor.

Herramientas de Pestaña del Editor

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

Una pestaña del editor es un panel personalizado que aparece dentro de Cave Editor. 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 ejemplo.")
        cave.ui.separator()

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

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

Este también es el código por defecto cuando agregas una pestaña de editor. Si haces clic para abrirla en la pestaña de propiedades y luego vas a la pestaña de herramientas de editor, verás la clase example tab que aparece como una pestaña de depuración. Luego solo necesitas registrar o recargar la pestaña y estará disponible en la interfaz:

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

cave.ui.DebugTab crea una pestaña personalizada del editor.
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 usarse para enviar información a la consola.

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

Qué 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 interfaz del editor necesita dibujarse y actualizarse. Esto significa que el código dentro de draw() debe 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("Se hizo clic en crear grupo de enemigos")

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

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

Una Idea Práctica de Herramienta

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

Environment
Enemies
Gameplay Triggers
Lighting
Audio
Debug Helpers

Podrías crear una herramienta de editor con un botón llamado Create Level Folders. Al hacer clic, podría crear esas entidades de carpeta en la escena actual. Recuerda: una carpeta en el Scene Graph es solo una Entity sin componentes adjuntos.

Puede parecer pequeño, pero herramientas pequeñas como esta facilitan mantener organizados los proyectos grandes. También te ayudan a seguir tus propias convenciones de proyecto sin tener que recordar cada paso manualmente.

Componentes de Editor

A veces, quieres mezclar lógica de juego con lógica de editor. Por ejemplo, podrías querer 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 indicando 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 comportamiento especial de editor, pero ese comportamiento no debe formar parte del juego real.

Por ejemplo:

Un punto de aparición podría mostrar información auxiliar 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 de creación del juego. Los scripts de juego son para el juego en sí.

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

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

Si quieres una forma más segura de hacerlo, puedes usar el Componente de Código Python, porque sí tiene un método de actualización de editor, y tener este método escrito no interferirá con si los métodos de start y end se llaman en el editor (no se llamarán). Revisa el Enemy en el proyecto inicial que crea Cave, porque usa el Componente de Código Python para dibujar una esfera de depuración alrededor de los enemigos, indicando el radio en que pueden moverse. Es una buena forma de aprender más sobre esto.

¿Cuándo Deberías Crear una Herramienta?

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

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

Repetir la misma tarea muchas veces.
Que una configuración sea fácil de olvidar.
Que una escena necesite validación.
Que un diseñador necesite una interfaz más limpia para cambiar valores.
Que un prototipo necesite botones rápidos de depuración.

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

Lo Que Debes Recordar

Python en Cave puede usarse tanto para la jugabilidad como para herramientas de editor.

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

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

Cave: Guía de Inicio