JavaScript Hot-Reload in 1.3.0

Die Veröffentlichung der Wonderland Engine 1.3.0 führt eine neue Methode ein, JavaScript/TypeScript-Anwendungen im Editor zu packen.

Mit der neuen Einrichtung kann der Editor die Unterstützung von Hot Reload zurückbringen, d.h. das Neuladen Deines JavaScripts im Browser ohne das Neustarten der Engine und der VR-Sitzungen.

Vor-Version 1.3.0 

Zuvor erzeugte der Editor ein einziges JavaScript-Bundle von einem einzigen Einstiegspunkt (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 */

Das generierte Bundle enthielt somit importierte Abhängigkeiten, den Engine-Initiierungscode sowie globale Variablen.

Neue Architektur 

Die neue Architektur trennt den Anwendungs-Einstieg vom Komponenten-Registrierungseintrag:

• js/index.js: Enthält Komponenten-Registrierung
• app.js: Enthält die Engine-Erstellung, globale Variablen usw.

js/index.js

 1// Komponenten-Einstiegspunkt
 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// Anwendungs-Einstiegspunkt
2
3import {loadRuntime} from '@wonderlandengine/api';
4
5const engine = await loadRuntime(...);
6engine.loadMainScene('MyScene.bin');

Außerdem wird das Komponenten-Bundle automatisch heruntergeladen und durch den engine.loadMainScene()-Aufruf registriert.

Du bist frei, Komponenten manuell zu importieren und in der Anwendung zu registrieren, aber sieh Dir zuerst den Abschnitt Gotchas an, um häufige Fallstricke zu vermeiden.

Einstellungen 

Der Editor hatte früher nur einen einzigen Eintrag für JavaScript-Einstellungen:

Jetzt wird dieser für die Anwendungs- und Komponenten-Einträge dupliziert:

Die output-Einstellung wird verwendet, um auf den Bundle-Dateinamen im Bereitstellungsordner zu verweisen.

Wenn ein benutzerdefiniertes npm-Kommando verwendet wird, muss dieser Wert auf den Dateinamen der generierten Datei gesetzt werden.

Migration 

Beim Öffnen eines Projekts vor Version 1.3 wird der Migrationsprozess das Komponenten-Bundle deaktivieren und die Importliste im ursprünglichen Index belassen.

Die Migration besteht aus ein paar Schritten:

• Aktiviere das Komponent-Packbonung im Projekt Einstellungen
• Verschiebe die Komponenten-Importe/Registrierungen in eine neue Indexdatei

Komponenten-Bundle aktivieren 

In den Projekt Einstellungen:

• Markiere das Kontrollkästchen Erweiterte Einstellungen anzeigen, falls nicht markiert
• Setze die bundling-Option. Wir empfehlen die Verwendung von esbuild
• Setze den entryPoint auf js/component-index.js
• Setze den output auf MyWonderland-components.js

Das Packen erzeugt automatisch die Datei 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}

Komponenten verschieben 

Wenn Dein Projekt manuell importierte/registrierte Komponenten in der alten js/index.js-Datei hatte, müssen diese in den js/component-index.js-Einstiegspunkt verschoben werden:

js/index.js

 1import {loadRuntime} from '@wonderlandengine/api';
 2
 3/* wle:auto-imports:start */
 4/* wle:auto-imports:end */
 5
 6// Diese Zeile muss zum Komponenten-Bundle hinzugefügt werden
 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// Diese Zeile muss zum Komponenten-Bundle hinzugefügt werden
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}

Herzlichen Glückwunsch, du verwendest jetzt die neue Architektur!

Gotchas 

Anwendungen, die globale Variablen haben, können in folgendem Fall enden:

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 diesem Beispiel würde die Klasse Manager in jeder Datei einmal deklariert.

Die Entscheidung, wie die Anwendung architektonisch strukturiert wird, wird von Fall zu Fall unterschiedlich sein. Hier ist eine Liste potenzieller Migrationsschritte:

• Manager könnten vollständig auf die Komponenten-Bundle-Seite verschoben werden
• Globale Variablen könnten lazy initialisiert werden
• Daten könnten über window geteilt werden (weniger empfohlen)
• Für fortgeschrittene Benutzer: Die Verwendung eines separaten JavaScript-Bundles, das im HTML importiert wird