Creando Bibliotecas en JavaScript

Este breve tutorial te guiará a través del proceso de crear y compartir una biblioteca de componentes para Wonderland Engine.

Instala npm 

npm es el gestor de paquetes oficial para el ecosistema de JavaScript.

Ahora forma parte de la cadena de herramientas de Wonderland Engine, facilitando a los desarrolladores el uso de dependencias externas. Como creador de bibliotecas, necesitarás npm para gestionar y publicar tus bibliotecas.

Puedes descargar nodejs, que viene con una instalación de npm empaquetada.

Crea la Biblioteca 

Para este tutorial, vamos a crear una biblioteca en una carpeta llamada my-library. Cambia al directorio de la carpeta my-library y ejecuta:

npm init

Aparecerán algunos mensajes pidiéndote información sobre tu paquete:

nombre del paquete: (my-library)
versión: (1.0.0)

Después de completar los mensajes, verás un archivo package.json que se ve así:

{
  "name": "my-library",
  "version": "1.0.0",
  "description": "¡Mi primera biblioteca para Wonderland Engine!",
  "main": "index.js"
}

El archivo package.json contiene toda la información necesaria sobre la biblioteca. Cuando un desarrollador instala tu biblioteca, npm encuentra los datos que necesita dentro de este archivo.

Etiqueta ‘wonderlandengine’ 

El Editor de Wonderland registra automáticamente las bibliotecas basadas en una etiqueta meta específica: wonderlandengine.

Al crear una biblioteca para usar con Wonderland Engine, debes agregar la siguiente línea a tu package.json, por ejemplo, sobre "main": "index.js":

  "wonderlandengine": {},

Por ahora, esto es todo lo que necesitas para que el editor recoja automáticamente la biblioteca. En el futuro, el objeto de metadatos wonderlandengine podría permitir especificar más propiedades para Wonderland Engine.

Punto de Entrada 

Una de las partes más importantes es el campo index.js. Especifica el archivo que debería exportar los objetos de tu biblioteca. Cuando un desarrollador usa tu biblioteca e importa:

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

'my-library' se resuelve a:

node_modules/my-library/index.js

El punto de entrada debe exportar la interfaz pública (clases, funciones, etc.) de tu biblioteca:

index.js

// Re-exporta componentes de otros archivos
export {ComponentA} from './component-a.js';
export {ComponentB} from './component-b.js';

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

Cuando se encuentra la etiqueta meta wonderlandengine en un package.json, el punto de entrada se usa para encontrar todos los componentes exportados (ComponentA y ComponentB en el ejemplo anterior):

Dependencias 

En este tutorial, vamos a crear un componente que usa la API pública de Wonderland Engine.

Lo agregamos como una dependencia en el package.json. Debajo de "dependencies", añadimos una nueva sección "peerDependencies":

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

Esto es importante, ya que queremos permitir al usuario usar un rango de versiones de la API con una biblioteca, usualmente hasta la próxima versión mayor de lanzamiento.

Para poder usar la API, después tienes que ejecutar npm install para aplicar los cambios en tu package.json:

npm install

Añadir Contenido 

Para este tutorial, vamos a crear un componente simple que mueve su objeto hacia adelante con cierta velocidad. Crea un nuevo archivo llamado move-forward.js en tu carpeta de la biblioteca con el siguiente contenido:

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

También necesitamos reexportar este componente para el desarrollador que utiliza nuestro paquete. Podemos actualizar el archivo index.js con:

index.js

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

Para este ejemplo, podríamos haber colocado el componente directamente en index.js. Sin embargo, cuanto más crezca tu biblioteca, mayor control querrás tener sobre tus exportaciones.

Pruebas y Depuración 

Las pruebas se pueden realizar creando un proyecto de Wonderland Engine e instalando tu biblioteca usando una ruta local. Para este tutorial, asumiremos que se ha creado un proyecto de Wonderland Engine con el nombre MyWonderland. En la raíz del proyecto, puedes ejecutar:

npm install path/to/my-library

Necesitarás reemplazar path/to/my-library con una ruta que apunte a la raíz de la carpeta de la biblioteca.

¡Eso es todo! Ahora deberías tener acceso al componente MoveForward en tu proyecto.

Editor de Wonderland Engine con nuestro componente move-forward

En este caso, la biblioteca está instalada localmente. Otros desarrolladores no tendrán acceso a la biblioteca. Necesitas:

  • Publicar la biblioteca (como se describe en la sección Publicar la Biblioteca)
  • O proporcionar un paquete local (por ejemplo, como .tar.gz) para que lo instalen

Publicar la Biblioteca 

Al publicar la biblioteca como un paquete en el repositorio de paquetes npm, marcas una cierta versión del código con un número de versión y subes el paquete a los servidores de npm para que otros desarrolladores puedan descargarlo.

Iniciar Sesión 

Para publicar tu biblioteca en npm, necesitas:

  • Crear una cuenta en npmjs.com
  • Iniciar sesión usando el comando del terminal (más información aquí)

Publicar 

Una vez que hayas iniciado sesión, puedes publicar tu paquete navegando a la carpeta de la biblioteca con un terminal y ejecutando:

npm run publish

También puedes ejecutar una publicación “en seco” usando:

npm run publish --dry-run

Este comando imprimirá información sobre los archivos que se publicarán y permite verificar que no estás publicando archivos no deseados.

Instalar 

Con tu biblioteca publicada con éxito, puedes instalarla entrando en tu proyecto y ejecutando:

npm install --save my-library

Ahora estás listo para crear las bibliotecas más maravillosas.

Creando bibliotecas ayudas a que la comunidad florezca y desarrolle contenido WebXR increíble para todos.

Writing Components in Typescript