Yotsuba ShaderAprende
Documentación

Godot

12 min de lectura

Referencia de Godot: cómo el addon traduce tus shaders, qué se soporta y los nombres de los datos del vértice.

Godot tiene su propio lenguaje de shaders, el Godot Shading Language, guardado en archivos .gdshader. Tú escribes el shader en C# y Yotsuba Shader lo traduce a ese lenguaje.

Un plasma animado de colores: rosa, amarillo y verde

1. El addon: traducir cada vez que pulsas Play#

Ejecutar el comando a mano cada vez que cambias el shader cansa. Yotsuba Shader tiene un addon para el editor de Godot que lo hace por ti.

Primero, copia esa carpeta, yotsubashader, dentro de GodotGame/addons/ (crea addons si no existe). Al abrir el proyecto en Godot, la carpeta aparece en el panel de archivos, como se ve en la captura de arriba.

Segundo, en Godot: Proyecto → Ajustes del proyecto → Plugins. YotsubaShader aparece en la lista, apagado.

Ajustes del proyecto, pestaña Plugins: YotsubaShader aparece sin activar

Marca la casilla para activarlo.

Ajustes del proyecto, pestaña Plugins: YotsubaShader activado

Tercero, en la pestaña General, activa Ajustes avanzados (el interruptor de arriba a la derecha). Aparece una sección llamada Yotsuba Shader: si no la ves, escribe yotsuba en el filtro. El campo project está vacío.

Ajustes del proyecto, General: la sección Yotsuba Shader con el campo Project vacío

Pon project en ../MisShaders/MisShaders.csproj (la ruta es relativa al proyecto de Godot).

La sección Yotsuba Shader con Project apuntando a ../MisShaders/MisShaders.csproj

Estos son todos los ajustes:

AjusteQué esPor defecto
projectRuta al .csproj con tus shaders (absoluta, o relativa al proyecto de Godot)vacío
output_dirDónde se escriben los .gdshaderres://yotsuba_shaders
shader_typespatial, canvas_item o bothspatial
commandEl comando de yotsubadotnet yotsuba
regenerate_on_runRegenerar al pulsar Playactivado

Desde ahora el addon ejecuta el mismo comando compile --target godot que escribiste, y deja los archivos en output_dir. Lo hace:

  • cada vez que pulsas Play, antes de que arranque el juego, y
  • desde el menú Proyecto → Herramientas → Regenerar shaders de YotsubaShader.

Después Godot refresca su sistema de archivos. Si el comando falla, el error sale en el panel de salida de Godot. Un fallo en un tipo de shader que no elegiste (por ejemplo canvas_item, cuando solo usas spatial) no se cuenta como error.

Pulsa Play (el triángulo de arriba a la derecha). Antes de que arranque el juego, el addon traduce el shader, y después se abre la ventana del juego.

El editor de Godot con el proyecto en ejecución

Dos cosas que pueden salir mal:

2. Qué se traduce#

El método del vértice de tu shader es lo que más le importa a Godot. Toma Vertex:

    [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;
    }

En el .spatial.gdshader queda así:

void vertex() {
    vec2 vertice_VERTEX = VERTEX.xy;
    vec2 vertice_UV = UV;
    vec4 ys_position = vec4(0.0);
    Pixel pixel;
    pixel.Posicion = Vec4(vertice_VERTEX.x, vertice_VERTEX.y, 0.0, 1.0);
    pixel.Uv = vertice_UV;
    ys_position = pixel.Posicion;
    v_Uv = pixel.Uv;
    POSITION = ys_position;
}

Fíjate en las correspondencias:

  • El método Vertex pasó a ser void vertex(), y el del fragmento, Fragment, pasó a ser void fragment().
  • El campo VERTEX de tu VerticeGodot lee el VERTEX de Godot, y el campo UV lee UV. Esos son los nombres que Godot le da a los datos de cada vértice, y el plugin los eligió por el nombre de tu campo.
  • Lo que el vértice le entrega al fragmento (pixel.Uv) pasó a ser un varying, v_Uv, que el fragmento lee.
  • La posición que devuelves (gl_Position) se escribe en POSITION. Es una posición en espacio de recorte, el -1 a 1 de antes. Eso quiere decir que Godot no aplica sus propias matrices (modelo, vista y proyección) a un shader hecho así. Si las quieres, tienes que mandarlas como uniform y multiplicarlas tú en el método del vértice. Esta guía no cubre cómo.
  • El color final ([return: location(0)]) va a ALBEDO y ALPHA.

