Yotsuba ShaderAprende
Get Started

Tu ventana para ver shaders

9 min de lectura

Un visor pequeño que dibuja en una ventana el shader que elijas, para que veas cada cambio.

Hasta ahora compilaste un shader y leíste su código en la consola. Pero un shader se hace para verse. Un shader del que no ves el resultado es como una receta que nunca cocinas: no aprendes nada.

Por eso, desde este capítulo cambia la forma de trabajar. Todo lo que sigue funciona así:

  1. Escribes un poco de código.
  2. Lo compilas.
  3. Lo miras en una ventana.
  4. Cambias un número y vuelves a mirar.

Para el paso 3 necesitas esa ventana. La vas a construir ahora, una sola vez.

Qué es el visor#

El visor es una pequeña escena de Godot que hace tres cosas:

  • Dibuja un rectángulo que cubre toda la ventana (el mismo rectángulo del Shader 1).
  • Le pone encima el shader que le nombres.
  • Le entrega el tamaño de la ventana y el tiempo, por si el shader los pide.

Fíjate en una cosa: el visor no forma parte de tu shader. Tus shaders siguen en MisShaders, sin saber nada de Godot. El visor es solo una herramienta de trabajo, como un banco para probar piezas. Cuando quieras llevar tus shaders a tu juego, usarás la misma librería en tus propias escenas.

Paso 1: crea el proyecto de Godot#

Crea una carpeta vacía llamada GodotGame dentro de tu carpeta Tutorial. Abre Godot, pulsa Create y rellena la ventana así:

La ventana Create New Project de Godot: nombre GodotGame, ruta terminada en Tutorial/GodotGame, el mensaje "The project folder exists and is empty" y el renderizador Forward+

  • Project Name: GodotGame.
  • Project Path: la ruta completa de esa carpeta vacía. Godot lo confirma con "The project folder exists and is empty". Deja Create Folder apagado, porque la carpeta ya existe.
  • Renderer: Forward+ está bien.

Pulsa Create. El editor se abre con un proyecto vacío:

El editor de Godot recién creado el proyecto: sin escena y con el panel FileSystem que solo tiene icon.svg

Tutorial/
├── MisShaders/       tus shaders
├── Probar/           la consola del capítulo anterior
└── GodotGame/        nuevo: el proyecto de Godot

Va dentro de Tutorial a propósito. La herramienta yotsuba se instaló con un manifiesto (.config/dotnet-tools.json), y .NET busca ese manifiesto en la carpeta actual y en las de arriba. Si el proyecto de Godot está dentro de Tutorial, dotnet yotsuba también funciona desde ahí.

Paso 2: instala el addon#

Yotsuba Shader tiene un addon para el editor de Godot. Cada vez que pulsas Play, le pide a yotsuba que traduzca tus shaders a archivos de Godot, así que nunca tienes que ejecutar el comando a mano. El addon viene dentro del paquete NuGet del plugin de Godot. Desde la carpeta Tutorial:

curl -L -o godot-addon.zip https://www.nuget.org/api/v2/package/YotsubaShader.Extensions.Godot/0.9.0
unzip -q godot-addon.zip "content/addon/addons/*" -d godot-addon
cp -R godot-addon/content/addon/addons GodotGame/

Un .nupkg es un archivo zip, así que en Windows también puedes renombrarlo a .zip y copiar a mano la carpeta addons/yotsubashader.

Godot solo mira sus archivos al arrancar, así que recarga el proyecto (Project → Reload Current Project). La carpeta nueva addons aparece en el panel FileSystem.

Ahora enciende el addon. Abre Project → Project Settings → Plugins. YotsubaShader está en la lista, apagado:

La pestaña Plugins de Project Settings con YotsubaShader en la lista y su casilla Enabled sin marcar

Marca la casilla Enabled. Luego abre la pestaña General, activa Advanced Settings (arriba a la derecha), escribe yotsuba en el filtro y elige la sección Yotsuba Shader. El campo Project está vacío:

