Создание библиотек JavaScript

Этот короткий учебник поможет вам пройти процесс создания и распространения библиотеки компонентов для Wonderland Engine.

Установка npm 

npm — официальный менеджер пакетов для экосистемы JavaScript.

Теперь он является частью инструментария Wonderland Engine, что упрощает использование внешних зависимостей для разработчиков. Как создателю библиотеки, вам понадобится npm для управления и публикации ваших библиотек.

Вы можете загрузить nodejs, которая включает установленный пакет npm.

Создание библиотеки 

Для этого учебного пособия мы создадим библиотеку в папке my-library. Перейдите в директорию my-library и выполните:

npm init

Появятся приглашения с просьбой ввести информацию о вашем пакете:

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

После заполнения запросов вы увидите файл package.json, который выглядит так:

{
  "name": "my-library",
  "version": "1.0.0",
  "description": "Моя первая библиотека для Wonderland Engine!",
  "main": "index.js"
}

Файл package.json содержит всю необходимую информацию о библиотеке. Когда разработчик устанавливает вашу библиотеку, npm находит необходимые данные внутри этого файла.

Тег ‘wonderlandengine’ 

Редактор Wonderland автоматически регистрирует библиотеки на основе определенного мета-тега: wonderlandengine.

При создании библиотеки для использования с Wonderland Engine необходимо добавить следующую строчку в ваш package.json, например, выше строки "main": "index.js":

  "wonderlandengine": {},

На данный момент это все, что вам нужно, чтобы редактор автоматически обнаружил библиотеку. В будущем объект метаданных wonderlandengine может позволить указывать больше свойств для Wonderland Engine.

Точка входа 

Одним из самых важных компонентов является поле index.js. Оно указывает файл, который должен экспортировать объекты вашей библиотеки. Когда разработчик использует вашу библиотеку и импортирует её:

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

'my-library' преобразуется в:

node_modules/my-library/index.js

Точка входа должна экспортировать публичный интерфейс (классы, функции и т.д.) вашей библиотеки:

index.js

// Реэкспорт компонентов из других файлов
export {ComponentA} from './component-a.js';
export {ComponentB} from './component-b.js';

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

Когда мета-тег wonderlandengine найден в package.json, точка входа используется для нахождения всех экспортируемых компонентов (ComponentA и ComponentB в приведенном выше примере):

Зависимости 

В этом учебном пособии мы создадим компонент, который использует общедоступный API Wonderland Engine.

Мы добавляем его в качестве зависимости в package.json. Ниже "dependencies" добавляем новый раздел "peerDependencies":

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

Это важно, поскольку мы хотим позволить пользователю использовать диапазон версий API с библиотекой, обычно до следующей основной версии.

Чтобы иметь возможность использовать API, вам необходимо запустить npm install для применения изменений в вашем package.json:

npm install

Добавление содержимого 

Для этого руководства мы создадим простой компонент, который перемещает свой объект вперед с определенной скоростью. Создайте новый файл move-forward.js в папке вашей библиотеки со следующим содержанием:

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

Нам также нужно реэкспортировать этот компонент для разработчика, использующего наш пакет. Мы можем обновить файл index.js следующим образом:

index.js

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

В этом примере мы могли бы разместить компонент непосредственно в index.js. Однако по мере роста вашей библиотеки контроль над экспортами будет становиться все более важным.

Тестирование и отладка 

Тестирование можно проводить, создавая проект Wonderland Engine и устанавливая вашу библиотеку, используя локальный путь. Для этого учебного пособия мы будем считать, что проект Wonderland Engine создан с именем MyWonderland. В корневой директории проекта вы можете выполнить:

npm install path/to/my-library

Вам нужно заменить path/to/my-library на путь, указывающий на корень папки библиотеки.

Вот и все! Теперь у вас должен быть доступ к компоненту MoveForward в вашем проекте.

Редактор Wonderland Engine с нашим компонентом move-forward

В этом случае библиотека установлена локально. Другие разработчики не будут иметь доступа к библиотеке. Вам необходимо либо:

  • Опубликовать библиотеку (описано в разделе Публикация библиотеки)
  • Или предоставить локальный пакет (например, в виде .tar.gz) для установки

Публикация библиотеки 

Опубликовав библиотеку как пакет в репозитории пакетов npm, вы присваиваете определенной версии кода номер версии и загружаете пакет на серверы npm для загрузки другими разработчиками.

Вход в систему 

Чтобы опубликовать вашу библиотеку в npm, нужно:

  • Создать учетную запись на npmjs.com
  • Войти в систему, используя команду в терминале (подробнее здесь)

Публикация 

Когда вы вошли в систему, вы можете опубликовать свой пакет, переключившись в папку библиотеки и выполнив:

npm run publish

Вы также можете выполнить “сухую” публикацию, используя:

npm run publish --dry-run

Эта команда выведет информацию о файлах, которые будут опубликованы, и позволит проверить, что вы не публикуете ненужные файлы.

Установка 

После успешной публикации вашей библиотеки вы можете установить её, вернувшись в ваш проект и выполнив:

npm install --save my-library

Теперь вы готовы создавать самые замечательные библиотеки.

Создание библиотек помогает сообществу развиваться и разрабатывать удивительный контент WebXR для всех.

Writing Components in Typescript