Los nombres que puedes usar en el struct de entrada están en la sección 3. En canvas_item solo existen la posición, el color y UV.

Más cosas que hace el plugin:

  • Un struct con [uniform] se convierte en un uniform por cada campo, con el nombre <Campo>_<Miembro>, como viste.
  • Una textura se convierte en uniform sampler2D <nombre>. Cómo se filtra o se repite lo decide Godot, con las opciones de la textura, y no el SamplerState de tu C#.
  • Los archivos spatial se generan con render_mode unshaded, cull_disabled;. unshaded porque el fragmento ya calcula el color final, y Godot no debe sumarle luz encima. cull_disabled porque un ShaderMaterial no puede apagar el culling (descartar las caras que miran hacia atrás), y, como la posición está en espacio de recorte, Godot descartaba las caras: el rectángulo de pantalla completa no se veía sin esto.

Tomar otro shader del tutorial#

Cualquier shader del Get Started se lleva a Godot con los mismos dos cambios que le hiciste al plasma: en el método del vértice, usa VerticeGodot en lugar de Vertice, y lee vertice.VERTEX en lugar de vertice.Posicion.

3. Los nombres de los datos del vértice#

En el tutorial declaraste VerticeGodot con todos los datos que Godot entrega por vértice. Esta sección explica cada uno.

La regla#

Los datos del vértice se declaran en un struct con estos nombres, tal como en el tutorial:

public struct VerticeGodot
{
    [location(0)] public vec3 VERTEX;
    [location(1)] public vec2 UV;
    [location(2)] public vec3 NORMAL;
    [location(3)] public vec4 COLOR;
}
  • El nombre decide el significado, y es el de Godot. UV es la coordenada de textura, NORMAL es la normal. El número de location sigue siendo tuyo: solo tiene que ser único.
  • Se escriben tal cual en Godot: en mayúsculas, con guion bajo (BONE_INDICES). Esa es la forma que usa el tutorial y la de las tablas de abajo.
  • El idioma no cambia nada. Estos nombres no se traducen: el tutorial en español usa UV, no Textura.
  • El nombre manda sobre el número y la semántica. Si el campo se llama UV, es UV, lleve el [location(1)], el [attribute(1)] o el [TEXCOORD(0)] que lleve.
  • Un nombre que no está en la lista no se adivina. Si tampoco lleva una semántica que el plugin conozca ([POSITION]...), el plugin da un error que dice qué nombres existen, y no deja pasar datos equivocados en silencio.

Los atributos#

Esta es la lista completa de lo que Godot entrega por vértice en un shader spatial. Los de canvas_item son un subconjunto, y se indica en cada fila.

NombreTipo en spatialTipo en canvas_itemEn HlslSyntax
VERTEXvec3vec2POSITION
NORMALvec3No existeNORMAL
TANGENTvec3No existeTANGENT
BINORMALvec3No existeBINORMAL
UVvec2vec2TEXCOORD(0)
UV2vec2No existeTEXCOORD(1)
COLORvec4vec4COLOR
CUSTOM0vec4vec4TEXCOORD(2)
CUSTOM1vec4vec4TEXCOORD(3)
CUSTOM2vec4No existeTEXCOORD(4)
CUSTOM3vec4No existeTEXCOORD(5)
BONE_INDICESuvec4No existeTEXCOORD(6)
BONE_WEIGHTSvec4No existeTEXCOORD(7)
POINT_SIZEfloatfloatTEXCOORD(8)

Los tipos son los de Godot. Si declaras uno distinto de la misma familia, el plugin lo adapta: uno más corto se completa (con 0, y con 1 en la w de VERTEX y de COLOR), y uno más largo se recorta. Por eso un VERTEX de vec2, como el del rectángulo de pantalla completa del tutorial, sirve.

Una convención para cada atributo#

VERTEX: la posición#

[location(0)] public vec3 VERTEX;

Es la posición del vértice en el espacio del objeto. En canvas_item es un vec2.

Una advertencia: si devuelves esta posición tal cual como posición final, es una posición en espacio de recorte, y Godot no le aplica sus matrices. Es lo que hace el plasma de esta guía.

NORMAL, TANGENT y BINORMAL#

[location(2)] public vec3 NORMAL;
[location(5)] public vec3 TANGENT;
[location(6)] public vec3 BINORMAL;

Los tres son vec3 y solo existen en spatial: el 2D no tiene normales. Un shader que los lee no puede ser canvas_item, y el compilador debe decirlo con un error, no generar un archivo roto.

UV y UV2#

[location(1)] public vec2 UV;
[location(4)] public vec2 UV2;

