Навык читать и понимать XML-структуру интерфейса Обливиона

XML – Расширяемый Язык Разметки, или же мета-язык, описывающий информацию, разбивая её на маленькие элементы и используя теги <>. Сам по себе он ничего не делает, лишь помогает организовать данные.

Продолжение данного гайда смотрите по ссылке. В нем вы узнаете, как создать свой компонент интерфейса на примере мода в духе Primary Needs.

1. Основы XML

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

…

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

2. Правила XML

В XML мы используем теги (tags), чтобы вставлять в них всё что-угодно. Другими словами, значение тега определяется автором кода (или в нашем случае Бесездой). Лишь немного элементов уже пред-определены заранее, то бишь, у которых уже есть предписанное значение, поскольку некоторые символы (certain characters), такие как <and >, уже зарезервированы языком, то есть, они уже используются для обозначения тегов.

Если бы у них не было зарезервированного значения, они бы означали < (меньше чем), > (больше чем), &quote; (цитата) и & (амперсанд).

Такие штуки называются сущностями (entities) или ярлыками (shortcuts), и Бесезда использует разработанные ей сущности чтобы ссылаться на элементы, которые, судя по всему, зашиты в код (hardcoded). Напр. булевы элементы (bool) имеют значения &true; или &false.

Поскольку это не язык сам по себе, не так много нужно запоминать при чтении кода, созданного не Бесездой. Поэтому…

А) все элементы следует закрывать закрывающим тегом

Цитата:

<tag>content</tag>

Или быть само-закрывающим пустым-элементом тегом:

Цитата:

<tag/>

Последнее обычно используется в комбинации с атрибутами, смотри ниже.

Б) теги чувствительны к регистру (case-sensitive) и должны быть правильно вложены (properly nested):

Цитата:

<Tag> content </tag> : неверно

<tag1><tag2> content </tag1></tag2> : неверно

<tag1><Tag2> content </Tag2></tag1> : супер

В) все документы должны иметь корневой тег (root tag), структура документа начинается с одного тега, который держит все остальные:

Цитата:

<A>

<B>

</B>

</A>

<C>

</C>

Неверно, потому что два элемента А и С оба являются корневыми.

Цитата:

<A>

   <B>

       <D>

       </D>

   </B>

   <C>

   </C>

</A>

Верно.

Отношения между разными элементами документа XML часто описывается как семейное древо (family tree). Элементы на одном и том же уровне иерархии названы сиблингами\брат-сестра (siblings). Элемент, содержащий другой, является «родителем» (parent) ему, а тот – ребенком (child) или дочерним элементом. Внуки и деды прилагаются.

Г) некоторая информация об элементах может содержаться в самом теге (parked inside the tag), а не в под-элементе. Такой способ размещения информации называется атрибутом (attribute). К примеру, элемент, обозначенный ниже, атрибуирован именем через атрибут:

Цитата:

<text name="NameOfTextElement">
</text>

Информация, содержащаяся в атрибуте, представляет собой мета-данные такого типа, которым благодаря своей уникальности незачем содержаться в под-элементах.

Д) комментарии в коде добавляются следующим образом:

Цитата:



3. XML в играх Бесезды: Схематизм

До-скайримовские игры Бесезды на Gamebryo свои меню и компоненты интерфейса (HUD components) организуют в элементы внутри документа XML. Элементы и их иерархия переводятся в то, что игрок видит на экране с помощью собственного XML-парсера игры. Для этого парсер присваивает значение элементам, тегам и тому, что между ними. XML поддерживает обширный синтаксис, а Бесезда наполняет его словарем. Но словарь этот она нигде особо не публиковала, так что для моддинга это проблема.

Такой тип словаря, говорящий нам какие теги в структуре XML валидны и значимы, называется схемой XML. К счастью для нас некоторые умные люди на КС Вики (CS Wiki) выяснили большую часть этой схемы в Обливионе. Конечно, надо с осторожностью подходить к тому, чтобы автоматически полагать, будто работающие вещи в Обливионе по определению будут работать в F3 или New Vegas, но тем не менее я опишу именно схему Обливиона.

