Exportar para la Web

Exportar a HTML5 permite publicar juegos hechos en Godot Engine en el navegador. Esto requiere soporte para las tecnologías recientes WebAssembly y WebGL 2.0 en el navegador del usuario.

Importante

Usa la consola de desarrollo integrada en el navegador, usualmente se abre presionando F12, para ver información de depuración como JavaScript, el motor, y errores de WebGL.

Atención

Many browsers, including Firefox and Chromium-based browsers, will not load exported projects when opened locally per file:// protocol. To get around this, use a local server.

Truco

Python ofrece un método fácil de comenzar un servidor local. Usa python -m SimpleHTTPServer con Python 2 o python -m http.server con Python 3, ejecutará el servidor en el directorio de trabajo actual, accesible en http://localhost:8000.

WebGL 2

Until the OpenGL ES 3 renderer is removed from Godot in favor of Vulkan, HTML5 export uses WebGL 2 when the GLES3 option is selected.

Advertencia

El uso de WebGL 2 no es recomendado dado a que se espera sea removido de Godot sin un remplazo.

WebGL2 no está soportado en todos los navegadores. Firefox y Chromium (Chrome, Opera) son los navegadores compatibles más populares, Safari y Edge aún no funcionan. En iOS, todos los navegadores están basados en WebKit (ej. Safari), por lo que tampoco funcionarán.

El renderizador WebGL 2 de Godot tiene problemas con el 3D y ha dejado de ser mantenido.

Limitaciones

Por razones de seguridad y privacidad, muchas de las funciones que funcionan sin esfuerzo en plataformas nativas son más complicadas en la plataforma web. A continuación hay una lista de limitaciones que debes tener en cuenta a la hora de portar un juego Godot a la web.

Uso de cookies para la persistencia de datos

Los usuarios deben permitir cookies (específicamente IndexedDB) si se desea la persistencia del sistema de archivos user://. Cuando se juega a un juego presentado en un iframe, también deben estar habilitadas las cookies de terceros. El modo de navegación de incógnito/privado también evita la persistencia.

El método OS.is_userfs_persistent() puede usarse para comprobar si el sistema de ficheros user:// es persistente, pero puede dar falsos positivos en algunos casos.

Captura de pantalla completa y ratón

Los navegadores no permiten ingresar a pantalla completa arbitrariamente. Lo mismo ocurre con capturar el cursor. En su lugar, estas acciones tienen que ocurrir como respuesta a un evento de entrada de JavaScript. En Godot, implica que se debe cambiar pantalla completa desde una llamada de entrada como _input o _unhandled_input. Consultando el singleton class_Input no será suficiente, el evento correspondiente debe estar actualmente activo.

Por la misma razón, la opción de proyecto a pantalla completa no funciona a menos que el motor sea lanzado desde un manejador de eventos de entrada válido. Esto requiere customizar la página HTML.

Reproducción automática de audio

Chrome restringe como las páginas web pueden reproducir sonido. Puede que sea necesario para el jugador hacer clic, tocar la pantalla o presionar un botón para habilitar el sonido.

Ver también

Google ofrece información adicional acerca de su política de reproducción automática de Web Audio.

class_HTTPClient y class_HTTPRequest

Las clases HTTP tiene varias restricciones en la plataforma HTML5:

  • No es posible acceder o cambiar el StreamPeer
  • El modo de hilos/bloqueo no está disponible
  • No se puede progresar más de una vez por fotograma, por lo que el sondeo en un bucle se congelará
  • No hay respuestas fragmentadas
  • La verificación del host no se puede deshabilitar
  • Sujeto a la política de mismo origen

El archivo exportado .html no debe ser reutilizado

Each project must generate their own HTML file. On export, several text placeholders are replaced in the generated HTML file specifically for the given export options. Any direct modifications to the generated HTML file will be lost in future exports. To customize the generated file, see Personalizando la página HTML de exportación a Web.

La pantalla de inicio no es mostrada

La página HTML por defecto no muestra la pantalla de inicio mientras se carga. Sin embargo, la imagen es exportada como un archivo PNG, así las páginas HTML customizadas pueden mostrarla.

Funcionalidad no implementada

La siguiente funcionalidad no está disponible actualmente en la plataforma HTML5:

  • Hilos
  • GDNative
  • C#
  • Sincronización del portapapeles entre el motor y el sistema operativo
  • Conexiones de red fuera de HTTPClient y class_WebSocketClient

