Crea tu primer shader para Bloxd.io: archivos, luz y agua

16 nov 2026 8 min

Guía para crear un shader pack de Bloxd.io: prepara el ZIP, ajusta la luz, prueba efectos en lava y agua y comprueba las reglas de la API 5.

Un shader pack de Bloxd.io puede dar a los bloques una luz más cálida, hacer que la lava brille o animar el agua, pero no añade texturas ni altera el aspecto del cielo, los personajes, los mobs o los objetos. La guía para principiantes de Bloxdhub explica cómo crear el ZIP y qué reglas debe respetar para que el juego lo acepte.

Qué cambia un shader pack

Un pack modifica la iluminación del mundo: puede ajustar el color de la luz, suavizar sombras o cambiar el brillo de superficies. Bloxdhub distingue este sistema de los paquetes de texturas, que son los que sirven para modificar las imágenes aplicadas a los bloques.

El efecto se limita a los elementos que procesa el renderizador WebGPU: bloques sólidos, agua y lava. El cielo y los personajes quedan fuera, al igual que mobs y objetos, según la guía de Bloxdhub. Algunas partidas también desactivan los shaders, así que el resultado puede variar según el modo de juego.

La documentación comunitaria no oficial sobre la API describe tres grupos de renderizado: terreno, líquidos y modelos. En conjunto hay nueve hooks, es decir, funciones con nombres determinados que el juego invoca para modificar partes concretas del dibujo. Para un primer pack no hace falta usar los nueve: basta con cambiar el hook que corresponda al efecto buscado.

Prepara los archivos y el ZIP

El punto de partida es una carpeta con un archivo pack.json y uno o más .wgsl. El manifiesto pack.json identifica el paquete: debe indicar apiVersion con el valor 5 y un nombre. El campo author es opcional, según la referencia comunitaria Prism Shaders; Bloxdhub también lo incluye en su ejemplo inicial.

Los archivos WGSL contienen los hooks. Se pueden repartir en varios archivos y Bloxd los procesa ordenados por nombre. Después, hay que comprimir la carpeta —o sus archivos— en un ZIP.

Crea tu primer shader para Bloxd.io: archivos, luz y agua
Imagen generada con IA

La documentación no oficial indica que el motor añade automáticamente las definiciones de la API al cargar el pack: quien lo crea escribe solo los hooks que quiere modificar. WGSL es el lenguaje de sombreado usado por WebGPU; la documentación lo presenta como familiar para quienes hayan programado en JavaScript, aunque exige tipos explícitos y distingue, por ejemplo, los números enteros de los decimales.

Hay que evitar nombres propios que empiecen por “bloxd”, porque están reservados para el juego, y no reutilizar nombres integrados o palabras reservadas. Bloxdhub también advierte que no se permiten atributos @, texturas o samplers añadidos por el pack, ni variables uniform o storage. El código debe ajustarse a la API, no a un shader genérico escrito para otro motor.

Empieza por cambiar la luz

Bloxdhub recomienda comenzar con bloxdTerrainLight, el hook que modifica la luz final y el color de los bloques sólidos. La función bloxdDefaultLight sirve como punto de partida: devuelve el resultado normal del juego, que luego se puede retocar sin reconstruir toda la estructura de iluminación.

Para una primera prueba, la guía propone calentar ligeramente la luz de todos los bloques, aumentando el canal rojo y reduciendo algo el azul. La idea es cambiar solo la parte que interesa y conservar el resto del cálculo del motor. La referencia Prism Shaders formula una recomendación similar: partir de las funciones predeterminadas, en lugar de reconstruir a mano los datos que el motor ya proporciona.

El hook adecuado depende del objetivo. Terrain trabaja con los bloques, excepto el agua y los modelos de bloque; los hooks de líquidos se ocupan del agua, mientras que los de modelos cubren elementos como plantas, objetos, jugadores y mobs. La lava se dibuja junto con los bloques, de modo que los hooks de terreno también pueden afectarla.

Para cambiar el color de una superficie antes de aplicar la luz existe bloxdTerrainSurface; para mover vértices del terreno, bloxdTerrainVertex. En el caso del agua, bloxdLiquidSurface altera color, transparencia y brillo, y bloxdLiquidVertex puede desplazar sus vértices para crear ondas. Elegir el hook correcto evita intentar modificar desde una función un elemento que no procesa.

Lava brillante y agua animada

La guía de Bloxdhub propone usar las propiedades del bloque para reconocer la lava que emite luz. Los flags disponibles indican características como opacidad, emisión, vegetación, tierra, arena o roca; se consultan como valores verdaderos o falsos. Las banderas describen el material, y un bloque puede tener varias a la vez.