У Бесезды элементы XML в целом делятся на три больших типа: обьектные элементы (object elements), элементы свойств (property elements), оперантные элементы (operator elements). Вот все они в отрывке из stats_menu.xml, линии 1415-1420:

Цитата:

<image name="stats_hunger_meter">

                   <locus> &true; </locus>

                   <filename> Interface\Stats\rad_meter_bracket.dds </filename>

                   <zoom>

                       <copy src="parent()" trait="zoom"/>

                    </zoom>

...

</image>

В этом коде главный элемент декларирует появление нового компонента изображения, которое добавлено в меню статов. Такие вещи называются обьектными элементами, которые вводят новые обьекты в меню или интерфейс. Само собой разумеется, они немедленно получают имя с помощью именного атрибута (name attribute), чтобы оперантные элементы и функции расширителя скриптов могли ссылаться на них.

Уровнем ниже мы можем видеть, что кое-что следует разъяснить в этом новом компоненте, а именно какую текстуру он использует (тег <filename>) и его процент масштабирования. Другие свойства включают размеры и положение элемента объекта. Элементы, обозначающие свойства обьектных элементов, именуются элементами свойств (property elements). Также они известны как характеристики (traits).

Во множестве случаев содержимое элементов свойств может быть абсолютной величиной, либо числом, либо строкой (string). Путь файла (filepath), к примеру. Однако скопированные из свойств других обьектных элементов эти значения могут также высчитываться в течение игровой сессии и\или подвергаться воздействию математических и обуславливающих (conditional) элементов. В приведенном выше примере процент масштабирования изображения копируется из процента масштабирования его собственного родительского элемента.

Элементы, которые создают такие «живые» операции на элементах свойств, называются оперантными элементами (operator elements). Они часто включают использование src и trait атрибутов, чтобы ссылаться на другие свойства. Src будет в большинстве случает ссылаться на обьектный элемент или на нечто глобальное, когда как trait ссылается на свойства.

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

Цитата:

<image name="stats_headline_h1">

<include src="line.xml"/>

</image>

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

Снова пример из stats_menu:

Цитата:

<_meter_height> 38 </_meter_height> 

<height> <copy src="StatsMenu" trait="_meter_height"/> </height> 

3.1 Обьектные Элементы

<rect> определяет прямоугольную область на экране. Сам по себе элемент невидим, но его свойства влияют на любые дочерние элементы, которые он имеет. В примере ниже текстовый элемент, являющийся дочерним элементом к прямоугольному элементу, наследует свойство <systemcolor>.

Цитата:

     <rect name="SneakMeter">

       <id> &noglow_branch; </id>

       <systemcolor>&hudmain;</systemcolor>

       <width> 356 </width>

       <height> 34 </height>

       <text name="sneak_nif">

           <width>128</width>

           <height>128</height>

           <justify>&center;</justify>

       </text>

   </rect>

<text> как вы можете представить, определяет текстовую компоненту.

<image> определяет прямоугольную область, которая заполняется текстурой.

Цитата:

    <image name="filled_checkbox">

               <visible>&false;</visible>

               <alpha>0</alpha>

               <filename>Interface\Shared\Marker\glow_square_filled_small.dds</filename>

               <texatlas> Interface\InterfaceShared.tai </texatlas>

               <width>26</width>

               <height>26</height>

               <x>-20</x>

               <y>3</y>

           </image>

<nif> определяет анимацию; используется в loading_menu.xml, а так же в полоске дыхания в интерфейсе:

Цитата:

<nif name="BreathMeter">

       <filename>Interface\HUD\AirTimer01.NIF</filename>

       <animation>Forward</animation>

       <visible>&false;</visible>

       <alpha>0</alpha>

       <width>64</width>

       <height>64</height>

       <systemcolor>&hudmain;</systemcolor>

   </nif>

<menu> - корневой элемент файлов XML, связанных с меню.

Цитата:

<menu name="HUDMainMenu">

   <class> &HUDMainMenu; </class>

   <stackingtype> &does_not_stack; </stackingtype>

   <visible>&false;</visible>

    ... и т.д.

</menu>

