Schreiben von JavaScript-Bibliotheken

Dieses kurze Tutorial führt Dich durch den Prozess der Erstellung und Weitergabe einer Komponentenbibliothek für Wonderland Engine.

Installiere npm 

npm ist der offizielle Paketmanager für das JavaScript-Ökosystem.

Es ist jetzt Teil der Wonderland Engine-Toolchain, um Entwicklern die Nutzung externer Abhängigkeiten nahtlos zu ermöglichen. Als Bibliothek-Entwickler benötigst Du npm, um Deine Bibliotheken zu verwalten und zu veröffentlichen.

Du kannst nodejs herunterladen, das eine gepackte npm-Installation enthält.

Erstelle die Bibliothek 

Für dieses Tutorial erstellen wir eine Bibliothek in einem Ordner namens my-library. Wechsle in das Verzeichnis des Ordners my-library und führe folgendes aus:

npm init

Einige Eingabeaufforderungen erscheinen, die Dich nach Informationen zu Deinem Paket fragen:

package name: (my-library)
version: (1.0.0)

Nachdem Du die Eingaben ausgefüllt hast, siehst Du eine package.json Datei, die folgendermaßen aussieht:

{
  "name": "my-library",
  "version": "1.0.0",
  "description": "Meine erste Wonderland Engine Bibliothek!",
  "main": "index.js"
}

Die package.json Datei enthält alle notwendigen Informationen über die Bibliothek. Wenn ein Entwickler Deine Bibliothek installiert, findet npm die benötigten Daten in dieser Datei.

‘wonderlandengine’ Tag 

Der Wonderland Editor registriert automatisch Bibliotheken basierend auf einem bestimmten Metatag: wonderlandengine.

Wenn Du eine Bibliothek für die Verwendung mit der Wonderland Engine erstellst, musst Du folgende Zeile zu Deiner package.json hinzufügen, z.B. oberhalb von "main": "index.js":

  "wonderlandengine": {},

Für jetzt ist dies alles, was der Editor benötigt, um die Bibliothek automatisch zu erkennen. In Zukunft könnte das wonderlandengine Metadatenobjekt es ermöglichen, weitere Eigenschaften für Wonderland Engine zu spezifizieren.

Einstiegspunkt 

Einer der wichtigsten Teile ist das index.js Feld. Es gibt die Datei an, die die Objekte Deiner Bibliothek exportieren soll. Wenn ein Entwickler Deine Bibliothek nutzt und sie importiert:

import {ComponentA, ComponentB} from 'my-library';

Wird 'my-library' aufgelöst zu:

node_modules/my-library/index.js

Der Einstiegspunkt muss daher die öffentliche Schnittstelle (Klassen, Funktionen etc.) Deiner Bibliothek exportieren:

index.js

// Re-export Komponente aus anderen Dateien
export {ComponentA} from './component-a.js';
export {ComponentB} from './component-b.js';

export {someUtilityFunction} from './someUtilityFunction.js';

Wenn das wonderlandengine Metatag in einer package.json gefunden wird, wird der Einstiegspunkt genutzt, um alle exportierten Komponenten zu finden (ComponentA und ComponentB im obigen Beispiel):

Abhängigkeiten 

In diesem Tutorial erstellen wir eine Komponente, die die öffentliche API der Wonderland Engine nutzt.

Wir fügen sie als Abhängigkeit in der package.json hinzu. Unterhalb von "dependencies" fügen wir einen neuen Abschnitt "peerDependencies" hinzu:

  "dependencies": {
  },
  "peerDependencies": {
    "@wonderlandengine/api": "^1.0.0"
  }

Das ist wichtig, da wir den Benutzern ermöglichen möchten, eine Bandbreite von API-Versionen mit einer Bibliothek zu verwenden, normalerweise bis zur nächsten größeren Release-Version.

Um die API nutzen zu können, musst Du als Nächstes npm install ausführen, um Änderungen in Deiner package.json anzuwenden:

npm install

Inhalt hinzufügen 

Für dieses Tutorial erstellen wir eine einfache Komponente, die ihr Objekt mit einer bestimmten Geschwindigkeit vorwärts bewegt. Erstelle eine neue Datei namens move-forward.js in Deinem Bibliotheksordner mit folgendem Inhalt:

move-forward.js

import {Component, Property} from '@wonderlandengine/api';

const tempVec = new Float32Array(3);

export class MoveForward extends Component {
    static TypeName = 'move-forward';
    static Properties = {
        speed: Property.float(1.5),
    };

    update(dt) {
        this.object.getForward(tempVec);

        tempVec[0] *= this.speed;
        tempVec[1] *= this.speed;
        tempVec[2] *= this.speed;

        this.object.translate(tempVec);
    }
}

Wir müssen diese Komponente auch an die Entwickler, die unser Paket nutzen, re-exportieren. Wir können die index.js Datei mit diesem Inhalt aktualisieren:

index.js

export {MoveForward} from './move-forward.js';

Für dieses Beispiel hätten wir die Komponente direkt in index.js platzieren können. Allerdings, je mehr Deine Bibliothek wächst, desto mehr Kontrolle wirst Du über Deine Exporte haben wollen.

Testen & Debuggen 

Das Testen kann erfolgen, indem man ein Wonderland Engine Projekt erstellt und Deine Bibliothek über einen lokalen Pfad installiert. Für dieses Tutorial nehmen wir an, dass ein Wonderland Engine Projekt mit dem Namen MyWonderland erstellt wurde. Im Projekt-Root kannst Du folgendes ausführen:

npm install path/to/my-library

Du musst path/to/my-library durch einen Pfad ersetzen, der auf das Root des Bibliotheksordners zeigt.

Das war’s! Du solltest jetzt auf die MoveForward Komponente in Deinem Projekt zugreifen können.

Wonderland Engine Editor mit unserer move-forward Komponente

In diesem Fall ist die Bibliothek lokal installiert. Andere Entwickler haben keinen Zugriff auf die Bibliothek. Du musst entweder:

  • Die Bibliothek veröffentlichen (wie im Abschnitt Bibliothek veröffentlichen beschrieben)
  • Oder ein lokales Paket bereitstellen (z.B. als .tar.gz), das sie installieren können

Bibliothek veröffentlichen 

Indem Du die Bibliothek als Paket im npm-Paketrepository veröffentlichst, markierst Du eine bestimmte Version des Codes mit einer Versionsnummer und lädst das Paket auf die npm-Server zum Download durch andere Entwickler hoch.

Anmeldung 

Um Deine Bibliothek auf npm zu veröffentlichen, musst Du:

  • Ein Konto bei npmjs.com erstellen
  • Dich mit dem Terminalbefehl anmelden (mehr Informationen hier)

Veröffentlichen 

Wenn Du angemeldet bist, kannst Du Dein Paket veröffentlichen, indem Du in den Bibliotheksordner mit einem Terminal navigierst und folgendes ausführst:

npm run publish

Du kannst auch eine “trockene” Veröffentlichung mit folgendem Befehl durchführen:

npm run publish --dry-run

Dieser Befehl wird Informationen über die zu veröffentlichenden Dateien ausgeben und ermöglicht es, zu überprüfen, dass Du keine unerwünschten Dateien veröffentlichst.

Installation 

Mit erfolgreich veröffentlichter Bibliothek kannst Du sie in Deinem Projekt installieren, indem Du folgendes ausführst:

npm install --save my-library

Jetzt bist Du bereit, die wunderbarsten Bibliotheken zu erstellen.

Indem Du Bibliotheken erstellst, unterstützt Du die Community dabei, großartige WebXR Inhalte für alle zu entwickeln.

Writing Components in Typescript