La sección Yotsuba Shader de la pestaña General: Project vacío, Output Dir res://yotsuba_shaders, Shader Type spatial, Command dotnet yotsuba y Regenerate on Run activado

Rellena project con:

../MisShaders/MisShaders.csproj

La misma sección con el campo Project puesto en ../MisShaders/MisShaders.csproj

La ruta se cuenta desde el proyecto de Godot. Deja el resto como está: Output Dir es donde van los shaders traducidos, Shader Type es spatial (para objetos 3D), Command es la herramienta y Regenerate on Run hace que el addon traduzca cada vez que pulsas Play.

Paso 3: el rectángulo y la ventana#

Aquí está la idea clave de esta ruta: Godot no dibuja un rectángulo suelto. Dibuja mallas (meshes), dentro de escenas. Así que el visor es una escena con tres nodos:

  • Visor: la raíz. Lleva el script.
  • Pantalla: un MeshInstance3D, el objeto que mostrará tu shader.
  • Camera3D: sin ella Godot no tiene por dónde mirar.

Constrúyela paso a paso.

La raíz. En el panel Scene, pulsa 3D Scene. Godot crea un Node3D. Haz doble clic en su nombre y llámalo Visor.

El nodo Pantalla. Clic derecho en Visor y elige Add Child Node… (o selecciónalo y pulsa Cmd/Ctrl+A). Escribe MeshInstance3D, selecciónalo y pulsa Create:

La ventana Create New Node con MeshInstance3D escrito en el buscador y seleccionado

Haz doble clic en el nodo nuevo y cámbiale el nombre a Pantalla.

La cámara. Selecciona Visor otra vez y añade otro nodo hijo, esta vez un Camera3D. Déjalo como está.

El margen. Selecciona Pantalla. En el Inspector abre Geometry y pon Extra Cull Margin en 16384:

El Inspector del nodo Screen con Geometry abierto y Extra Cull Margin en 16384 m; el árbol de la escena muestra Viewer y Screen

Por qué: antes de dibujar un objeto, Godot comprueba, con su posición en el mundo 3D, si está dentro de lo que ve la cámara. Tu shader mueve los vértices a otro sitio, pero eso pasa después. El margen grande le dice a Godot: "no tires este objeto".

El script. Clic derecho en Visor y elige Attach Script…. Deja el lenguaje en GDScript (o elige C# si usas .NET), pon la ruta res://visor.gd y pulsa Create:

La ventana Attach Node Script: lenguaje GDScript, hereda de Node3D, ruta res://viewer.gd

Se abre el editor de scripts con una plantilla. Reemplaza todo su contenido por esto:

GodotGame/visor.gd
extends Node3D

## Nombre de la clase del shader en MisShaders (Degradado, Colores, Plasma...).
@export var nombre_shader := "Degradado"

## La imagen para los shaders que declaran una textura `Foto`. Arrástrala aquí desde el Inspector.
@export var foto: Texture2D

var _material := ShaderMaterial.new()


func _ready() -> void:
	# Las cuatro esquinas del rectángulo, como la tabla del capítulo: posición y Uv.
	var arrays := []
	arrays.resize(Mesh.ARRAY_MAX)
	arrays[Mesh.ARRAY_VERTEX] = PackedVector3Array([
		Vector3(-1, -1, 0), Vector3(1, -1, 0), Vector3(-1, 1, 0), Vector3(1, 1, 0)])
	arrays[Mesh.ARRAY_TEX_UV] = PackedVector2Array([
		Vector2(0, 0), Vector2(1, 0), Vector2(0, 1), Vector2(1, 1)])
	# Tu struct pide NORMAL y TANGENT, así que la malla también tiene que llevarlos.
	arrays[Mesh.ARRAY_NORMAL] = PackedVector3Array([
		Vector3(0, 0, 1), Vector3(0, 0, 1), Vector3(0, 0, 1), Vector3(0, 0, 1)])
	arrays[Mesh.ARRAY_TANGENT] = PackedFloat32Array([
		1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1])
	var mesh := ArrayMesh.new()
	mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLE_STRIP, arrays)

	_material.shader = load("res://yotsuba_shaders/MisShaders/%s.spatial.gdshader" % nombre_shader)
	if foto:
		_material.set_shader_parameter("Foto", foto)
	$Pantalla.mesh = mesh
	$Pantalla.material_override = _material


