Cómo exportar un juego de Godot 4 a la web (HTML5 e itch.io)

Godot exporta a la web como HTML5 y WebAssembly, lo que significa que tu juego se ejecuta en una pestaña del navegador sin descargas ni plugins. Es la forma más rápida de poner una versión jugable frente a alguien. Pegas un enlace, hacen clic y juegan.

"Exportar a la web" son dos trabajos, no uno. Generar los archivos toma más o menos un minuto. Lograr que esos archivos funcionen en un navegador es donde la gente se topa con una pantalla negra, normalmente por la forma en que se sirven los archivos o porque una opción de exportación activó sin avisar un requisito que el alojamiento no puede cumplir. Esta guía cubre ambas mitades, la configuración exacta y los errores detrás de la mayoría de las exportaciones fallidas.

Aplica a Godot 4.3 y versiones posteriores. Las versiones 4.x anteriores siempre usaban una compilación con hilos, así que si todavía estás en 4.0, 4.1 o 4.2, lee con atención la sección sobre cabeceras o actualiza el editor.

{/* IMAGE: The Godot Export dialog open with a Web preset selected, the Export Project button highlighted. 1200x675 editor screenshot. */}

Qué produce realmente la "exportación web"

Cuando exportas, Godot no crea un solo archivo. Escribe una pequeña carpeta de archivos estáticos.

• index.html es la página que carga todo. Es lo que abre el navegador.
• Un archivo .wasm es el propio motor de Godot, compilado a WebAssembly. Es la pieza más grande.
• Un archivo .pck contiene los datos de tu juego, es decir, escenas, scripts y recursos empaquetados juntos.
• Un archivo .js es el código de carga que conecta el motor con la página.
• A veces un .audio.worklet.js y, en las compilaciones con hilos, archivos de worker adicionales.

Todos deben estar juntos y servirse por HTTP. No puedes hacer doble clic en index.html y esperar que funcione, y eso es lo primero que confunde a la gente.

Paso 1. Instala las plantillas de exportación

Godot distribuye el editor y las plantillas de exportación por separado. Las plantillas son los binarios precompilados del motor para cada plataforma, incluida la compilación WebAssembly para el navegador. Una instalación nueva no las trae.

Ve a Editor y luego a Manage Export Templates (administrar plantillas de exportación), y haz clic en Download and Install. Esto descarga las plantillas para la versión exacta de tu motor.

Las plantillas deben coincidir exactamente con la versión de tu editor. Un editor 4.4 no puede exportar con plantillas 4.3, ni al revés. Esa diferencia de versiones es una de las causas más comunes de una compilación web rota. Cada vez que actualices el editor, vuelve a instalar las plantillas.

Paso 2. Agrega un preset de exportación Web

Abre Project y luego Export. Haz clic en Add y elige Web.

Los valores predeterminados son razonables. Tres grupos de opciones importan para la web.

• Variant, Thread Support. Desactivado por defecto desde Godot 4.3. Déjalo así, a menos que hayas medido una necesidad real de hilos. Una compilación de un solo hilo funciona en cualquier alojamiento estático y dentro de iframes en portales de juegos. Activarlo requiere las dos cabeceras Cross-Origin que se describen en el paso 4.
• Variant, Extensions Support. Solo hace falta si tu proyecto usa GDExtension. También requiere las cabeceras Cross-Origin, y cada extensión nativa necesita su propia compilación web.
• VRAM Texture Compression. "For Desktop" está activado por defecto y "For Mobile" está desactivado. Activar ambos hace que la exportación pese más pero sea más compatible, lo que importa si esperas jugadores en el celular, porque los teléfonos por lo general no admiten los formatos de textura de escritorio.

Deja Head Include y el shell HTML personalizado vacíos, a menos que tengas una razón para cambiarlos. El shell predeterminado se encarga de la carga y de la barra de progreso.

Paso 3. Exporta el proyecto

Elige una carpeta de destino. Crea una vacía con un nombre como web-build para que los archivos generados no se mezclen con nada más.

Nombra el archivo principal index.html, no con el nombre de tu juego. La mayoría de los alojamientos, incluido itch.io, buscan un index.html como punto de entrada. Si lo llamas mygame.html, el alojamiento no lo encontrará.

Haz clic en Export Project. En unos segundos la carpeta se llena con los archivos de la lista anterior.

