Создание пользовательских событий для ct.js

Автоматически переведённая страница

К сожалению, на полный ручной перевод у нас не хватает ресурсов.
Если вы увидели ошибку — отправьте пул-риквест с исправлениями (ссылка для редактирования в конце страницы).

Пользовательские события — это отличный способ сделать вашу библиотеку более простой для изучения и использования. Это позволяет пользователям упростить свои скрипты и избежать шаблонного кода. Вы уже используете события в шаблонах и комнатах через список событий, и ваши события тоже могут быть там.

Но сначала вам нужно понять, как работают такие события.

Целевые коды событий

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

• thisOnCreate — код, вызываемый при создании сущности (копии шаблона) или переходе в целевую комнату;
• thisOnDestroy — код, вызываемый при уничтожении текущей редактируемой сущности (комната/шаблон). Для комнат этот код срабатывает при переходе из одной комнаты в другую или при удалении интерфейсной комнаты со сцены;
• thisOnStep — код «старта кадра» для текущей редактируемой сущности (шаблон/комната);
• thisOnDraw — код «конца кадра» для текущей редактируемой сущности (шаблон/комната).

Это регулярные целевые области жизненного цикла. Они выполняются для каждой копии/комнаты, и ключевое слово this указывает на текущую сущность. Но иногда нужно запустить код один раз для всех комнат/копий, возможно, для инициализации свойств или глобальных игровых правил. Ниже представлены аналогичные события, но они выполняются только корневыми комнатами. Корневая комната всегда — это ct.room, комната, с помощью которой начинается или в которую переключается ваша игра, и которая может содержать слои интерфейса и другие подкомнаты.

• rootRoomOnCreate
• rootRoomOnStep
• rootRoomOnDraw
• rootRoomOnLeave

Контекст выполнения отличается здесь. Ключевое слово this будет указывать на ct.room, и вам нужно будет работать с вашими шаблонами/комнатами, используя замены переменных из /*%%ENTITY_TYPE%%*/ и /*%%ENTITY_NAME%%*/. Возможно, вам понадобится использовать ct.templates.list или ct.rooms.list, чтобы получить доступ к вашим копиям и комнатам.

Обратите внимание, что использование полей rootRoom* делает поведение статическим, увеличивая размер пакета игры и не позволяя разработчику игры добавлять и удалять это поведение в реальном времени игры. Эти события следует использовать только в тех случаях, когда вы не можете использовать поля thisOn*.

Когда ct.IDE экспортирует игру, он объединяет все события в thisOnCreate, thisOnDestroy, thisOnStep и thisOnDraw для каждого шаблона и комнаты, а также собирает события для корневых комнат со всех скриптовых сущностей. Одно событие пользователя может способствовать нескольким целевым областям кода одновременно: например, таймер будет объявлен в thisOnCreate и проверять выполнение в thisOnStep.

Создание события:

События должны быть объявлены в module.json, затем их код должен быть либо вложен в module.json, либо написан в отдельных файлах в папке events.

Декларация события

События объявляются в объекте events в module.json. Ниже приведен отрывок из ct.place в качестве примера с большинством полей событий:

{
    "main": {
        "name": "ct.place",
        "version": "4.0.0",
        /* ... */
    },
    /* ... */
    "events": {
        "collisionTemplate": {
            /* Название события, отображаемое в селекторе событий и списке событий */
            "name": "Сражаясь с шаблоном",
            /* Пример локализованного названия. `Ru` - код языка здесь. */
            "name_Ru": "Столкновение с шаблоном",

            /* События с аргументами, такие как это, могут иметь специальное шаблонизированное название для списков событий.
               %%template%% соответствует значению аргумента `template` ниже. */
            "parameterizedName": "Сражаясь с %%template%% шаблоном",
            /* Пример локализованного названия. `Ru` - код языка здесь. */
            "parameterizedName_Ru": "Столкновение с шаблоном %%template%%",

            /* События также могут иметь расширенные описания, отображаемые в меню "Добавить событие".
               Эти описания также могут быть локализованы */
            /* "hint": "Пример описания", */

            /* Отображаемый значок этого события.
               См. список иконок в разделе Meta основного файла ct.js.*/
            "icon": "копия",
            /* Если установлено значение true, событие в редакторе списка событий будет пытаться получить миниатюру
               первого зала, шаблона или текстуры в списке аргументов и отобразить ее. */
            "useAssetThumbnail": true,

            /* Список сценариев, поддерживающих это событие. В настоящее время могут включать `шаблон`, `room`. */
            "applicable": ["шаблон"],

            /* Если вы проектируете событие только для шаблонов, укажите поддерживаемые базовые классы здесь,
               или не используйте это поле, если они поддерживаются все. */
            "baseClasses": ["AnimatedSprite", "NineSlicePlane", "Text"],

            /* Кодовое имя категории, в которой будет отображаться это событие. */
            "category": "сражения",

            /* Список аргументов (необязательно) требуемых событием. */
            "arguments": {
                /* Имя поля соответствует имени переменной в шаблоне кода */
                "шаблон": {
                    /* Отображаемое имя в редакторе аргументов */
                    "name": "Шаблон",
                    /* Пример локализованного названия. `Ru` - код языка здесь. */
                    "name_Ru": "Шаблон",
                    /* Тип аргумента. */
                    "type": "шаблон"

                    /* Аргументы числового и строкового типов также могут иметь значение по умолчанию.
                       Они заполняют список аргументов для новых событий. */
                    /* "default": 404 */
                }
            },

            /* Список целевых кодов из первого раздела этой страницы, к которым это событие вносит свой вклад. */
            "codeTargets": ["thisOnStep"],

            /* Местные переменные, предоставляемые событием для кода пользователя. */
            "locals": {
                /* Объявляет переменную `other` типа ` Копия`. */
                "other": {
                    /* Тип передается в TypeScript как есть. */
                    "type": "Копия",
                    /* Местные переменные перечислены в списке событий вместе с их описаниями */
                    "description": "Сражаясь с копией",
                    /* Описания местных переменных также могут быть локализованы */
                    "description_Ru": "Сражаясь с копией",
                }
            }
        },
        "collisionCGroup": {
            "name": "Сражаясь с группой",
            /* ... та же структура */
        }
    },
    "eventCategories": {
        "сражения": {
            "name": "Сражения",
            "icon": "копия"
        }
    }
}

