Scrivere Librerie JavaScript

Questo breve tutorial ti guiderà attraverso il processo di creazione e condivisione di una libreria di componenti per Wonderland Engine.

Installa npm 

npm è il gestore di pacchetti ufficiale per l’ecosistema JavaScript.

Ora fa parte del toolchain di Wonderland Engine, rendendo semplice per gli sviluppatori l’utilizzo di dipendenze esterne. Come creatore di librerie, avrai bisogno di npm per gestire e pubblicare le tue librerie.

Puoi scaricare nodejs, che include un’installazione di npm.

Crea la Libreria 

Per questo tutorial, creeremo una libreria in una cartella chiamata my-library. Cambia directory nella cartella my-library ed esegui:

npm init

Appariranno delle richieste che ti chiederanno informazioni sul tuo pacchetto:

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

Dopo aver completato le richieste, vedrai un file package.json che assomiglia a questo:

{
  "name": "my-library",
  "version": "1.0.0",
  "description": "La mia prima libreria per Wonderland Engine!",
  "main": "index.js"
}

Il file package.json contiene tutte le informazioni necessarie sulla libreria. Quando uno sviluppatore installa la tua libreria, npm trova i dati necessari all’interno di questo file.

Tag ‘wonderlandengine’ 

Wonderland Editor registra automaticamente le librerie basate su un tag meta specifico: wonderlandengine.

Quando crei una libreria da usare con Wonderland Engine, devi aggiungere la seguente riga al tuo package.json, ad esempio, sopra "main": "index.js":

  "wonderlandengine": {},

Per ora, questo è tutto ciò di cui hai bisogno perché l’editor rilevi automaticamente la libreria. In futuro, l’oggetto metadata wonderlandengine potrebbe consentire di specificare più proprietà per Wonderland Engine.

Punto di Entrata 

Uno dei pezzi più importanti è il campo index.js. Esso specifica il file che dovrebbe esportare gli oggetti della tua libreria. Quando uno sviluppatore usa la tua libreria e la importa:

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

'my-library' viene risolto in:

node_modules/my-library/index.js

Il punto di entrata deve quindi esportare l’interfaccia pubblica (classi, funzioni, ecc.) della tua libreria:

index.js

// Riesporta componenti da altri file
export {ComponentA} from './component-a.js';
export {ComponentB} from './component-b.js';

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

Quando il tag meta wonderlandengine viene trovato in un package.json, il punto di entrata viene utilizzato per trovare tutti i componenti esportati (ComponentA e ComponentB nell’esempio sopra):

Dipendenze 

In questo tutorial, creeremo un componente che utilizza l’API pubblica di Wonderland Engine.

Lo aggiungiamo come dipendenza nel package.json. Sotto "dependencies", aggiungiamo una nuova sezione "peerDependencies":

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

Questo è importante, poiché vogliamo permettere all’utente di usare un range di versioni dell’API con una libreria, solitamente fino alla prossima versione maggiore.

Per poter usare l’API, devi eseguire npm install per applicare le modifiche nel tuo package.json:

npm install

Aggiungi Contenuto 

In questo tutorial, creeremo un semplice componente che muove il suo oggetto in avanti con una certa velocità. Crea un nuovo file chiamato move-forward.js nella tua cartella libreria con il seguente contenuto:

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);
    }
}

Dobbiamo anche riesportare questo componente allo sviluppatore che usa il nostro pacchetto. Possiamo aggiornare il file index.js con:

index.js

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

Per questo esempio, avremmo potuto mettere il componente direttamente nell’index.js. Tuttavia, più la tua libreria cresce, maggiore sarà il controllo che vorrai avere sulle tue esportazioni.

Test & Debugging 

Il test può essere fatto creando un progetto Wonderland Engine e installando la tua libreria usando un percorso locale. Per questo tutorial, assumeremo che sia stato creato un progetto Wonderland Engine con il nomeMyWonderland. Nella root del progetto, puoi eseguire:

npm install path/to/my-library

Dovrai sostituire path/to/my-library con un percorso che punta alla radice della cartella della libreria.

Ecco fatto! Dovresti ora avere accesso al componente MoveForward nel tuo progetto.

In questo caso, la libreria è installata localmente. Altri sviluppatori non avranno accesso alla libreria. Devi o:

• Pubblicare la libreria (come descritto nella sezione Pubblica la Libreria)
• Oppure fornire un pacchetto locale (ad es. come .tar.gz) per loro da installare

Pubblica la Libreria 

Pubblicando la libreria come pacchetto sul repository di pacchetti npm, marchi una certa versione del codice con un numero di versione e carichi il pacchetto sui server npm per essere scaricato da altri sviluppatori.

Login 

Per pubblicare la tua libreria su npm, devi:

• Creare un account su npmjs.com
• Accedere usando il comando terminale (più informazioni qui)

Pubblica 

Dopo aver effettuato l’accesso, puoi pubblicare il tuo pacchetto navigando nella cartella della libreria con un terminale ed eseguendo:

npm run publish

Puoi anche eseguire una pubblicazione “a secco” usando:

npm run publish --dry-run

Questo comando stamperà informazioni sui file da pubblicare e ti permetterà di verificare che non stai pubblicando file indesiderati.

Installa 

Con la tua libreria pubblicata con successo, puoi installarla entrando nel tuo progetto ed eseguendo:

npm install --save my-library

Ora sei pronto per creare le librerie più belle.

Creare librerie aiuta la comunità a prosperare e a sviluppare contenuti WebXR straordinari per tutti.