Truco

Revisa la lista de issues abiertos sobre HTML5 en Github para ver si la funcionalidad que te interesa ya tiene uno abierto. Si no, inicia uno para hacernos llegar tu interés.

Entrega de archivos

Exportar para la web genera varios archivos para ser servidos desde un servidor web, incluyendo una página HTML por defecto para la presentación. Se puede utilizar un archivo HTML personalizado, visita Personalizando la página HTML de exportación a Web.

El archivo .html generado puede ser usado como DirectoryIndex en los servidores Apache y puede ser renombrado a e.g. index.html en cualquier momento, nunca dependerá de su nombre por defecto.

La página HTML dibujará el juego en el tamaño máximo dentro de la ventana del navegador. De esta manera se puede insertar en un <iframe> con el tamaño del juego, como es común en la mayoría de los sitios web de alojamiento de juegos.

Los otros archivos exportados se sirven tal cual, junto al archivo .html, sin cambios en los nombres. El archivo .wasm es un módulo binario de WebAssembly que implementa el motor. El archivo .pck es el paquete principal de Godot que contiene tu juego. El archivo .js contiene código de inicio y es usado por el archivo .html para acceder al motor. El archivo .png contiene la imagen de bienvenida al inicio. No se utiliza en la página HTML por defecto, pero se incluye para páginas HTML personalizadas.

El archivo .pck es binario, normalmente se entrega con el MIME-type application/octet-stream. El archivo .wasm se entrega como application/wasm.

Prudencia

Emitir el modulo WebAssembly (.wasm) con un tipo MIME diferente a application/wasm puede evitar algunas optimizaciones de arranque.

Se recomienda entregar los archivos con compresión del lado del servidor especialmente para los archivos .pck y .wasm, que suelen ser de gran tamaño. El módulo WebAssembly se comprime particularmente bien, hasta alrededor de un cuarto de su tamaño original con compresión gzip.

Opciones de exportación

Si hay disponible una plantilla de exportación web ejecutable, aparece un botón entre los botones Detener escena y Reproducir escena en el editor para abrir rápidamente el juego en el navegador predeterminado para realizar pruebas.

Si se da una ruta a un archivo HTML shell personalizado, se utilizará en lugar de la página HTML predeterminada. Ver Personalizando la página HTML de exportación a Web.

Head Include se agrega al elemento <head> de la página HTML generada. Esto permite, por ejemplo, cargar fuentes web y APIs JavaScript de terceros, incluir CSS o ejecutar código JavaScript.

Llamada a JavaScript desde script

En las desarrollos web, se implementa el singleton JavaScript. Ofrece un único método llamado eval que funciona de forma similar a la función JavaScript del mismo nombre. Toma una cadena como argumento y la ejecuta como código JavaScript. Esto permite interactuar con el navegador de formas que no son posibles con lenguajes de script integrados en Godot.

func my_func():
    JavaScript.eval("alert('Calling JavaScript per GDScript!');")

El valor de la última sentencia JavaScript es convertido a un valor GDScript y devuelto por eval() bajo ciertas circunstancias:

  • JavaScript number se devuelve como GDScript class_float
  • JavaScript boolean se devuelve como GDScript class_bool
  • JavaScript string se devuelve como GDScript class_String
  • JavaScript ArrayBuffer, TypedArray y DataView se devuelven como GDScript class_PoolByteArray
func my_func2():
    var js_return = JavaScript.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

Cualquier otro valor de JavaScript se devuelve como null.

Las plantillas de exportación HTML5 se pueden crear sin soporte para singleton. Con tales plantillas, y en plataformas que no sean HTML5, llamar `JavaScript.eval también devolverá null. La disponibilidad del singleton se puede verificar usando JavaScript feature tag:

func my_func3():
    if OS.has_feature('JavaScript'):
        JavaScript.eval("""
            console.log('The JavaScript singleton is available')
        """)
    else:
        print("The JavaScript singleton is NOT available")

Truco

Los strings multilinea de GDScript, rodeados por 3 comillas dobles """ como arriba en my_func3(), son utiles para mantener el código JavaScript más legible.

El método eval también acepta un segundo argumento booleano opcional, que especifica si se debe ejecutar el código en el contexto de ejecución global, por defecto false para evitar contaminar el namespace global:

func my_func4():
    # execute in global execution context,
    # thus adding a new JavaScript global variable `MyGlobal`
    JavaScript.eval("var SomeGlobal = {};", true)