Совет

Типы в events.yourEventCode.locals - это имена TypeScript. Копия - это копия ct.js, Room - это комната (см. документацию по этим и другим встроенным классам).

Помимо этих простых значений, вы можете использовать boolean, number, string как типы локальных переменных, а также любой другой допустимый тип описателя TypeScript.

Параметризованные события и типы аргументов

Любое событие, у которого есть по крайней мере один аргумент, является параметризованным событием. В сравнении с простыми событиями может быть несколько параметризованных событий одного типа в одной шаблонной или комнате.

Вы можете использовать аргументы для дальнейшего уточнения события или для предоставления настроек пользователю. Например, событие столкновения является параметризованным событием, где пользователь может добавить несколько событий столкновения с разными аргументами — шаблонами для проверки столкновений. Встроенный пример ct.js параметризованного события — любое событие действия: действие само по себе является аргументом здесь.

Ct.js поддерживает следующие типы аргументов:

• integer
• float
• string
• boolean
• template
• room
• sound
• tandem
• font
• style
• texture
• action.

Создание категорий событий

Вы также можете добавлять категории внутри module.json в объекте eventCategories, с помощью которых ваши события могут заполнять пользовательские категории вместо встроенных.

Если категория оказывается пустой, она не отображается.

Структура объекта категории, как можно увидеть на предыдущем примере кода, довольно проста:

{
    "main": {
        "name": "ct.place",
        "version": "4.0.0",
        /*...*/
    },
    /* ... */
    "eventCategories": {
        /* Кодовое название вашей категории. Вы используете его для связи событий с ней. */
        "collisions": {
            /* Отображенное название категории */
            "name": "Collisions",
            /* Пример локализованного названия для локали Ru. */
            "name_Ru": "Столкновения",
            /* Отображаемый значок этой категории.
               См. список значков в разделе Meta главного меню ct.js.*/
            "icon": "copy"
        }
    }
}

Совет

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

• lifecycle;
• actions;
• pointer;
• animation;
• misc (по умолчанию).

Написание кода события

Существует два способа определения кода для каждого целевого объекта кода события: внедрение в module.json или размещение в файлах с путями events/eventCode_codeTarget.js. Первый метод подходит для небольших шаблонов и в основном используется для встроенных событий.

Примечание

При написании событий убедитесь, что вы не утекаете переменные за пределы своего события, поскольку это может привести к непредвиденному поведению в других модулях событий или коде пользователя. Если вы объявляете переменные, используйте let и const вместо var, и оберните вашу функцию в { }.

Встраиваемые события

Вот пример кода встроенного события:

{
    "name": "Action press",
    "parameterizedName": "%%action%% press",
    "applicable": ["template", "room"],
    "icon": "airplay",
    "category": {
        "key": "actions",
        "custom": false
    },
    "arguments": {
        "action": {
            "name": "Action",
            "type": "action"
        }
    },
    "codeTargets": ["thisOnStep"],
    "inlineCodeTemplates": {
        /* This matches with codeTargets with its keys*/
        "thisOnStep": "if (ct.actions[/*%%action%%*/].pressed) {\n/*%%USER_CODE%%*/\n}"
    }
}

Написание кода события в отдельных файлах

Вот структура модуля с двумя событиями, одно из которых имеет три целевые файла кода:

catmod
│
└─ docs
│  └─ ... (файлы документации)
│
└─ events
|   │
|   └─ complexEvent_thisOnStep.js
|   └─ complexEvent_thisOnDraw.js
|   └─ complexEvent_rootRoomOnLeave.js
|   └─ simpleEvent_thisOnStep.js
│
└─ index.js
└─ module.json

Вы пишете JS-код в эти файлы так, как есть, без каких-либо оболочек.

Шаблонирование кода события

/*%%USER_CODE%%*/ заменяется кодом, который пишет пользователь в вашем событии.

Вы можете использовать значения аргументов с /*%%argumentName%%*/. Вам, вероятно, понадобится добавить оболочку, чтобы сохранить синтаксис JS действительным, например: var targetEnemy = [/*%%enemy%%*/][0];.

Также есть две дополнительные токены шаблонизации, которые вы можете использовать: /*%%ENTITY_TYPE%%*/ и /*%%ENTITY_NAME%%*/, которые заменяются типом ассета ('room', 'template') и именем этого ассета.

Примечание

Строчные значения автоматически заключаются в кавычки, а также действия, шаблоны и другие имена сущностей.

Совет

Вам нужны больше примеров? Посмотрите на place catmod внутри папки установки ct.js > data > ct.libs > place.