Другие обьектные элементы, встречающиеся в ваниле, включают <hotrect> и <template>. Как обьектный элемент, <template> скорее всего служит той же функции, которую выполняет пользовательский элемент свойства: хранит информацию, которая может быть использована в любом другом месте. Имеет смысл. Но в различиях между <rect> и <hotrect> я не уверен (см. stats_menu.xml).

Цитата:

     <template name="stats_list_template">

           <hotrect name="stats_list_template_item">

               <include src="list_box_template.xml"/>

3.2 Элементы Свойств

Элементы свойств или характеристики определяют свойства их родительских элементов. Они могут иметь буквальные значения (числа, строки, булевы значения &true; или &false;) или состоять из формул, которые используют оперантные элементы.

Цитата:

<width> 450 </width> vs <width> <copy src="screen()" trait="width" />

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

А) размер и позиция

<x> и <y> определяют позицию родительского элемента на оси X & Y на экране

<width> и <height> самоочевидны: широта и высота соответственно.

<locus> булев элемент. Если &true; позиционирование X/Y дочернего элемента будет зависеть относительно родительского элемента, если же значение локуса ложно, то позиция дочернего элемента будет абсолютной.

Б) отрисовка (rendering)

<visible> булев элемент, включает или выключает отображение элемента, а также его дочерние элементы. На скрытый элемент нельзя нажать мышью, но можно активировать через скрипт.

<alpha> числовой элемент, определяющий прозрачность родительского элемента, значение установлено в периоде от 0 до 255 (нормальная, полная видимость)

<depth> числовой элемент, определяющий приоритет перекрывающих элементов. Элемент с более высоким значением будет отрисован поверх остальных. Изначально, дочерние элементы имеют более высокую глубину, чем родительские.

<clips> булев элемент, гарантирующий скрытие элемента, если родительское свойство <clipwindow> истино, при условии что элемент находится за пределами размеров родительского элемента.

<systemcolor> берет сущности (обычно &hudmain;), которые определяют цвет главного интерфейса, например пипбоя.

В) клики и наведение мышью

<target> булев элемент, определяющий будет ли элемент (rect или изображение) реагировать на ввод игроком (player input). Если истино, то свойство наведения мышью будет соответствующе установлено движком, и если элемент имеет свойство <id>, клик по нему установит его свойство на «кликнуто» и воспроизведет специфицированный звук нажатия мышью (clicksound).

<clicked> числовой элемент, чье значение меняется на 1 на один фрейм после того, как на элемент кликнули мышью.

<clicksound> числовой элемент, определяющий какой именно звук будет сыгран, когда на элемент кликнули мышью.

<mouseover> другой числовой элемент, который автоматически меняет значение на 1 игровым движком, когда на элемент навели мышью. В противном случае приобретает значение 0.

Г) уникальные свойства элементов-изображений

<filename> определяет путь файла для текстуры, которую будет отображать элемент, находящийся в папке Data\Textures.

<zoom> числовой элемент, определяющий процент масштабирования. Если больше 100, увеличит источник текстуры, если 0, то спрячет изображение. Если -1, то изображение будет изменено таким образом, чтобы втиснуться в ширину и высоту элемента без обрезания краёв.

<filewidth>, <fileheight> это элементы только для чтения. Их значение устанавливается игровым движком под актуальные ширину и высоту загруженной текстуры (в пикселях), после того как было применено масштабирование. Если масштабирование равно -1, значение этого элемента равно 0.

<tile> булев элемент, если истинно, а широта или высота элемента больше текстуры, 2 или более текстур будут собраны в одном изображении.

<cropx>, <cropy> определяет точку текстуры, которая будет помещена в верхний левый угол изображения. Пример смотрите здесь.

<texatlas> судя по всему ссылается на файл с расширением .tai, который, очевидно, содержит атласную текстуру, файл, хранящий несколько текстур.

Д) уникальные свойства текстовых элементов

<string> содержит текст, который должен быть отображен.

<red>, <green> и <blue> числовые элементы, которые можно использовать чтобы определить цвет текста. Ранжируется от 0 до 255 (также работает на изображениях!)