{/* IMAGE: A file explorer showing the exported web-build folder contents: index.html, .wasm, .pck, .js files. 1000x500. */}

Paso 4. Cuándo necesitas las cabeceras Cross-Origin

La mayoría de los tutoriales antiguos dicen que toda compilación web de Godot 4 necesita cabeceras especiales. Eso era cierto antes de 4.3. Hoy depende de dos casillas.

Una compilación con Thread Support o Extensions Support activado usa SharedArrayBuffer, y los navegadores solo lo permiten cuando la página se sirve con estas dos cabeceras de respuesta.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Sin ellas el motor no puede arrancar, y la consola muestra un error que menciona SharedArrayBuffer o crossOriginIsolated. Estas cabeceras no se configuran en Godot. Se configuran en lo que sea que sirva los archivos.

Una compilación con ambas opciones desactivadas, que es la opción predeterminada, no necesita ninguna de las dos cabeceras. Por eso la exportación de un solo hilo es la opción correcta para itch.io, los portales de juegos y el alojamiento estático simple. Los hilos pueden mejorar el rendimiento en juegos pesados, pero te cuestan flexibilidad de alojamiento y compatibilidad al incrustar el juego.

Paso 5. Pruébalo en local antes de subirlo

Nunca depures una exportación web subiéndola y recargando la página. Pruébala primero en tu propia máquina.

La comprobación más rápida es el despliegue de un clic (one-click deploy) del editor. En cuanto existe un preset Web, aparece un icono de navegador en la esquina superior derecha del editor. Al hacer clic, inicia un servidor web local, exporta el proyecto y lo abre en tu navegador predeterminado. Ese servidor envía las cabeceras Cross-Origin, así que también ejecuta compilaciones con hilos.

Para una compilación que ya exportaste, cualquier servidor local funciona si Thread Support y Extensions Support están desactivados. Con Python instalado, ejecuta python -m http.server 8000 dentro de la carpeta web-build y abre http://localhost:8000.

Para una compilación con hilos, sírvela con ambas cabeceras. Guarda esto como serve.py dentro de la carpeta.

import http.server, socketserver

class Handler(http.server.SimpleHTTPRequestHandler):
    def end_headers(self):
        self.send_header("Cross-Origin-Opener-Policy", "same-origin")
        self.send_header("Cross-Origin-Embedder-Policy", "require-corp")
        super().end_headers()

with socketserver.TCPServer(("", 8000), Handler) as httpd:
    print("Serving on http://localhost:8000")
    httpd.serve_forever()

Ejecuta python serve.py y abre http://localhost:8000. Si el juego carga aquí, la exportación es correcta y cualquier problema que quede es de configuración del alojamiento.

Paso 6. Aloja el juego

itch.io (lo más sencillo, gratis)

Es la opción recomendada para compartir y para game jams.

1. Comprime el contenido de la carpeta web-build, no la carpeta padre, para que index.html quede en el nivel superior del zip.
2. En itch.io, crea un proyecto nuevo y configura Kind of project (tipo de proyecto) como HTML.
3. Sube el zip y marca This file will be played in the browser (este archivo se jugará en el navegador).
4. En las opciones de incrustación, define un tamaño de viewport que coincida con la resolución de tu juego.

itch.io acepta hasta 500 MB de contenido descomprimido, 200 MB para un solo archivo y 1.000 archivos. Una compilación de un solo hilo no necesita nada más. Para una compilación con hilos, itch.io ofrece la casilla SharedArrayBuffer support en las opciones del marco de incrustación, anunciada como una función experimental que puede romper partes de la página, así que prueba la página publicada en más de un navegador.

Netlify, Vercel, GitHub Pages o tu propio servidor

Una compilación de un solo hilo funciona tal cual en cualquier alojamiento estático, incluido GitHub Pages sin configuración extra. Asegúrate de que el servidor envíe los archivos .wasm con el tipo de contenido application/wasm y los comprima, ya que WebAssembly se reduce a cerca de una cuarta parte de su tamaño con gzip.

Para una compilación con hilos, el alojamiento debe enviar las dos cabeceras. En Netlify, agrega un archivo _headers a la raíz del despliegue.

