Руководство по миграции

Миграция проектов с устаревшими сценариями

В июле 2016 года PlayCanvas принял свою текущую систему сценариев (иногда называемую Scripts 2.0). Проекты с устаревшими сценариями продолжают работать как обычно. Однако больше нельзя создавать или копировать проекты с устаревшими сценариями.

В декабре 2020 года было объявлено, что проекты с устаревшими сценариями станут доступны только для чтения в ближайшем будущем. Когда вы откроете один из них в редакторе, вы увидите следующее сообщение на панели управления проектом:

И следующее сообщение в редакторе:

Если вы хотите продолжить работу над проектами с устаревшими сценариями, мы рекомендуем мигрировать их в текущий формат. К сожалению, для этого нет автоматического процесса миграции. Вместо этого это ручной процесс, но данное руководство поможет вам выполнить его.

Шаг 1 - Создание нового проекта

Сначала создадим новый пустой проект для переноса ассетов и кода. Удалите четыре созданных по умолчанию объекта ниже корневого объекта сцены.

Шаг 2 - Перенос ассетов

Затем скопируйте все ассеты в ваш новый проект (за исключением сценариев, которые в устаревших проектах не являются настоящими ассетами). Можно копировать и вставлять ассеты из одного проекта в другой (используя контекстное меню правой кнопки мыши).

Однако проекты с устаревшими сценариями довольно старые. Много лет назад ассеты импортировались без расширений файлов, и некоторые метаданные могут быть недоступны для просмотра на панели инспектора. Поэтому вы можете рассмотреть возможность загрузки исходных ассетов и загрузки их в ваш новый проект.

Шаг 3 - Перенос сценариев

Загрузите сценарии из вашего проекта с устаревшими сценариями через панель управления проектом:

Если ваш устаревший проект подключен к репозиторию GitHub, загрузите сценарии оттуда.

Теперь вы можете загрузить устаревшие сценарии в ваш новый проект.

Шаг 4 - Обновление сценариев до текущего формата

Перенесенные сценарии в вашем новом проекте теперь необходимо обновить до текущего формата. Вот пример, показывающий устаревший формат:

pc.script.attribute('speed', 'number', 10);

pc.script.create('myScript', function (app) {
    // Создает новый экземпляр MyScript
    var MyScript = function (entity) {
        this.entity = entity;
    };

    MyScript.prototype = {
        // Вызывается один раз после загрузки всех ресурсов и перед первым обновлением
        initialize: function () {
        },

        // Вызывается каждый кадр, dt - время в секундах с момента последнего обновления
        update: function (dt) {
        }
    };

    return MyScript;
});

И вот эквивалентный скрипт в текущем формате:

var MyScript = pc.createScript('myScript');

MyScript.attributes.add('speed', { type: 'number', default: 10 });

// инициализация кода, вызываемая один раз для каждой сущности
MyScript.prototype.initialize = function() {
    var app = this.app;       // экземпляр приложения доступен как this.app
    var entity = this.entity; // свойство сущности уже настроено
};

// код обновления, вызываемый каждый кадр
MyScript.prototype.update = function(dt) {
};

Вещи, на которые стоит обратить внимание:

• В текущем формате сценария нет конструктора. Код конструктора должен быть перемещен в функцию initialize.
• app (экземпляр pc.Application скрипта) становится this.app.
• this.entity автоматически доступен для скриптов текущего формата.

Миграция событий скрипта

Устаревшие скрипты обрабатывают события, такие как enable, disable и destroy, следующим образом:

onEnable: function () {

},

onDisable: function () {

},

onDestroy: function () {

},

Для переноса их в текущий формат сценария вы должны зарегистрировать обработчики событий в функции initialize сценария:

MyScript.prototype.initialize = function() {
    this.on("enable", function () {

    });

    this.on("disable", function () {

    });

    this.on("destroy", function () {

    });
};

Шаг 5 - Перенос иерархии сцены

Далее мы перенесем иерархию сцены из устаревшего проекта. Редактор PlayCanvas поддерживает операцию копирования и вставки между двумя экземплярами редактора. Однако эта операция не выполняется, если в выборке присутствуют компоненты устаревших сценариев. Поэтому сначала вам следует удалить все компоненты сценариев из вашего устаревшего проекта со сценариями. Чтобы сделать это, выберите все объекты с компонентами устаревших сценариев. Вы можете сделать это, выполнив следующий JavaScript в консоли JavaScript браузера:

var entities = editor.call('entities:list').filter(function(entity) {
    return entity.has('components.script');
});
if (entities.length) {
    editor.call('selector:set', 'entity', entities);
} else {
    editor.call('selector:clear');
}

Вы должны увидеть что-то похожее на следующее:

Затем вы можете нажать кнопку удаления в Инспекторе:

Теперь вы можете успешно скопировать и вставить иерархию вашей игры из проекта только для чтения в новый проект-приемник.

С этим сделанным, вы можете нажать CTRL+Z (CMD+Z на Mac), чтобы отменить предыдущее удаление ваших устаревших компонентов сценария.

Повторно выберите все сущности, имеющие компонент сценария. Создайте компонент сценария на каждой соответствующей сущности в новом проекте и добавьте соответствующие сценарии к этим компонентам. Наконец, пройдитесь по каждому атрибуту сценария на каждом сценарии на каждом компоненте сценария и скопируйте его значение в новый проект.

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