Fields Overview
Каждый компонент в Thing-Editor имеет свой список редактируемых полей, отображаемых в окне Properties
)
Для того, чтобы свойство компонента стало видимым в редакторе свойств, необходимо добавить компоненту описание (мета-данные) этого свойства. Простейшее описание свойства можно найти в компоненте 'Bunny' в самом низу.
/// #if EDITOR
__EDITOR_editableProps(Bunny, [ //list of editable properties
{
name:'gravity',
type:Number,
default: 1,
step: 0.01
}
]);
/// #endif
Данный блок описывает одно единственное редактируемое свойство gravity, имеющее числовое значение (тип Number).
Так как необходимость в описании редактируемого поля есть только на этапе разработки игры в редакторе, и нет смысла хранить это описание в результирующей сборке игры, описание обернуто в теги условной компиляции /// #if EDITOR, /// #endif. Javascript код, заключенный в такие теги будет вырезан при сборке игры. Если забыть добавить эти теги, то игра не будет работать в финальном билде с ошибкой Uncaught ReferenceError: __EDITOR_editableProps is not defined is undefined., так как функция __EDITOR_editableProps существует только в редакторе.
В зависимости от типа редактируемого поля, описание поля может иметь дополнительные параметры, описанные в списке типов. Например min, max, step,
Наилучшим примером описания редактируемых полей является исходный код встроенных компонентов Thing-Editor. Если вы видите в редакторе редактируемое свойство, поведение которого вы хотите повторить в своем компоненте, посмотрите описание этого поля в исходном коде.
Описание редактируемых полей представляет собой массив объектов, каждый из которых описывает одно редактируемое поле, и может содержать следующие свойства (атрибуты):
(Обязательный атрибут описания редактируемого поля.) Имя, по которому значение редактируемого поля будет присваиваться и читаться из объекта сцены. Если имя поля начинается с двух знаков подчеркивания "__", то такое поле считается полем хелпером редактора. Значение данного поля сохраняется в файлах сцен на этапе разработки, но вырезается из финального билда игры. Примером такого поля является поле __lockSelection, компонента Container, отключающее возможность выделения объекта при клике по сцене. Так как выделение объектов это функция редактора, отсутствующая в финальной игре - данное поле вырезается из финального билда.
Если имя поля начинается с трех знаков подчеркивания "___" такое поле считается временным полем. Оно не сохраняется в файлах сцены и не попадает в финальный билд игры. Значение этого поля теряется при каждом запуске игры. Примером такого поля является поле ___id, компонента Container. Данное поле хранит временный уникальный идентификатор объекта сцены, отображаемый в дереве сцены. Идентификатор помогает разработчику сопоставлять объекты в дереве редактора с объектами, отображаемыми javascript отладчиком браузера. Другой способ отключить сохранение поя в файл - установить notSerializable в true.
Редактор свойств не поддерживает вложенность полей при сохранении/загрузке сцен. Некоторые свойства PIXI.js объектов, как например scale.x или style.fontSize являются полями, вложенными в промежуточный объект. Таким компонентам добавлены свойства-посредники - 'scale.x' 'style.fontSize', геттером и сеттером которые пробрасывают значение по нужному пути. Эти свойства-посредники используется при сохранении/загрузке (сериализации/десериализации) сцен из файлов, и при редактировании поля в окне редактора свойств. В javascript коде, следует обращаться к таким полям как обычно, container.scale.x, text.style.fontSize игнорируя псевдонимные геттер и сеттер (
container['scale.x'];.
(Обязательный атрибут описания редактируемого поля.) Тип редактируемого поля. Допустимые значения: Number, String, Boolean, 'rect', 'color', 'btn', 'splitter', 'ref', 'call', 'data-path'
Подробно эти типы описаны в разделе Типы редактируемых полей Также, каждый из типов имеет свое описание пользовательского интерфейса в Редакторе свойств
Значение поля по умолчанию. Это значение будет присвоено полям вновь добавленного на сцену объекта. Если значение поля, у объекта на сцене, равно значению по умолчанию, такое значение не сохраняется в файл при сохранении сцены, так как при загрузке сцены поля без значения заполняются значениями по умолчанию.
Скрывает редактируемое поле в редакторе свойств, по некоторому условию. Значением данного атрибута является функция, принимающая объект сцены как аргумент, а ее возвращаемое значение определяет, будет ли описываемое редактируемое поле скрыто или нет. Значение true делает поле видимым.
Например, свойство shapeLineColor (цвет линии), компонента Shape, скрыто, если толщина линии 'shapeLineWidth' равна нулю:
{
name: 'shapeLineColor',
basis: 16,
type: Number,
default: 0xFFFFFF,
min:0,
max:0xFFFFFF,
visible:(o) => { // hide line color when line is zero sized
return o.shapeLineWidth > 0;
}
},Javascript код, приведенный выше, взят из исходного кода компонента Shape.
Блокирует редактирование поля по некоторому условию. Значением данного атрибут является функция, принимающая объект сцены как аргумент, а ее возвращаемое значение определяет, будет ли описываемое редактируемое поле заблокировано для редактирования разработчиком игры или нет. Значение true блокирует редактирование.
Например, свойство name, компонента Container, заблокировано для редактирования у корневых объектов сцены:
{
name: 'name',
type: String,
disabled:(node) => {
return node.parent === game.stage;
}
}Javascript код, приведенный выше, взят из исходного кода компонента DisplayObject.
Значение true - отключает сохранение значения описываемого поля в файл, при сохранении сцены.
Значение true - отключает создание анимации для данного поля при его редактировании у MovieClip.
Подсветка важных полей в редакторе свойств, для удобства.
Флаг переопределения описания редактируемого поля родительского класса. Thing-Editor проверяет имена описываемых редактируемых полей на уникальность, для раннего выявления ошибок разработки. В случае, когда дочерний класс должен переопределить свойства уже описанного в базовом классе редактируемого поля, такое переопределение должно иметь данный флаг override, отключающий проверку уникальности имен для данного конкретного описания поля.
Например, компонент Text скрывает унаследованное поле image:
{
name: 'image',
type: String,
override: true,
visible:() => {}
},Javascript код, приведенный выше, взят из исходного кода компонента Text.
Позволяет добавить проверку значения редактируемого поля и отобразить предупреждение, в случае, если значение не верное.
Позволяет модифицировать/исправлять вводимое в редакторе свойств данного поля значение.
Например, свойство name, не должно содержать некоторые зарезервированные символы. parser функция заменяет такие символы на знаки подчеркивания при вводе их в редакторе свойств:
{
name: 'name',
type: String,
parser:(name) => {
return name && name.replace('.', '_').replace('#', '_').replace('`', '_').replace(',', '_');
}...
}Javascript код, приведенный выше, взят из исходного кода компонента DisplayObject.
Добавление данного атрибута преобразует редактируемое поле в выпадающий список. Подробнее о работе с выпадающими списками. Значение атрибута должно представлять из себя массив Array, содержащий список объектов вида:
{
name: 'Читаемое имя, которое отобразится в списке',
value: 1 //значение, которое будет присваиваться объекту при выборе данного элемента в списке.
//значение может иметь любой тип, допустимый для описываемого редактируемого поля.
}Простым примером использования выпадающего списка является поле style.fontWeight, компонента Text
{
name: 'style.fontWeight',
type: String,
select: [
{name: 'normal', value: 'normal'},
{name: 'bold', value: 'bold'},
{name: 'bolder', value: 'bolder'},
{name: 'lighter', value: 'lighter'}
],
default: 'normal'
},Javascript код, приведенный выше, взят из исходного кода компонента Text. В данном примере отображаемые имена совпадают со значениями, которые присваивается полю при выборе.
Список выбираемых значений может быть динамическим. Для этого аттрибут select должен являться функцией, возвращающей массив c элементами списка в том же формате что описан выше.
В Thing-Editor существуют несколько функций-фабрик, генерирующих описания редактируемых полей с часто используемыми выпадающими списками, такими как список изображений, звуков и других ресурсов проекта. Данные функции описаны в списке Функции-фабрики для выпадающих списков.
Опциональное поле используемое совместно с атрибутом select. Выпадающий список имеет поле ввода для поиска/фильтрации значений. При каждом открытии списка, предыдущий введенный текст поиска сохраняется. Для того, чтобы разные поля могли сохранять общий текст поиска, описание поля может иметь атрибут filterName. Данное имя используется как ключ для сохранения текста поиска, и может пересекаться между разными полями.
Текстовый аттрибут, добавляющий подсказку для редактируемого поля, в виде кнопки со знаком вопроса. Может содержать форматирование HTML тегами.
Функция, вызываемая перед каждым редактированием значения поля. Может быть использована для проведения проверок или манипуляций с выделенными в данный момент объектами, список которых доступен через глобальную переменную editor.selection.
Функция, вызываемая после каждого редактирования значения поля. Может быть использована для проведения проверок или манипуляций с выделенными в данный момент объектами, список которых доступен через глобальную переменную editor.selection.
Описание редактируемого поля может иметь дополнительные атрибуты, зависящие типа поля. Данный атрибуты описаны в описании типов полей ниже.
Числовое свойство. Подробнее: Числовое редактируемое свойство Дополнительные атрибуты:
Минимальное значение редактируемого поля.
Минимальное значение редактируемого поля.
Шаг изменения значение редактируемого поля. По умолчанию имеет значение 1.
Определяет систему исчисления, в которой числовое значение поля будет отображаться в редакторе свойств. По умолчанию имеет значение 10.
Отключает проверку на NaN для описываемого редактируемого свойства. Подробнее: Автоматическая проверка на NaN
Текстовое свойство. Подробнее: Строковое редактируемое свойство Не имеет дополнительных атрибутов.
Булево свойство. Подробнее: Булево редактируемое свойство Не имеет дополнительных атрибутов.
Свойство данного типа является простым объектом со свойствами {x, y, w, h}. Используется для определения прямоугольной области. Для удобства это свойство отображается в виде прямоугольника, в Viewport при выделении объекта, которому это свойство принадлежит. Дополнительные атрибуты:
Включает возможность присвоения свойству пустого значения null.
Задают минимум и максимум для x, y, w, h параметров прямоугольной области.
Включает/отключает вращение прямоугольной области, отображаемой на экране при вращении самого объекта.
Включает/отключает масштабирование прямоугольной области, отображаемой на экране при масштабирование самого объекта.
Свойство данного типа имеет числовое значение, однако, в редакторе свойств оно отображается как элемент выбора цвета. Значение представляет собой число, с закодированной 3 байтовой RGB информацией цвета.
Редактируемое свойство данного типа не присваивает значения объекту, и представляется в виде кнопки, расположенной в редакторе свойств. Дополнительные атрибуты:
Всплывающая подсказка, отображаемая при наведении курсора на кнопку.
Код горячей клавиши, для данной кнопки. Если горячая клавиша требует удержания Ctrl, то к данному коду следует прибавить 1000.
Функция, вызываемая при нажатии кнопки. Функция будет вызвана для каждого выделенного в данный момент объекта сцены, при этом выделенный объект будет передан ей в качестве аргумента.
Разделитель группы редактируемых полей. Принято, что каждый компонент начинает описание редактируемых полей с разделителя. Однако, разделителей может быть больше, либо он может отсутствовать вовсе, по усмотрению разработчика. Дополнительные атрибуты:
Заголовок, который будет отображен в заголовке группы.
Не редактируемое поле - ссылка на объект. Поля данного типа введены для того, чтобы автоматически чистить ссылки при переиспользовании объектов. Подробнее: Пулинг объектов. При удалении объекта, Thing-Editor проверяет объект на наличие ссылок на другие объекты сцены. Все ссылки должны быть очищены в методе onRemove, либо для ссылки должно быть описано поле 'ref', для автоматической очистки. Это помогает избежать ошибок при разработке.
Функция, вызываемая при клике по данному полю в редакторе свойств.
Редактируемые поля данного типа имеют строковое значение, представляющее собой текстовый путь к функции или методу, для вызова оных при наступлении некоторого события. Подробнее: Callback редактор. Методы и функции, имя которых начинается со знака подчеркивания, считаются приватными, и невидимы для визуального редактора путей, однако, такие имена можно вписать в поле вручную, при необходимости. Функции и методы, имена которых начинаются с заглавной буквы считаются конструкторами, и не доступны для использования как целевых в редакторе путей, однако, при необходимости такие имена также можно вписать в поле вручную. При создании собственных компонентов, разработчик может управлять видимостью методов и объектов в редакторе путей при помощи маркеров видимости и приоритета в редакторе путей.
Редактируемые поля данного типа имеют строковое значение, представляющее собой текстовый путь к javascript переменной, для чтения или записи значения заданной переменной из компонента. Подробнее: Data-Path редактор Дополнительные атрибуты:
Данный атрибут позволяет проверить значение, расположенное по указанному пути на валидность. Чаще всего данная проверка применяется, когда компоненту необходимо указать путь к объекту, имеющему определенный тип. Примером использования такой проверки может служить описание поля container компонента Spawner:
{
name:'container',
type: 'data-path',
isValueValid: (o) => {
return (o instanceof Container);
}
},Javascript код, приведенный выше, взят из исходного кода компонента Spawner. Данное поле должно указывать на объект, имеющий тип Container, иначе значение не будет принято как целевое в редакторе путей.
При создании собственных компонентов, разработчик может управлять видимостью методов и объектов в редакторе путей при помощи маркеров видимости и приоритета в редакторе путей.
Генерирует список значений для выпадающего списка, содержащий все звуки, имеющиеся в проекте.
startsWith - позволяет отфильтровать элементы списка, указав стартовую часть имени звуков (подпапку), которые будут доступны в списке. canBeEmpty - делает возможной очистку значения редактируемого поля (добавляет пустой элемент в начало списка).
Как пример, данная функция используется для описания редактируемого поля sndClick, в компоненте Button:
{
type: String,
select:window.makeSoundSelector(),
name: 'sndClick'
},Javascript код, приведенный выше, взят из исходного кода компонента Button.
window.makePrefabSelector ( startsWith : String = null, canBeEmpty : Boolean = true, filter : Function<>:Boolean = null )
Генерирует список значений для выпадающего списка, содержащий префабы, имеющиеся в проекте.
startsWith - позволяет отфильтровать элементы списка, указав стартовую часть имени префабов (подпапку), которые будут доступны в списке. canBeEmpty - делает возможной очистку значения редактируемого поля (добавляет пустой элемент в начало списка). filter - дополнительный, более гибкий фильтр. Функция, получающая сериализованные данные префаба. Возвращаемое булево значение определяет, будет ли префаб доступен в выпадающем списке.
Как пример, данная функция используется для описания редактируемого поля prefabToSpawn, в компоненте Spawner:
{
name: 'prefabToSpawn',
type: String,
select:window.makePrefabSelector(undefined, false),
important:true
},Javascript код, приведенный выше, взят из исходного кода компонента Spawner.
window.makeImageSelectEditablePropertyDescriptor ( name : String, canBeEmpty : Boolean, important : Boolean, filterName : String )
Генерирует полный дескриптор редактируемого поля, которое в конечном счете имеет вид выпадающего списка со всеми изображениями, имеющимися в проекте. name - имя редактируемого поля. canBeEmpty - делает возможной очистку значения (добавляет пустой элемент в начало списка). important - значение присваиваемое атрибуту important. filterName - значение присваиваемое атрибуту filterName.
Как пример, данная функция используется для описания редактируемого поля image, в компоненте Sprite:
...
window.makeImageSelectEditablePropertyDescriptor('image', false, true),
...Javascript код, приведенный выше, взят из исходного кода компонента Sprite. Вызов функции вставлен непосредственно в список описания редактируемых полей, так как функция генерирует полный дескриптор редактируемого поля, а не массив со списком выбираемых элементов.
Генерирует дескриптор кнопки, для переключения компонента в режим предпросмотра. При нажатии этой кнопки в редакторе свойств, будет вызван метод компонента __goToPreviewMode, а при повторном нажатии или снятии выделения с компонента, будет вызван метод __exitPreviewMode.
title - текст, который будет отображен на кнопке. helpUrl - ссылка на страницу документации, которая будет открыта при нажатии клавиши F1.
Как пример, данная функция используется в компоненте Trigger, для предпросмотра триггера в неактивном состоянии:
...
window.makePreviewModeButton('Preview switched', 'components.Trigger#preview-switched'),
...Javascript код, приведенный выше, взят из исходного кода компонента Trigger. Вызов функции вставлен непосредственно в список описания редактируемых полей, так как функция генерирует полный дескриптор редактируемого поля (кнопки).
Для того чтобы скрыть или выделить объект в редакторе путей, можно присвоить объекту специальное свойство - маркер, имеющее одно из зарезервированных Thing-Editor имен:
___EDITOR_isHiddenForChooser : Boolean Скрывает объект из списка выбора как для редактора пути к методу, так и для редактора пути к данным.
___EDITOR_isHiddenForCallbackChooser : Boolean Скрывает объект из списка выбора для редактора пути к методу. В редакторе пути к данным объект остается доступным.
___EDITOR_isHiddenForDataChooser : Boolean Скрывает объект из списка выбора для редактора пути к данным. В редакторе пути к методу объект остается доступным.
___EDITOR_isGoodForChooser : Boolean Выделяет объект в списке редактора пути к данным и редактора пути к методу.
___EDITOR_isGoodForCallbackChooserchooser : Boolean Выделяет объект только в списке редактора пути к методу.
*___EDITOR_ChooserOrder : Number Изменяет приоритет объекта в списке выбора. Чем больше число, тем выше объект будет находиться в списке выбора. При этом объекты сцены имеют приоритет по умолчанию равный 100000, редактируемые поля компонентов - 10000, а объекты выделенные маркером видимости - 100, все остальные объекты и свойства - 0. Кнопка возврата из списка имеет приоритет 10000000.