/*
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp

En Vercel, configura las mismas dos cabeceras en vercel.json dentro de una regla headers. En nginx o Apache, agrégalas al bloque location. GitHub Pages no puede enviar cabeceras personalizadas, así que ahí las compilaciones con hilos necesitan un service worker como solución alternativa, por ejemplo coi-serviceworker, que no todos los navegadores respetan. Si no necesitas hilos, la respuesta más simple es desactivar Thread Support.

Cómo arreglar una pantalla negra, la lista de verificación

Si ves un canvas negro, abre la consola de desarrollador del navegador (presiona F12 y luego la pestaña Console) y lee el primer error en rojo. Revisa estos puntos en orden.

1. ¿Abriste el archivo directamente? Si la URL empieza con file://, sírvelo por HTTP.
2. ¿Aparece SharedArrayBuffer o crossOriginIsolated en el error? Thread Support o Extensions Support está activado y el alojamiento no envía las cabeceras. Desactiva ambas opciones y vuelve a exportar, o agrega las cabeceras en el alojamiento.
3. ¿El error menciona una versión o una plantilla que no se pudo cargar? Tus plantillas de exportación no coinciden con la versión de tu editor. Vuelve a instalarlas en Manage Export Templates.
4. ¿Es un proyecto en C#? Godot 4 no puede exportar proyectos en C# a la web. La compilación web necesita un proyecto en GDScript.
5. ¿El archivo .wasm se sirve con el tipo equivocado? Algunos alojamientos lo envían como una descarga genérica. Configura el tipo de contenido application/wasm.

La mayoría de las exportaciones web fallidas son uno de estos cinco casos.

Lo que no funciona igual en el navegador

Una compilación web no es la versión de escritorio con una URL. Algunas cosas se comportan distinto.

• Los datos guardados van al IndexedDB del navegador, no a una carpeta en el disco, y los jugadores deben permitir el almacenamiento del sitio para que se conserven. Dentro de un iframe en un portal eso puede requerir almacenamiento de terceros, así que prueba el guardado en el alojamiento que vayas a usar.
• El audio solo empieza después de que el jugador hace clic, toca la pantalla o presiona una tecla, porque los navegadores bloquean la reproducción automática. Una pantalla de "haz clic para empezar" lo resuelve.
• Los plugins nativos (bibliotecas GDExtension compiladas para escritorio) no cargan, a menos que incluyan una compilación web y Extensions Support esté activado.
• C# no se exporta a la web en Godot 4.
• El renderizado usa el renderizador Compatibility (WebGL 2) en la web, así que un proyecto creado con Forward+ o Mobile se ve distinto. Efectos como SDFGI, la niebla volumétrica y los reflejos en espacio de pantalla no se renderizan. Crea en Compatibility desde el principio los juegos pensados para la web, para que lo que ves en el editor sea lo que llega al jugador. La plantilla web propia de Summer es distinta, porque usa WebGPU con Forward+ o Mobile.
• El tamaño de carga importa más que en cualquier otro lugar. El jugador descarga el motor, el paquete de datos y todos los recursos antes de que empiece el juego. La guía para desarrolladores de Poki señala que los jugadores suelen irse si la carga tarda más de diez segundos, así que mantén pequeña la primera descarga.

Summer Engine y la exportación web

Summer Engine es un motor de escritorio para macOS y Windows que conserva los flujos de trabajo de Godot 4, con una IA que crea escenas, scripts y recursos a partir de lenguaje natural. Genera versiones de escritorio de tu juego, que puedes vender en Steam o subir a itch.io como descarga, y también exporta compilaciones web.

Desde el motor 0.7, el editor incluye la plantilla de exportación web propia de Summer, que usa WebGPU con el renderizador Forward+ o Mobile. La exportación web funciona para proyectos en GDScript. Los proyectos que usan C# no pueden exportarse a la web, la misma limitación de Godot 4. La compilación web es un .zip estático estándar con index.html en la raíz. La publicas en Summer Games, donde la gente la juega en el navegador. Summer Games también acepta la exportación web estándar de Godot descrita arriba, hecha con el renderizador Compatibility. Los agentes pueden hacer ambos pasos con las herramientas MCP summer_export_game (destino web) y después summer_publish_build.

Si quieres empezar un juego en Summer hoy, parte de una plantilla que ya tenga el movimiento y la cámara configurados, describe las mecánicas que quieres agregar encima y exporta una compilación cuando se juegue bien.