func _process(_delta: float) -> void:
	var size := get_viewport().get_visible_rect().size
	var seconds := Time.get_ticks_msec() / 1000.0
	# Cualquier uniform llamado <Field>_Ancho, <Field>_Alto or <Field>_Segundos recibe su valor.
	for uniform in _material.shader.get_shader_uniform_list():
		var uniform_name: String = uniform.name
		if uniform_name.ends_with("_Ancho"):
			_material.set_shader_parameter(uniform_name, size.x)
		elif uniform_name.ends_with("_Alto"):
			_material.set_shader_parameter(uniform_name, size.y)
		elif uniform_name.ends_with("_Segundos"):
			_material.set_shader_parameter(uniform_name, seconds)

Las esquinas son la misma tabla de los capítulos anteriores: cada una dice dónde está y cuál es su Uv. Una cosa cambia en Godot: el eje vertical de la pantalla va al revés (Y = -1 es arriba), así que la esquina que tiene Uv = (0, 0) se escribe con Y = -1. Así la Uv sigue empezando arriba a la izquierda, y los shaders se ven igual que en todas las demás rutas.

Otras líneas que vale la pena leer:

  • ShaderMaterial es un material cuyo pintado lo hace un shader que tú le das. material_override hace que Pantalla lo use.
  • _ready() se ejecuta una vez, cuando arranca la escena. _process() se ejecuta en cada fotograma.
  • El bucle de _process mira los uniform de tu shader y manda un valor a los cuyo nombre termina en _Ancho, _Alto o _Segundos (por ejemplo Datos_Segundos o Tiempo_Segundos). Si tu shader no declara ninguno, no pasa nada. En unos capítulos sabrás para qué sirven.
  • @export (o [Export] en C#) pone nombre_shader en el Inspector, así eliges el shader sin tocar el código.

Así se ve el editor con tu script:

El editor de scripts de Godot mostrando viewer.gd, con el árbol de la escena a la izquierda

Si usas C#, el archivo del script se tiene que llamar igual que la clase, Visor.cs, y Godot necesita un .csproj para el proyecto de Godot (el editor lo crea con Proyecto → Herramientas → C# → Crear solución de C#). Ese .csproj no es MisShaders: es el del juego.

Paso 4: ve tu primer shader#

Guarda la escena (Cmd/Ctrl+S) como visor.tscn. Selecciona el nodo Visor: en el Inspector, Shader Name dice Degradado.

La escena terminada: Viewer con Screen y Camera3D, y en el Inspector el campo Shader Name con Gradient

Pulsa Play (el triángulo de arriba a la derecha). La primera vez Godot pide una escena principal: elige Select Current. Antes de que empiece el juego, el addon traduce MisShaders, y luego se abre la ventana.

La ventana del juego con un degradado de atardecer: rosa arriba, naranja en el medio y amarillo abajo

Ese es tu shader, dibujado por la GPU. Cierra la ventana para volver al editor.

El ciclo de trabajo#

Durante el resto del tutorial usarás este ciclo:

  1. Editas un archivo de MisShaders.
  2. Pulsas Play en Godot. El addon compila por ti.
  3. Miras la ventana.

Pruébalo con tu primer experimento. Abre MisShaders/Degradado.cs y busca esta línea en Fragment:

float rojo = 1f;

Cámbiala por esta:

float rojo = pixel.Uv.X;

Guarda y pulsa Play:

El mismo degradado, pero el rojo crece de izquierda a derecha: a la izquierda quedan el azul oscuro y el verde, a la derecha el rosa y el amarillo

El rojo ya no vale lo mismo en toda la pantalla: ahora crece de izquierda a derecha, porque pixel.Uv.X va de 0 en el borde izquierdo a 1 en el derecho.

Acabas de hacer lo que harás cientos de veces: cambiar un número y ver qué pasa. Antes de seguir, vuelve la línea a float rojo = 1f;.

Un archivo de partida#

Para cada capítulo siguiente vas a crear un shader nuevo. Todos arrancan igual, con el mismo Vertex de siempre, así que conviene tenerlo como molde. Crea MisShaders/Plantilla.cs:

MisShaders/Plantilla.cs
using YotsubaShader.GlslSyntax;
using YotsubaShader.GlslSyntax.Types;
using YotsubaShader.Language;

namespace MisShaders;

public class Plantilla
{
    [ShaderStage(Stage.Vertex)]
    public Pixel Vertex(VerticeGodot vertice)
    {
        Pixel pixel;
        pixel.Posicion = Crear.Vec4(vertice.VERTEX.X, vertice.VERTEX.Y, 0f, 1f);
        pixel.Uv = vertice.UV;
        return pixel;
    }

    [ShaderStage(Stage.Fragment)]
    [return: location(0)]
    public vec4 Fragment(PixelIn pixel)
    {
        return Crear.Vec4(0f, 0f, 0f, 1f);
    }
}

El Fragment de esta plantilla devuelve negro (0, 0, 0). Es un shader que todavía no hace nada, listo para que tú le pongas lo suyo.

Cuando un capítulo te diga "copia Plantilla.cs como Colores.cs", haz esto:

  1. Copia el archivo y llámalo Colores.cs.
  2. Dentro, cambia public class Plantilla por public class Colores.

El nombre de la clase tiene que coincidir con lo que escribes después de -- en el visor.

Comprueba que todo funciona ejecutando la plantilla. Selecciona el nodo Visor, escribe Plantilla en Nombre Shader y pulsa Play. Debe abrirse una ventana completamente negra. Si la ves, estás listo.

Si algo falla#

Qué vesQué significaQué hacer
Cannot open file 'res://yotsuba_shaders/MisShaders/Colores.spatial.gdshader'El nombre en Nombre Shader está mal escrito, o el addon no se ejecutó.Revisa las mayúsculas, y que el plugin YotsubaShader esté activado.
La ventana muestra el shader viejoEl addon está apagado o regenerate_on_run está apagado.Enciéndelo en la configuración del proyecto, o usa Proyecto → Herramientas → Regenerate YotsubaShader shaders.
El panel de Salida dice que no encontró dotnetGodot, abierto desde el Dock o el Finder, no ve el mismo PATH que tu terminal.Pon la ruta completa de dotnet en el ajuste command del addon.
dotnet yotsuba dice que no existeEl proyecto de Godot está fuera de la carpeta donde ejecutaste dotnet new tool-manifest.Mueve GodotGame dentro de Tutorial.
Un error CS con número y líneaEs un error normal de C# en tu shader.Léelo, ve a esa línea y corrígela.
La ventana sale negra o vacíaGodot descartó el rectángulo o el shader falló.Revisa el extra_cull_margin de Pantalla y el panel de Salida.

Lo que aprendiste#

  • Para ver un shader hace falta una ventana. El visor es esa ventana, y es una herramienta aparte: tus shaders no dependen de ella.
  • El ciclo de trabajo es editar, compilar con add y mirar con el visor.
  • Plantilla.cs es el molde de todos los shaders que vienen: un Vertex ya escrito y un Fragment que devuelve negro.

Siguiente: Los colores.