Exportar para la Web¶
Ver también
This page describes how to export a Godot project to HTML5. If you're looking to compile editor or export template binaries from source instead, read Compiling for the 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
Hay errores importantes al ejecutar proyectos HTML5 en iOS <https://github.com/godotengine/godot/issues?q=is:issue+is:open+label:platform:html5+ios> __ (independientemente del navegador). Recomendamos utilizar la funcionalidad de exportación nativa de iOS en su lugar, ya que también dará como resultado un mejor rendimiento.
Versión de WebGL¶
Dependiendo de su elección de renderizador, Godot puede apuntar a WebGL 1.0 (* GLES2 ) o WebGL 2.0 ( GLES3 *).
WebGL 1.0 es la opción recomendada si desea que su proyecto sea compatible con todos los navegadores con el mejor rendimiento.
El renderizador GLES3 de Godot apunta a dispositivos de gama alta, y el rendimiento con WebGL 2.0 puede ser insatisfactorio. Algunas funciones tampoco son compatibles con WebGL 2.0 específicamente.
Además, aunque la mayoría de los navegadores son compatibles con WebGL 2.0, este todavía no es el caso de Safari. La compatibilidad con WebGL 2.0 viene en Safari 15 para macOS y aún no está disponible para ningún navegador iOS (todos basados en WebKit como Safari). Consulte ¿Puedo usar WebGL 2.0 <https://caniuse.com/webgl2> __ para obtener más detalles.
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.
Puede elegir el ** Tipo de exportación ** para seleccionar qué funciones estarán disponibles:
Regular: is the most compatible across browsers, will not support threads, nor GDNative.
Hilos: requerirá que el navegador admita SharedArrayBuffer. Consulte ¿Puedo usar SharedArrayBuffer <https://caniuse.com/sharedarraybuffer> __ para obtener más detalles.
GDNative: enables GDNative support but makes the binary bigger and slower to load.
Si tiene previsto utilizar Compresión de la memoria RAM asegúrese de que Compresión de la textura de la memoria RAM está activada para las plataformas a las que se dirige (si activa tanto Para escritorio como Para móvil, la exportación será mayor, pero más compatible).
Si se da una ruta a un archivo HTML shell personalizado, se utilizará en lugar de la página HTML predeterminada. Ver Custom HTML page for Web export.
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.
Importante
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 that HTML file will be lost in future exports. To customize the generated file, use the Custom HTML shell option.
Advertencia
Export types other than Regular are not yet supported by the C# version.
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.
Importante
Los proveedores de navegadores están haciendo más y más funcionalidades solo disponibles en contextos seguros <https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts> _, esto significa que tales características solo están disponibles si la página web se sirve a través de una conexión HTTPS segura (localhost generalmente está exento de tal requisito).
Truco
Revisa la lista de issues abiertos sobre HTML5 en Github para ver si la funcionalidad que te interesa ya tiene un problema reportado. Si no, inicia uno para hacernos llegar tu interés.
Background processing¶
The project will be paused by the browser when the tab is no longer the active
tab in the user's browser. This means functions such as _process()
and
_physics_process()
will no longer run until the tab is made active again by
the user (by switching back to the tab). This can cause networked games to
disconnect if the user switches tabs for a long duration.
This limitation does not apply to unfocused browser windows. Therefore, on the user's side, this can be worked around by running the project in a separate window instead of a separate tab.
Hilos¶
Como se mencionó arriba el multi-threading sólo está disponible si se establece el Tipo de Exportación apropiado y el soporte para ello en los navegadores es todavía limitado.
Advertencia
Requires a secure context. Browsers also require that the web page is served with specific cross-origin isolation headers.
GDNative¶
Como se mencionó arriba GDNative sólo está disponible si se establece el Tipo de exportación apropiado.
La exportación también copiará los archivos requeridos de GDNative `` .wasm `` en la carpeta de salida (y debe cargarse en su servidor junto con su juego).
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 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.
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.
Advertencia
El acceso al micrófono requiere secure context.
Redes¶
Las redes de bajo nivel no se implementan debido a la falta de soporte en los navegadores.
Actualmente, solo están soportados: HTTP client <doc_http_client_class>, HTTP requests, WebSocket (client) y WebRTC.
Las clases HTTP también tienen 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
Portapapeles¶
La sincronización del portapapeles entre el motor (Godot) y el sistema operativo requiere de un navegador que soporte la Clipboard API, además, debido a la naturaleza de la API asíncrona, el portapapeles, podría no ser de confianza cuando se accede desde GDScript.
Advertencia
Requiere un: ref: secure context <doc_javascript_secure_contexts>.
Mandos de juego¶
Los Mandos no se detectarán hasta que se presione uno de sus botones. Los Mandos pueden tener un mapeo incorrecto dependiendo de la combinación de navegador / sistema operativo / mando, lamentablemente la API de Gamepad <https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API> `__ no proporcionan una forma fiable de detectar la información del mando necesaria para reasignarlos según el modelo / proveedor / sistema operativo debido a consideraciones de privacidad.
Advertencia
Requiere un: ref: secure context <doc_javascript_secure_contexts>.
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.
Limitaciones del lenguaje de shaders¶
Cuando se exporta un proyecto GLES2 a HTML5, se utiliza WebGL 1.0. WebGL 1.0 no soporta bucles dinámicos, así que los shaders que los usan no funcionarán allí.
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 Custom HTML page for Web export.
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.
Host que proveen compresión sobre la marcha: GitHub Pages (gzip)
Host que no proveen compresión sobre la marcha: itch.io, GitLab Pages (soporta precompresión manual con gzip)
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 floatJavaScript
boolean
se devuelve como GDScript boolJavaScript
string
se devuelve como GDScript StringJavaScript
ArrayBuffer
,TypedArray
yDataView
se devuelven como GDScript 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 pueden ser: ref:built <doc_compiling_for_web> sin soporte para el singleton para mejorar la seguridad. Con tales plantillas, y en plataformas distintas de HTML5, llamar a JavaScript.eval
también devolverá null
. La disponibilidad del singleton se puede verificar con el 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 útiles 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 espacio de nombres global:
func my_func4():
# execute in global execution context,
# thus adding a new JavaScript global variable `SomeGlobal`
JavaScript.eval("var SomeGlobal = {};", true)