UV va de (0, 0) a (1, 1) sobre la superficie. UV2 es la segunda coordenada, que Godot usa para cosas como mapas de luz. En canvas_item solo existe UV.

COLOR#

[location(3)] public vec4 COLOR;

En spatial es el color del vértice. En canvas_item, Godot lo multiplica por modulate y self_modulate del nodo, así que el valor que lees no es el que guardaste en la malla.

CUSTOM0 a CUSTOM3#

[location(7)] public vec4 CUSTOM0;

Cuatro vec4 para datos propios. Son la salida para un dato que no encaja en ninguno de los otros nombres, y tienen un coste: para llenarlos hay que construir la malla a mano en Godot (con ArrayMesh), porque las mallas integradas (QuadMesh, SphereMesh...) no los traen.

En canvas_item solo existen CUSTOM0 y CUSTOM1. En HlslSyntax viajan como TEXCOORD(2) a TEXCOORD(5).

BONE_INDICES y BONE_WEIGHTS#

[location(11)] public uvec4 BONE_INDICES;
[location(12)] public vec4 BONE_WEIGHTS;

Los datos de un esqueleto: a qué huesos pertenece el vértice y cuánto pesa cada uno. Solo existen en spatial y son de solo lectura. HlslSyntax no tiene una semántica para huesos ni para el tamaño del punto: por eso la variante HLSL usa un [TEXCOORD(n)] cualquiera, y es el nombre del campo el que decide.

POINT_SIZE#

[location(13)] public float POINT_SIZE;

El tamaño de un punto cuando la malla se dibuja como puntos. En las pruebas, leerlo dentro de vertex() hacía que Godot no dibujara nada, así que el plugin siempre entrega 1.0.

VERTEX_ID: no es un campo#

El índice del vértice no viene de la malla: es una variable integrada, igual que gl_VertexIndex en GLSL. No se declara con un campo de nombre VERTEX_ID, sino con la variable integrada de la sintaxis que uses. Godot la entrega como VERTEX_ID en spatial y en canvas_item.

Cómo se aplica#

La prioridad que sigue el compilador para saber qué es cada dato:

  1. El nombre estándar de esta página: siempre gana.
  2. La semántica que lleve el campo ([POSITION]...), si el nombre no está en la lista.
  3. Un error que dice qué nombres existen. Nunca una suposición silenciosa.

Y la regla tiene que valer para todos los motores. Si solo fallara con Godot, un shader compilaría en MonoGame y no en Godot, y la promesa es que lo que compila funciona en cualquiera.

En los motores donde armas tú el vértice (MonoGame, KNI y FNA), el número de location sigue mandando, y el nombre solo le añade significado. Tu VertexDeclaration no cambia.

Lo que está pendiente#

  • Publicar el plugin de Godot con el reconocimiento de nombres (hoy solo existe como cambio sin publicar).
  • Traducir VERTEX_ID, que es una variable integrada y no un campo.
  • Generar la VertexDeclaration y el mapa de canales automáticamente, para que el programador no los escriba.
  • Una regla de portabilidad estricta: que un shader con [location(n)] sin nombre estándar falle al compilar para cualquier motor, no solo para Godot.

Lo que no se puede#

El plugin no traduce esto, y te lo dice con un error claro (no deja un archivo roto):

Un shader que lee NORMAL no puede ser un canvas_item (el 2D no tiene normales). En ese caso la CLI avisa de ese archivo y termina con código de salida 1, pero el .spatial.gdshader sí se escribe.

Resumen#

De todo lo que hiciste, lo propio de Godot es esto:

El plugin (para la CLI)godot (--target godot)
Lo que produceTexto: un .gdshader, spatial o canvas_item
El comandodotnet yotsuba compile MisShaders/MisShaders.csproj --target godot --output ...
Su método en C#ToGodotShader(GodotShaderType), que devuelve un string
Los nombres de los uniforms<Campo>_<Miembro>, como Tiempo_Segundos
El addonaddons/yotsubashader, que regenera los archivos al pulsar Play

Lo que es igual que en las guías de MonoGame, KNI y FNA:

  • El plugin es una herramienta de la CLI yotsuba, y tu juego no lo usa.
  • El primer --target godot descarga el plugin solo.
  • Los datos de un uniform se mandan por nombre, con la regla Campo_Miembro.

Lo que es distinto: en Godot escribes los datos del vértice con nombres (VERTEX, UV), obtienes un archivo de texto en lugar de un binario, y Godot lo carga con load(...) y un ShaderMaterial, no con new Effect(...).