JavaScript Hot-Reload nella versione 1.3.0

La versione 1.3.0 di Wonderland Engine introduce un nuovo modo di gestire l’applicazione JavaScript/TypeScript nell’editor.

Il nuovo setup consente di ripristinare il supporto all’Hot Reload, ossia ricaricare il tuo JavaScript nel browser senza riavviare il motore e le sessioni VR.

Versioni precedenti alla 1.3.0 

In precedenza, l’editor generava un singolo bundle JavaScript, partendo da un singolo punto di ingresso (index.js):

js/index.js

 1import {loadRuntime} from '@wonderlandengine/api';
 2
 3/* wle:auto-imports:start */
 4import {MyComponent} from './js/my-component.js';
 5/* wle:auto-imports:end */
 6
 7const engine = await loadRuntime(...);
 8
 9/* wle:auto-register:start */
10engine.registerComponent(MyComponent);
11/* wle:auto-register:end */

Il bundle generato conteneva quindi le dipendenze importate, il codice di creazione del motore, così come i globali.

Nuova Architettura 

La nuova architettura separa il punto di ingresso dell’applicazione da quello della registrazione dei componenti:

• js/index.js: Contiene la registrazione dei componenti
• app.js: Contiene la creazione del motore, i globali, ecc…

js/index.js

 1// Punto di ingresso dei componenti
 2
 3/* wle:auto-imports:start */
 4import {MyComponent} from './js/my-component.js';
 5/* wle:auto-imports:end */
 6
 7export default function(engine) {
 8  /* wle:auto-register:start */
 9  engine.registerComponent(MyComponent);
10  /* wle:auto-register:end */
11}

app.js

1// Punto di ingresso dell'applicazione
2
3import {loadRuntime} from '@wonderlandengine/api';
4
5const engine = await loadRuntime(...);
6engine.loadMainScene('MyScene.bin');

Inoltre, il bundle dei componenti verrà scaricato e registrato automaticamente dalla chiamata engine.loadMainScene().

Se lo desideri, puoi importare manualmente i componenti e registrarli nell’applicazione, ma consulta prima la sezione Gotchas per evitare problemi comuni.

Impostazioni 

L’editor aveva un solo campo di configurazione per le impostazioni JavaScript:

Ora è duplicato per l’ingresso dell’applicazione e dei componenti:

L’impostazione output è usata per riferirsi al nome del file bundle nella cartella di distribuzione.

Quando si utilizza un comando npm personalizzato, questo valore deve essere impostato sul nome del file generato.

Migrazione 

Aprendo un progetto pre-1.3, il processo di migrazione disabiliterà il bundle dei componenti, lasciando l’elenco delle importazioni nell’indice originale.

La migrazione consiste in alcuni passaggi:

• Abilitare il bundling dei componenti nelle Impostazioni del Progetto
• Spostare l’importazione/registrazione dei componenti in un nuovo file indice

Abilitare il Bundle dei Componenti 

Nelle Impostazioni del Progetto:

• Seleziona la casella Mostra Impostazioni Avanzate se non già selezionata
• Imposta l’opzione bundling. Si consiglia di utilizzare esbuild
• Imposta il entryPoint su js/component-index.js
• Imposta l’output su MyWonderland-components.js

Il packaging genererà automaticamente il js/component-index.js:

1/* wle:auto-imports:start */
2/* wle:auto-imports:end */
3
4export default function(engine) {
5/* wle:auto-register:start */
6/* wle:auto-register:end */
7}

Spostare i Componenti 

Se nel tuo progetto avevi importato/registrato manualmente componenti nel vecchio file js/index.js, sarà necessario spostarli nel punto di ingresso js/component-index.js:

js/index.js

 1import {loadRuntime} from '@wonderlandengine/api';
 2
 3/* wle:auto-imports:start */
 4/* wle:auto-imports:end */
 5
 6// Questa linea deve essere trasferita al bundle dei componenti
 7import {ManualComponent} from './js/manual-component.js';
 8
 9const engine = await loadRuntime(...);
10
11/* wle:auto-register:start */
12/* wle:auto-register:end */
13
14// Questa linea deve essere trasferita al bundle dei componenti
15engine.registerComponent(ManualComponent);

js/component-index.js

 1/* wle:auto-imports:start */
 2/* wle:auto-imports:end */
 3
 4import {ManualComponent} from './manual-component.js';
 5
 6export default function(engine) {
 7    /* wle:auto-register:start */
 8    /* wle:auto-register:end */
 9    engine.registerComponent(ManualComponent);
10}

Congratulazioni, ora stai usando la nuova architettura!

Gotchas 

Le applicazioni che utilizzano globali possono finire nel caso seguente:

js/manager.js

1export class Manager {
2    static isReady = false;
3}

app.js

1import {loadRuntime} from '@wonderlandengine/api';
2import {Manager} from './js/manager.js';
3
4const engine = await loadRuntime(...);
5Manager.isReady = true;
6engine.loadMainScene('MyScene.bin');

js/my-component.js

1import {Manager} from './manager.js';
2
3export class MyComponent extends Component {
4    start() {
5        console.log(Manager.isReady); // `false`
6    }
7}

In questo esempio, la classe Manager verrebbe dichiarata una volta in ciascun file.

La decisione di come strutturare l’applicazione sarà diversa per ogni caso d’uso. Ecco un elenco di possibili passi di migrazione:

• I manager potrebbero essere spostati completamente sul lato del bundle dei componenti
• I globali potrebbero essere inizializzati pigramente
• I dati potrebbero essere condivisi usando window (meno consigliato)
• Per utenti avanzati: Utilizzare un bundle js separato importato nell’html