El ejemplo de lava ajusta la emisión de las superficies que brillan y no son opacas. Así se busca que la lava conserve su resplandor incluso de noche. Como la lava forma parte del terreno y no del agua, el efecto se aplica mediante un hook de superficie del terreno, no con uno de líquidos.

Para las ondas, el ejemplo mueve verticalmente los vértices del agua con una función periódica basada en el tiempo y la posición. Pero hay una condición importante: los modos estrictos mantienen quieta la geometría. Bloxdhub exige que un hook de vértices esté dentro de la directiva #ifndef BLOXD_STRICT; de lo contrario, el pack puede quedar desactivado en partidas estrictas, que son mayoría según la guía.

Prueba el pack antes de compartirlo

Bloxd comprueba el pack en varias variantes antes de ejecutarlo: Bloxdhub habla de seis combinaciones entre modos normal y estricto, bloques, líquidos y modelos. Si una comprobación falla, el pack no carga; al entrar en una partida, el navegador también compila el código y puede aplicar una validación más estricta.

Entre los errores que señala la guía están modificar directamente una entrada del hook, construir manualmente estructuras que deberían salir de las funciones predeterminadas y usar funciones restringidas fuera del contexto permitido. También hay que poner entre paréntesis las operaciones que mezclen ciertos operadores matemáticos y de bits: el validador de Bloxd puede aceptarlas aunque el navegador las rechace.

Crea tu primer shader para Bloxd.io: archivos, luz y agua
Imagen generada con IA

La documentación comunitaria no oficial recomienda probar primero en una partida permisiva y después en una estricta. Su guía rápida indica que, al seleccionar el pack, puede aparecer el estado “Ready. Reload the page to use it.”; tras recargar la página, “Ready to use” indica que está listo. Si aparecen errores con archivo, línea y variante, hay que corregirlos y volver a cargar.

Para cargarlo, Bloxdhub indica que hay que abrir Ajustes, entrar en Shader Pack y elegir el ZIP con Chrome o Edge actuales, que son los navegadores mencionados para WebGPU. La guía rápida no oficial añade que cargar una carpeta directamente solo está disponible en navegadores de escritorio. El renderizador WebGPU es un requisito: los packs no funcionan con el renderizador anterior.

El Workshop de Bloxdhub valida el archivo y puede rechazar packs que no funcionen, que dejen el mundo negro o que no produzcan cambios. También genera imágenes de comparación antes y después, además de primeros planos y vistas del agua, el atardecer y la noche. La guía recomienda subir allí el ZIP terminado, en la sección Shader Packs.

API 5 y compatibilidad con packs antiguos

Bloxdhub advierte que la versión requerida es API 5: los packs creados para versiones anteriores dejan de cargar. La documentación no oficial coincide en que las versiones 1 a 4 se rechazan al cargarlas; añade que los packs guardados pueden quedar inactivos sin aviso. Bloxdhub señala que, al subir un pack antiguo al Workshop, este ofrece actualizarlo.

Los cambios de versión afectan a nombres y datos de las funciones. En API 5, por ejemplo, los flags de los bloques se reciben como valores verdaderos o falsos; también se sustituyó una directiva de iluminación por la función bloxdLit(), y en agua solo se ejecutan los hooks de líquidos. La versión 5 añade hooks para modelos, incluidos plantas, objetos, jugadores y mobs.

La historia de compatibilidad importa sobre todo si se parte de un pack existente. Bloxdhub también enumera cambios de API 4, como el renombrado de funciones relacionadas con la posición de los bloques y la niebla, y cambios de API 3 en las funciones de tiempo y desplazamiento. Para quien empieza desde cero, la referencia práctica es mantener apiVersion en 5 y comprobar que el pack carga en el juego y en el Workshop.

La documentación comunitaria no oficial y Prism Shaders amplían la lista de capacidades con lectura de texturas existentes y efectos específicos para modelos; también describen límites como la ausencia de postprocesado y de reflejos reales. Para una primera creación, no hace falta cubrir ese catálogo: basta con elegir un efecto concreto, modificar el hook correspondiente y comprobar que el ZIP supera las pruebas de Bloxd.

Fuentes: Bloxdhub, Bloxd.io Shader Pack Documentation (unofficial), Bloxd.io Shader Pack Documentation (unofficial), Bloxd.io Shader Pack Documentation (unofficial), Bloxd.io Prism Shaders