Personalizando la página HTML de exportación a Web

En lugar de la página HTML que viene por defecto con las plantillas de exportación, también es posible personalizar la página HTML. Esto permite una personalización drástica de la presentación y comportamiento de la página web. La ruta de la página HTML personalizada está especificada en las opciones de exportación como Html/Custom Html Shell.

La página HTML por defecto está disponible en el repositorio de Godot Engine en /misc/dist/html/full-size.html. Algunos casos de uso simple donde es útil personalizar la página por defecto incluyen:

  • Cargar archivos de diferentes directorios
  • Cargar archivos .zip en lugar de .pck como paquete principal
  • Cargar archivos del motor desde un directorio distinto al paquete de datos principal
  • Adding a click-to-play button so games can be started in full-screen mode
  • Cargar archivos extra antes de que arranque el motor, así estarán disponibles en el sistema de archivos luego
  • Pasar argumentos de la línea de comandos, por ejemplo, -s para iniciar un script MainLoop

Otro ejemplo de páina HTML se encuentra disponible en /misc/dist/html/fixed-size.html. Esta página utiliza un canvas de tamaño fijo con un widget de salidas debajo. Sin embargo, la consola del navegador (F12) debe preferirse ya que puede mostrar información adicional como errores de WebGL.

Sustitución de parámetros

Cuando se exporta el juego, muchos placeholders en la página HTML son sustituidos por valores de acuerdo a la exportación:

Parámetros Sustituido por
$GODOT_BASENAME Nombre base de los archivos exportados sin sufijos, ej. game cuando se exporta game.html
$GODOT_DEBUG_ENABLED true si es de depuración, false en caso contrario
$GODOT_HEAD_INCLUDE Cadena personalizada para incluir antes del final del elemento HTML <head>

El arcivo HTML debe evaluar el archivo JavaScript $GODOT_BASENAME.js. Este archivo define un objeto global Engine usado al iniciar el motor, ver debajo para más detalles.

La imagen splash de inicio es exportada como $GODOT_BASENAME.png y puede ser usada en elementos como <img />.

$GODOT_DEBUG_ENABLED puede ser útil para, opcionalmente, mostrar salida de consola u otras herramientas de depuración.

$GODOT_HEAD_INCLUDE es sustituida con la cadena especificada por la opción de exportación Html/Head Include.

El objeto Engine

El objeto global JavaScript es definido por $GODOT_BASENAME.js y sirve como una interfaz para los procesos de inicio del motor.

La API está basada en «promesas» y requiere una comprensión básica de las mismas: Promises.

El objeto tiene sólo los siguientes métodos:

Engine.load(basePath)

Carga el motor desde la ruta indicada.

Argumentos:
  • basePath (string) – Base path of the engine to load.
Devuelve:

Una promesa de que resolverá una vez cargado el motor.

Engine.unload()

Unload the engine to free memory.

Esto es llamado automáticamente una vez que el motor ha comenzado a menos que sea deshabilitado explícitamente usando engine.setUnloadAfterInit().

Engine.isWebGLAvailable([majorVersion = 1])

Check whether WebGL is available.

Argumentos:
  • majorVersion (number) – The major WebGL version to check for. Defaults to 1 for WebGL 1.0.
Devuelve:

Devuelve true si la versión mayor de WebGL dada está disponible, false falso de otro modo.

Engine.setWebAssemblyFilenameExtension(extension)

When loading the engine, the filename extension of the WebAssembly module is assumed to be wasm. This function allows usage of an alternate extension.

Engine.setWebAssemblyFilenameExtension('dat');
// Load 'mygame.dat' as WebAssembly module.
Engine.load('mygame');

This is useful for outdated hosts that only accept uploads of files with certain filename extensions.

Argumentos:
  • extension (string) – Filename extension without preceding dot.

Nota

Depending on the host, using an alternate filename extension can prevent some start-up optimizations. This occurs when the file is delivered with a MIME-type other than application/wasm.

Comenzando una instancia de Engine

Engine() also acts a class:

class Engine()

An instance of the engine that can be started, usually a game.

Instantiate the class using the new operator:

var engine = new Engine();

This yields an Engine() instance, referred to as engine with a lower-case e from here.

Para iniciar esta instancia, el objeto global Engine debe ser cargado, luego, la instancia engine debe ser inicializada e iniciada.

engine.init([basePath])

Initialize the instance. The instance can then be started with one of the start functions, usually engine.startGame().

Argumentos:
  • basePath (string) – The base path to the engine, same as in Engine.load(). Must be passed only if the engine hasn’t been loaded yet.
Devuelve:

Devuelve una promesa de que resolverá una vez que el motor es cargado e inicializado.

engine.preloadFile(file[, path])

Esto carga un archivo para que esté disponible en el sistema de archivos una vez que la instancia es iniciada. Debe llamarse antes de iniciar la instancia.

Argumentos:
  • file – Si file es una cadena, el archivo será cargado desde una URL. Si file es un ArrayBuffer o una vista de uno, el buffer será usado como el contenido del archivo.
  • path (string) – Ruta en la cual el archivo está disponible. Es mandatorio si file no es una cadena. De otro modo, la ruta será derivada desde la URL del archivo cargado.