<font> числовой элемент, определяющий, какой шрифт следует использовать в соответствии со шрифтами, перечисленными в ini-файле игры. Если он отсутствует или недействителен, по умолчанию будет использоваться шрифт 1.

<justify> элемент, определяющий, где будет начинаться текст относительно х-кординаты элемента. Значения "&left;", "&center;" и "&right;".

<wrapwidth> обозначает максимальную широту элемента в пикселях. Если текст превышает эту широту, он раздваивается в несколько множественных линий.

<wraplines> максимальное число отображаемых линий.

Вот здесь пример более продвинутого использования элементов <IsHTML>, <PageNum> и <PageCount>, которые должны позволить отобразить текст, разделенный на страницы.

Е) уникальные свойства элементов меню

<class> определяет какой класс внутренного меню использовать для обработки ввода и вывода в меню. Значения могут быть числовыми и соответствовать кодам, использованным в MenuMode, но обычно они определены как сущности, соответствующие названиям меню, такие как HUDMainMenu; или &StatsMenu; . Если введенное значение не соответствует классу меню, меню откроется, но не будет обновляться или принимать вводные значения.

<stackingtype> определяет, блокирует ли меню использование других меню или элементов управления игровым процессом, когда оно открыто. Большая часть блокирует такие взаимодействия и маркирована как "&no_click_past;".

<menufade> определяет длительность эффекта постепенного появления/исчезновения (fade in/out) в секундах, когда меню открывается и закрывается. Меню не обновляет и не принимает ввод, когда активен эффект.

Ж) общие и разные свойства

<id> по идее связано с меню тегом <class>, в котором определяет, какой части собственной классовой системы этого меню соответствует элемент, чтобы принять и обновить то, что вводит туда игрок (updating and accepting player input). Примеры схемы Обливиона ограничены типами меню, характерными для этой игры, так что не очень ясно как этот элемент работает в контексте меню Фоллаутов.

<user#> : типы элементов, начинающиеся с пользователя, обычно не являются частью схемы XML, но могут распознаваться определенными классами меню. Как и <id>, кажется, что их значение во многом зависит от меню, в котором они находятся. Если верить странице обсуждения, они, похоже, предназначены для использования в качестве своего рода заполнителей (placeholders), а не как ссылки на структуру меню на несколько уровней ниже, так что это может быть полезным при моддинге.

Другие незатронутые элементы свойств можно найти здесь.

3.3 Оперантные элементы

А) как они работают

Операторы производят конкретные операции на элементах свойств, используя либо буквенные значения...

Цитата:

<rect>                       

<x>                        

   <copy> 10 </copy>       

     <add> 5 </add>          

</x>

</rect>

...Либо другие свойства как их второй операнд, с атрибутами 'src' и 'trait' в самозакрывающемся теге:

Цитата:

<rect name="thiselement">

<x>

<copy> 10 </copy>

<add src="anotherelement" trait="y" />

</x>

</rect>

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

Цитата:

<rect name="thiselement">

    <x>

         <copy> 10 </copy>

         <add src="anotherelement" trait="y" />

         <mul> 2 </mul>

         <add>

               <copy> 10 </copy>

               <div src="anotherelement" trait="x" />

         </add>

   </x>

</rect>

Б) возможные значения 'src'

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

Цитата:

<rect name="firstrect">

   <x> 10 </x>

</rect>

<image name="firstimage">

   <x>

      <copy src="firstrect" trait="x" />

   </x>

</image>

Однако присутствуют и «относительные» способы ссылаться на другие свойства, используя значения 'src', которые включают me, parent, sibling(name), и child(name):

Цитата:

<y> <copy src="me()" trait="x" /> </y>

Устанавливает позицию Y (игрек) у элемента такой же как его позиция X (икс).

Цитата:

<x>

<copy src="parent()" trait="x" />

</x>

Устанавливает позицию X (икс) у элемента такой же как у его родителя.

Цитата:

<width>

<copy src="sibling(siblingsname)" trait="width" />

</width>

Устанавливает ширину элемента такой же как у конкретного сиблинга. Если имя сиблинга опущено, то в таком случае по дефолту значение берется у сиблинга, созданного прямо перед оператором.

