Sviluppo HTML5

Defold supporta la creazione di giochi per la piattaforma HTML5 tramite il normale menu di creazione dei bundle, come per le altre piattaforme. Inoltre, il gioco risultante viene incorporato in una normale pagina HTML, il cui aspetto può essere personalizzato tramite un semplice sistema di modelli.

Il file game.project contiene le impostazioni specifiche per HTML5:

Dimensione dell’heap

Il supporto HTML5 di Defold si basa su Emscripten (vedi http://en.wikipedia.org/wiki/Emscripten). In breve, crea un’area di memoria isolata per l’heap in cui opera l’applicazione. Per impostazione predefinita, il motore alloca una quantità abbondante di memoria (256MB), che dovrebbe essere più che sufficiente per un gioco tipico. Durante l’ottimizzazione, puoi scegliere di usare un valore inferiore. Per farlo, segui questi passaggi:

1. Imposta heap_size sul valore desiderato, espresso in megabyte.
2. Crea il tuo bundle HTML5 (vedi sotto)

Test di una build HTML5

Per eseguire i test, una build HTML5 richiede un server HTTP. Defold ne crea uno per te se scegli Project ▸ Build HTML5.

Se vuoi testare il tuo bundle, caricalo sul tuo server HTTP remoto oppure crea un server locale, ad esempio usando Python nella cartella del bundle. Python 2:

python -m SimpleHTTPServer

Python 3:

python -m http.server

oppure

python3 -m http.server

Creazione di un bundle HTML5

Creare contenuti HTML5 con Defold è semplice e segue la stessa procedura delle altre piattaforme supportate: seleziona Project ▸ Bundle... ▸ HTML5 Application... dal menu:

I bundle HTML5 supportano due architetture WebAssembly:

• wasm-web - il normale motore WebAssembly, senza thread.
• wasm_pthread-web - un motore WebAssembly che può utilizzare i thread.

Puoi includere una delle due architetture oppure entrambe. Quando sono incluse entrambe, il caricatore seleziona wasm_pthread-web se il browser e l’ambiente di hosting lo supportano, altrimenti utilizza wasm-web. Consulta il manuale di Bob per i nomi canonici delle piattaforme di destinazione.

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

I bundle HTML5 di Defold richiedono un browser moderno con supporto WebAssembly. Internet Explorer 11 non è supportato.

Quando fai clic sul pulsante Create bundle, ti verrà chiesto di selezionare una cartella in cui creare l’applicazione. Al termine dell’esportazione, troverai tutti i file necessari per eseguirla.

Problemi noti e limitazioni

• Hot Reload - L’hot reload non funziona nelle build HTML5. Per ricevere aggiornamenti dall’editor, le applicazioni Defold devono eseguire un proprio piccolo server web, cosa che non è possibile in una build HTML5.
• Chrome
  • Build di debug lente - Nelle build di debug per HTML5, verifichiamo tutte le chiamate grafiche WebGL per rilevare errori. Purtroppo, questa operazione è molto lenta durante i test in Chrome. Puoi disabilitarla impostando il campo Engine Arguments di game.project su --verify-graphics-calls=false.
• Supporto dei gamepad - Consulta la documentazione dei gamepad per le considerazioni specifiche e i passaggi che potrebbero essere necessari su HTML5.

Personalizzazione di un bundle HTML5

Quando generi una versione HTML5 del tuo gioco, Defold fornisce una pagina web predefinita. Questa fa riferimento a risorse di stile e script che determinano come viene presentato il gioco.

A ogni esportazione dell’applicazione, questi contenuti vengono ricreati. Se desideri personalizzare uno di questi elementi, devi modificare le impostazioni del progetto. Per farlo, apri game.project nell’editor Defold e scorri fino alla sezione html5:

Puoi trovare maggiori informazioni su ciascuna opzione nel manuale delle impostazioni del progetto.

In game.project puoi disattivare il pulsante Fullscreen e il link Made with Defold. Defold fornisce un tema scuro e uno chiaro per index.html. Il tema chiaro è quello predefinito, ma puoi cambiarlo modificando il file Custom CSS. Nel campo Scale Mode puoi inoltre scegliere tra quattro modalità di ridimensionamento predefinite.

Downscale Fit e Fit

Nella modalità Fit, il canvas viene ridimensionato per mostrare l’intero canvas del gioco sullo schermo mantenendo le proporzioni originali. L’unica differenza di Downscale Fit è che il ridimensionamento avviene solo se le dimensioni interne della pagina web sono inferiori a quelle del canvas originale del gioco; il canvas non viene ingrandito quando la pagina web è più grande.

Stretch

Nella modalità Stretch, il canvas viene ridimensionato per riempire completamente lo spazio interno della pagina web.

No Scale

Con la modalità No Scale, le dimensioni del canvas sono esattamente quelle definite nel file game.project, nella sezione [display].

Token

Per creare il file index.html utilizziamo il linguaggio di modelli Mustache. Durante la creazione di una build o di un bundle, i file HTML e CSS vengono elaborati da un compilatore in grado di sostituire determinati token con valori che dipendono dalle impostazioni del progetto. Questi token sono sempre racchiusi tra doppie o triple parentesi graffe ({{TOKEN}} o {{{TOKEN}}}), a seconda che le sequenze di caratteri debbano essere sottoposte a escape oppure no. Questa funzionalità può essere utile se modifichi spesso le impostazioni del progetto o se intendi riutilizzare il materiale in altri progetti.

Qualsiasi impostazione di game.project può essere usata come token. Ad esempio, se vuoi usare il valore Width della sezione Display:

Apri game.project come testo e controlla [section_name] e il nome del campo che vuoi usare. Puoi quindi utilizzarlo come token: {{section_name.field}} o {{{section_name.field}}}.

Ad esempio, nel codice JavaScript del modello HTML:

function doSomething() {
    var x = {{display.width}};
    // ...
}

Sono disponibili anche i seguenti token personalizzati:

DEFOLD_SPLASH_IMAGE

Inserisce il nome del file dell’immagine iniziale oppure false se html5.splash_image in game.project è vuoto

{{#DEFOLD_SPLASH_IMAGE}}
		background-image: url("{{DEFOLD_SPLASH_IMAGE}}");
{{/DEFOLD_SPLASH_IMAGE}}

exe-name

Il nome del progetto senza simboli non consentiti

DEFOLD_CUSTOM_CSS_INLINE

Il punto in cui viene inserito direttamente il contenuto del file CSS specificato nelle impostazioni di game.project.

<style>
{{{DEFOLD_CUSTOM_CSS_INLINE}}}
</style>

DEFOLD_SCALE_MODE_IS_DOWNSCALE_FIT

Questo token è true se html5.scale_mode è Downscale Fit.

DEFOLD_SCALE_MODE_IS_FIT

Questo token è true se html5.scale_mode è Fit.

DEFOLD_SCALE_MODE_IS_NO_SCALE

Questo token è true se html5.scale_mode è No Scale.

DEFOLD_SCALE_MODE_IS_STRETCH

Questo token è true se html5.scale_mode è Stretch.

DEFOLD_HEAP_SIZE

La dimensione dell’heap specificata in game.project con html5.heap_size, convertita in byte.

DEFOLD_ENGINE_ARGUMENTS

Gli argomenti del motore specificati in game.project con html5.engine_arguments, separati dal simbolo ,.

build-timestamp

Il timestamp della build corrente in secondi.

Parametri aggiuntivi

Se crei un modello personalizzato, puoi modificare i parametri del caricatore del motore assegnando valori nell’oggetto globale CUSTOM_PARAMETERS. Il modello integrato fornisce un blocco <script id="engine-setup"> intenzionalmente vuoto per queste personalizzazioni.

Ad esempio:

    <script id="engine-setup" type="text/javascript">
        CUSTOM_PARAMETERS.disable_context_menu = false;
        CUSTOM_PARAMETERS.unsupported_webgl_callback = function() {
            console.log("Oh-oh. WebGL not supported...");
        };
    </script>

CUSTOM_PARAMETERS può contenere, tra gli altri, i seguenti campi:

'archive_location_filter':
    Filter function that will run for each archive path.

'unsupported_webgl_callback':
    Function that is called if WebGL is not supported.

'engine_arguments':
    List of arguments (strings) that will be passed to the engine.

'custom_heap_size':
    Number of bytes specifying the memory heap size.

'disable_context_menu':
    Disables the right-click context menu on the canvas element if true.

'retry_time':
    Pause in seconds before retry file loading after error.

'retry_count':
    How many attempts we do when trying to download a file.

'can_not_download_file_callback':
    Function that is called if you can't download file after 'retry_count' attempts.

'resize_window_callback':
    Function that is called when resize/orientationchanges/focus events happened

'start_success':
    Function that is called just before main is called upon successful load.

'update_progress':
    Function that is called as progress is updated. Parameter progress is updated 0-100.

Operazioni sui file in HTML5

Le build HTML5 supportano operazioni sui file come sys.save(), sys.load() e io.open(), ma la gestione interna di queste operazioni è diversa rispetto alle altre piattaforme. Quando JavaScript viene eseguito in un browser, non esiste un vero e proprio concetto di file system e l’accesso ai file locali è bloccato per motivi di sicurezza. Emscripten (e quindi Defold) usa invece IndexedDB, un database interno al browser che permette di memorizzare dati in modo persistente, per creare un file system virtuale nel browser. La differenza importante rispetto all’accesso al file system sulle altre piattaforme è che può esserci un leggero ritardo tra la scrittura in un file e l’effettiva memorizzazione della modifica nel database. La console per sviluppatori del browser consente generalmente di ispezionare il contenuto di IndexedDB.

Passaggio di argomenti a un gioco HTML5

A volte è necessario fornire argomenti aggiuntivi a un gioco prima o durante il suo avvio. Potrebbe trattarsi, ad esempio, di un ID utente, di un token di sessione o del livello da caricare all’avvio del gioco. Puoi farlo in diversi modi, alcuni dei quali sono descritti qui.

Argomenti del motore

Puoi specificare argomenti aggiuntivi del motore durante la sua configurazione e il suo caricamento. Questi argomenti possono essere recuperati durante l’esecuzione tramite sys.get_config_string(). Assegna gli argomenti direttamente a CUSTOM_PARAMETERS.engine_arguments nel blocco engine-setup di index.html:

    <script id="engine-setup" type="text/javascript">
        CUSTOM_PARAMETERS.engine_arguments = [
            "--config=example.foo1=bar1",
            "--config=example.foo2=bar2"
        ];
    </script>

L’assegnazione di un nuovo array sostituisce tutti gli argomenti del motore configurati in game.project. Per conservare questi argomenti e aggiungerne un altro, usa invece CUSTOM_PARAMETERS.engine_arguments.push("--config=example.foo3=bar3").

Puoi anche aggiungere --config=example.foo1=bar1, --config=example.foo2=bar2 al campo Engine Arguments nella sezione HTML5 di game.project. I valori separati da virgole vengono aggiunti a CUSTOM_PARAMETERS.engine_arguments nel file dmloader.js generato.

Durante l’esecuzione, puoi ottenere i valori in questo modo:

local foo1 = sys.get_config_string("example.foo1")
local foo2 = sys.get_config_string("example.foo2")
print(foo1) -- bar1
print(foo2) -- bar2

Argomenti di query nell’URL

Puoi passare argomenti come parametri di query nell’URL della pagina e leggerli durante l’esecuzione:

https://www.mygame.com/index.html?foo1=bar1&foo2=bar2

local url = html5.run("window.location")
print(url)

Una funzione ausiliaria completa per ottenere tutti i parametri di query come tabella Lua:

local function get_query_parameters()
    local url = html5.run("window.location")
    -- get the query part of the url (the bit after ?)
    local query = url:match(".*?(.*)")
    if not query then
        return {}
    end

    local params = {}
    -- iterate over all key value pairs
    for kvp in query:gmatch("([^&]+)") do
        local key, value = kvp:match("(.+)=(.+)")
        params[key] = value
    end
    return params
end

function init(self)
    local params = get_query_parameters()
    print(params.foo1) -- bar1
end

Ottimizzazioni

I giochi HTML5 hanno generalmente requisiti rigorosi in termini di dimensioni del download iniziale, tempo di avvio e utilizzo della memoria, affinché si carichino rapidamente e funzionino bene anche su dispositivi poco potenti e con connessioni Internet lente. Per ottimizzare un gioco HTML5, si consiglia di concentrarsi sui seguenti aspetti:

• Utilizzo della memoria
• Dimensioni del motore
• Dimensioni del gioco

FAQ

D: Perché la mia applicazione HTML5 si blocca alla schermata iniziale in Chrome?

R: In alcuni casi non è possibile eseguire un gioco nel browser direttamente dal file system locale. Quando lo avvii dall’editor, il gioco viene servito da un server web locale. Puoi usare, per esempio, SimpleHTTPServer di Python:

$ python -m SimpleHTTPServer [port]

D: Perché il mio gioco si arresta con l’errore “Unexpected data size” durante il caricamento?

R: Questo accade solitamente quando usi Windows, crei una build e la aggiungi a un commit Git. Se la configurazione delle terminazioni di riga in Git è errata, Git le modifica, cambiando così anche la dimensione dei dati. Segui queste istruzioni per risolvere il problema: https://docs.github.com/en/free-pro-team@latest/github/using-git/configuring-git-to-handle-line-endings