Devuelve:

Devuelve una promesa de que resolverá una vez que el archivo es precargado.

engine.start([arg1, arg2, ])

Comienza la instancia del motor, pasando la cadena indicada como argumento. Esto permite un gran control sobre cómo el motor es iniciado, pero usualmente los otros métodos cuyos nombres comienzan con engine.start son más simples y deben usarse en su lugar.

If the instance has not yet been initialized with engine.init(), it will be.

The engine must be loaded beforehand.

Requires that the engine has been loaded, and that a canvas can be found on the page.

Argumentos:
  • variadic (string) – Parámetros de la línea de comandos.
Devuelve:

Devuelve una promesa de que resolverá una vez que el motor ha iniciado.

engine.startGame(mainPack)

Initializes the engine if not yet initialized and starts the game with the main pack loaded from the passed URL.

Si el motor no está cargado todavía, la ruta base de la URL indicada será utilizada para cargar el motor.

This function ignores overrides of filenames and their extensions to start only the main pack passed as argument.

Argumentos:
  • mainPack (string) – Path to the main pack to start. Also used as base path to load the engine if not loaded already.
Devuelve:

Devuelve una promesa de que resolverá una vez que el juego ha arrancado.

Configurando comportamiento de inicio

Además de comenzar el engine, otros métodos de la instancia engine permite configurar el comportamiento:

engine.setUnloadAfterInit(enabled)

Specify whether the Engine will be unloaded automatically after the instance is initialized.

Esto libera memoria del navegador removiendo archivos cargados que no son necesarios una vez que la instancia es inicializada. Sin embargo, si más instancias de engine son iniciadas, Engine tendrá que ser cargado nuevamente.

Enabled by default.

Argumentos:
  • enabled (boolean) – true si el motor deberá ser eliminado de memoria después de inicializar, false en caso contrario.
engine.setCanvas(canvasElem)

Specify a canvas to use.

Por defecto, el primer elemento canvas de la página se utiliza para el renderizado.

Argumentos:
  • canvasElem (HTMLCanvasElement) – The canvas to use.
engine.setCanvasResizedOnStart(enabled)

Establece el canvas se redimensionará a la anchura y la altura especificadas en la configuración del proyecto al inicio.

Enabled by default.

Argumentos:
  • enabled (boolean) – true si el canvas debe redimensionarse al comenzar, false en caso contrario.
engine.setLocale(locale)

Por defecto, el motor tratará de adivinar la localización a usar desde el entorno JavaScript. Es usualemente preferible para usar una localización especificada por el usuario desde el lado del servidor, o al menos usará la localización solicitada en la cabecera HTTP Accept-Language. Este método permitirá especificar la cadena de localización personalizada.

For example, with PHP:

engine.setLocale(<?php echo Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']); ?>);
Argumentos:
  • locale (string) – Idioma.

Ver también

List of locales.

engine.setExecutableName(execName)

Specify the virtual filename of the executable.

A real executable file doesn’t exist for the HTML5 platform. However, a virtual filename is stored by the engine for compatibility with other platforms.

Por defecto, se usa el nombre base de los archivos del engine cargados. Este método permite especificar otro nombre.

This affects the output of OS.get_executable_path() and the automatically started main pack, ExecutableName.pck.

Argumentos:
  • execName (string) – Executable name.

Personalizando la presentación

Los siguientes métodos son usados para implementar la presentación:

engine.setProgressFunc(callback)

Set the callback for displaying download progress.

Argumentos:
  • callback (function) – Callback called once per frame with two number arguments: bytes loaded so far, and total bytes to load.
function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.setProgressFunc(printProgress);

Si el total es 0, no puede ser calculado. Posibles razones incluyen:

  • Los archivos son distribuidos con chunked compression del lado del servidor
  • Los archivos son distribuidos con compresión del lado del servidor en Chromium
  • Algunas descargas no han iniciado todavía (usualmente en servidores sin multi-threading)

Nota

For ease of use, the callback is only called once per frame, so that usage of requestAnimationFrame() is not necessary.

engine.setStdoutFunc(callback)

Specify the standard output stream callback.

Argumentos:
  • callback (function) – Callback function called with one argument, the string to print.
function printStdout(text) {
    console.log(text);
}
engine.setStdoutFunc(printStdout);

Este método debe ser usado solamente en páginas de depuración. El placeholder $GODOT_DEBUG_ENABLED puede ser usado para verificar esto.

Por defecto, se usa console.log().

engine.setStderrFunc(callback)

Specify the standard error stream callback.

Argumentos:
  • callback (function) – Callback function called with one argument, the string to print.
function printStderr(text) {
    console.warn("Error: " + text);
}
engine.setStderrFunc(printStderr);

Este método debe ser usado solamente en páginas de depuración. El placeholder $GODOT_DEBUG_ENABLED puede ser usado para verificar esto.

Por defecto, se usa console.warn().

Accediendo el módulo Emscripten

Si sabes lo que estás haciendo, puedes acceder al entorno de ejecución (módulo Emscripten) como engine.rtenv. Revisa la documentación oficial para información de cómo usarlo: https://kripken.github.io/emscripten-site/docs/api_reference/module.html