Дочерний элемент следует тому же синтаксису: вам нужно указать имя, но он также найдет еще более нижние элементы и далее.

Если множество дочерних элементов, «внучатых» элементов и тд. существуют с тем же именем, будет выбрано последнее записанное в документ XML.

И еще кое-что. Src так же может ссылаться на конкретные глобальные свойства, в большинстве случаев используя "screen()" и "io()". В примере ниже элемент интерфейса позиционируется в крайне правой части экрана, устанавливая его позицию X (икс) к ширине "screen()", вычитая из неё элемент своей собственной ширины:

Цитата:

<image name="thisimage">

   <width> 300 </width>

   <x>

       <copy src="screen()" trait="width" />

       <sub src="me()" trait="width" />

   </x>

</image>

io() возможно аббревиатура для ввода\вывода (input/output), так как, судя по всему, служит как средство коммуникации между XML-парсером и скриптами игры. Свойства, скопированные из io, могут быть установлены через скрипт с помощью SetUIFloat и SetUIString. Довольно важный элемент, если планируется включать или позиционировать элементы с помощью скрипта и\или настроек МСМ (для Fallout).

Цитата:

<visible>

<copy src="io()" trait="_MyModVisible" />

</visible>

Этот скрипт означает, что элемент интерфейса, описываемый этим элементом, будет виден, если пользовательское свойство "_MyModVisible" будет включено с помощью функции SetUIFloat в скрипте:

Цитата:

SetUIFloat "HudMainMenu\_MyModVisible" 1

Г) общие операторы

Математические операторы:

<add>, <sub>, <mul> и <div> должны быть самоочевидными. Также доступны <mod> (модуль) и <rand> (случайное число между 0 и содержимым <rand> </rand>).

Логические операторы, все возвращающие сущности со значением &true; (то есть число 2), или &false; (1, или любое другое число):

<onlyif> и <onlyifnot> элементы условия перед ними.

Цитата:

<systemcolor>

    <copy> &hudmain; </copy>

    <onlyifnot>

        <copy src="io()" trait="_MyModAltColorTrait" />

        <eq> 1 </eq>                              

    </onlyif>

</systemcolor>

<and>, <or>, <not> самоочевидны: и, или, не.

Для сравнения чисел и значений у нас есть <lt> (lesser than, меньше чем), <lte> (lesser than or equal to, меньше чем или равно), <gt> (greater than, больше чем), <gte>, <eq> (equals, равно) и <neq> (not equal, не равно).

<min> и <max> устанавливает значение элемента свойства, соответственно минимуму или максимуму самого себя и тому, что находится между тегом.

Цитата:

<x>

<copy src="parent()" trait="x" />

<min> 200 </min> <!—будет 200 или меньше -->

</x>

4. Выводы

Всё это можно считать гайдом по тому, как читать связанные с HUD файлы XML. Даже при понимании синтаксиса XML и большей части вокабуляра Бесезды, все равно потребуется стальное упорство для того, чтобы понять более сложные меню, но этот гайд хотя бы даст базу.

Чтение – очевидное условие для любого желающего написать что-то своё, а написание элемента интерфейса станет уже темой другого туториала.

Пс. Замечания переводчика

К сожалению ссылки, ведшие на CS Wiki, уже мертвы и не имеют смысла. Тем не менее, я оставил их в тексте на случай, если сайт когда-нибудь будет активен снова, или если неофициальная копия сайта (cs.uesp) перенесет эти страницы к себе.

Некоторые неважные или неуместные здесь пассажи (см. на каком именно сайте был опубликован оригинальный туториал) я опустил.

Я придерживался стиля и разметки оригинала, а в скобках оставлял оригинальные термины на случай, если мой перевод не отображает общепринятых в IT переводов данных понятий или пассажей.

ППС. Вообще слово Bethesda обозначает...Вифезду, город в Иудее, который посещал Господь Иисус Христос в эпизоде с исцелением расслабленного. Возникает оторопь: зачем надо было брать это название, если суть всех игр компании ничего общего не имеет с иерофаническим смыслом, закрепившемся за этим названием города?