Написание статей Guidebook

Guidebook — это мощный инструмент для передачи игрокам более сложной внутриигровой информации без необходимости переходить на внешнюю вики. В будущем большая часть информации должна быть перенесена из вики в guidebook в той или иной форме. Это руководство объясняет, как написать статью для guidebook и настроить её в игре, а также даёт полезные советы по созданию качественных статей. После этого, если вы хотите узнать, как сделать pull request для вашей новой статьи, ознакомьтесь с Git for the SS14 Developer. Статьи состоят из двух частей: .xml файла с содержимым самой статьи и YAML prototype, определяющего метаданные о статье. Сначала мы рассмотрим файл, из которого состоит содержимое статьи.

Написание статей

Все статьи хранятся в пути /Resources/ServerInfo/Guidebook/ в основном репозитории. Структура файлов самих статей должна примерно соответствовать структуре самих статей, хотя это не обязательно. Самое важное — просто убедиться, что файлы примерно организованы. Сами статьи — это, по сути, текстовые файлы с некоторыми дополнительными тегами, используемыми для стилизации. Единственная обязательная часть статьи — это тег <Document>. Таким образом, самая простая статья, которую вы можете сделать, выглядит так:

<Document>
</Document>

Любой текст, написанный в пределах тега, будет отображаться в guidebook. Но если вы напишете статью только с обычным текстом, это будет невероятно скучная статья. Чтобы облегчить мою неминуемую смерть, рассмотрите использование (небольшого) разнообразия поддерживаемых markdown-тегов:

# создаёт заголовок
## создаёт раздел
### создаёт подраздел
- создаёт элемент списка
\n создаёт разрыв строки
[color=hex or name][/color] окрашивает текст внутри тегов в указанный hex-цвет или один из 145 пресетов
[bold][/bold] применяет жирное начертание
[italic][/italic] применяет курсивное начертание
[bolditalic][/bolditalic] применяет жирное курсивное начертание (иначе bold и italic переопределяют друг друга)

Пример

Вот пример статьи guidebook, magboots.xml:

<Document>
# Magboots: The man, the myth, the legend
We know magboots are amazing, but just how amazing? The answer is quite clear: [color=#ff0000]extremely.[/color]
  
## Behold
<Box>
<GuideEntityEmbed Entity="ClothingShoesBootsMag" Caption="Perfect"/>
</Box>

## Additionally
<Box>Magboots are also cool for the following reasons:</Box>
- They come in multiple colors.
- They make me feel fuzzy and warm.
- They make sure I don't fly off into space.

You cannot beat the hustle of the magboots.
</Document>

И вот как это выглядит в игре:

Пользовательские элементы управления Guidebook

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

Box

Тег <Box> можно использовать для центрирования части статьи. Это не очень полезно для текста, но может использоваться в сочетании с другими тегами для создания более визуально привлекательной страницы. Он имеет следующие свойства:

Orientation: ориентация элементов внутри блока. Либо «Vertical», либо «Horizontal»
HorizontalAlignment: как блок будет размещён по горизонтали на странице. Может быть «Stretch», «Left», «Center» или «Right»
VerticalAlignment: как блок будет размещён по вертикали на странице. Может быть «Stretch», «Top», «Center» или «Bottom»

Table

Тег <Table> можно использовать для создания таблицы с заданным количеством столбцов. Вы можете создать таблицу, используя этот тег в сочетании с тегами <Box> и <ColorBox>. <ColorBox> — это вариант <Box>, находящийся на PanelContainer. Для целей guidebook это означает, что его можно использовать для обозначения отдельных ячеек таблицы. Вы можете использовать свойство Color, чтобы задать <ColorBox> фоновый hex-код. Таблицы имеют следующие свойства:

Columns: сколько столбцов должно отображаться.
MinForcedColumWidth: абсолютная минимальная ширина, к которой может быть принуждён столбец. По умолчанию 50.

Вот пример таблицы, созданной с помощью XML:

<Table Columns="3">
  <ColorBox Color="#994444">
    <Box>
      HEADER 1
    </Box>
  </ColorBox>
  <ColorBox Color="#449944">
    <Box>
      HEADER 2
    </Box>
  </ColorBox>
  <ColorBox Color="#444499">
    <Box>
      HEADER 3
    </Box>
  </ColorBox>
  <ColorBox>
    <Box HorizontalAlignment="Left" VerticalAlignment="Stretch" Margin="2">
      body 1
    </Box>
  </ColorBox>
  <ColorBox>
    <Box HorizontalAlignment="Left" VerticalAlignment="Stretch" Margin="2">
      body 2 OASDKFA F ASDKF ASD FKASD LFKA SLFKA SL
    </Box>
  </ColorBox>
  <ColorBox>
    <Box HorizontalAlignment="Left" VerticalAlignment="Stretch" Margin="2">
      body 3 BUT IT GOES CRAZY AND OFF THE RAILS OH MY GOD ITS ASDF ASF ASDFASKD FNMXV EWOR QIWEORP SV
    </Box>
  </ColorBox>
</Table>

И вот как это выглядит в игре:

CommandButton

Тег <CommandButton> позволяет встроить кнопку в guidebook. Нажатие на кнопку выполнит команду. Это может показаться бесполезным, но есть много полезных клиентских команд, например, открывающих меню. Обратите внимание, важно не использовать их для админских команд, так как средний игрок, скорее всего, будет сбит с толку. Он имеет следующие свойства:

Text: текст, который будет отображаться внутри кнопки. Поддерживает строки локализации.
Command: полная команда, включая аргументы. Это то, что выполняется при нажатии кнопки.

GuideEntityEmbed

Тег <GuideEntityEmbed> позволяет встраивать внутриигровые prototypes в статью. В зависимости от конфигурации вы можете даже взаимодействовать с ними и осматривать их. Он имеет следующие свойства:

Entity: ID prototype для сущности, которая будет отображаться.
Caption: подпись, отображаемая под сущностью. По умолчанию — имя сущности.
Scale: значение для масштабирования размера встроенной сущности. 2 даст двукратный размер, 0.5 — половинный.
Interactive: можно ли взаимодействовать со встроенной сущностью.
Rotation: угол поворота сущности. Полезно, если вы хотите отобразить определённый ракурс. По умолчанию — на юг.
Init: инициализирована ли встроенная сущность на карте. По умолчанию true.

Полезные советы от Emo: Если вы не видите определённый текст осмотра или взаимодействия на вашей встроенной сущности, вероятно, ваша логика находится на сервере. Все сущности в guidebook существуют только на стороне клиента, что означает, что если вы хотите, чтобы определённый текст осмотра был виден или имел определённый вид, это должно быть определено либо в shared, либо в client коде.

GuideReagentEmbed

Тег <GuideReagentEmbed> создаёт небольшой информационный блок о данном реагенте. Он включает название, описание, физическое описание, рецепты (если есть) и эффекты (если есть). Их можно использовать, если вы хотите предоставить распространённые химикаты и их рецепты в соответствующих местах. Например, размещение embed для Space Cleaner в руководстве уборщика. Он имеет следующие свойства:

Reagent: ID prototype для реагента, который будет использоваться.

GuideReagentGroupEmbed

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

Group: группа, к которой будут относиться все реагенты. Это должно соответствовать значению поля group в ReagentPrototype.

ProtoTag

ProtoTag — это формат richtext, который будет брать информацию о (неабстрактном) prototype напрямую из кода сущности. Это можно использовать для защиты страницы guidebook от устаревания — так как он всегда будет искать данные в самой сущности, вам не придётся обновлять информацию в вашей guidebook. ProtoTag использует формат [protodata="<id>" comp="<component>" member="<member>"/], где id — это ID желаемой сущности, component — компонент, который вы просматриваете, и member — конкретное поле этого компонента. Например, если вы хотите получить информацию о том, сколько энергии потребляет RTG, вы можете сделать [protodata="GeneratorRTG" comp="PowerSupplier" member="MaxSupply"/].

Чтобы эта система работала, ей нужен доступ к этим полям. Любое поле компонента, к которому вы обращаетесь, должно быть помечено атрибутом [GuidebookData] и не может быть приватным.

Вы можете указать опциональный format="<format>" для форматирования полученных данных с помощью метода float.ToString(). Эта страница является хорошим ресурсом для форматирования строк.

Создание записей

Теперь, когда вы создали файл со всем содержимым, вам нужно создать запись для его отображения в игре. Записи — это prototypes, находящиеся в папке /Resources/Prototypes/Guidebook/. Как и раньше, старайтесь группировать руководства и их дочерние элементы вместе, чтобы их можно было легко найти. Каждая запись состоит из одного prototype с несколькими переменными, которые вы можете установить. Вот пример prototype для нашей только что написанной статьи:

- type: guideEntry
  id: Magboots
  name: guide-entry-magboots
  text: "/ServerInfo/Guidebook/magboots.xml"
  priority: 10
  children:
  - Radio

Чтобы убедиться, что она отображается в guidebook, вам нужно также добавить её как дочерний элемент к другой записи.

Полезные советы от Emo: Теперь, когда вы написали свою статью и создали prototype, вы можете открыть guidebook и просмотреть её. Статьи поддерживают hot-reloading, что означает, что вы можете изменить файл, пока ваш локальный сервер запущен, закрыть guidebook, снова открыть его и увидеть изменения.

Все эти поля довольно просты, давайте пройдёмся по ним по одному.

id

Это просто уникальный ID prototype. Просто убедитесь, что он примерно соответствует названию вашей статьи.

name

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

text

Это просто путь к файлу статьи, начиная с директории /Resources/.

priority

Это числовое значение для сортировки статей верхнего уровня. Более высокие значения отображаются первыми. Это не используется, если статьи являются дочерними элементами другой статьи; в этом случае они сортируются по порядку, указанному в поле children.

children

Это список всех других статей, которые отображаются ниже этой на боковой панели. Элементы этого списка должны соответствовать id других статей.

Интеграция в игре

Полезный способ сделать статьи guidebook более заметными для игроков — использовать компонент GuideHelpComponent. Когда сущности с этим компонентом осматриваются, в правом нижнем углу окна осмотра появляется маленький вопросительный знак, и при нажатии открывается статья, указанная в компоненте. Это чрезвычайно полезно для новых игроков и помогает людям быстро переходить к соответствующим руководствам. Просто добавьте компонент на соответствующие prototypes и добавьте соответствующие ID руководств в поле данных guides компонента. Вот пример:

- type: entity
  id: BaseStockPart
  name: stock part
  parent: BaseItem
  description: What?
  abstract: true
  components:
  - type: Sprite
    netsync: false
    sprite: Objects/Misc/stock_parts.rsi
  - type: Item
    size: 1
  #this is the part you add
  - type: GuideHelp
    guides:
    - MachineUpgrading #this is the guide that is opened

Лучшие практики

Вот несколько общих советов по написанию хороших руководств:

Делайте заголовки чёткими и краткими. Игроки не хотят искать то, что им нужно.
Делайте статьи короткими. Вы всегда можете добавить дочерние статьи, если хотите более подробно раскрыть тему.
Используйте блоки, встроенные сущности и цвета текста, чтобы придать статьям визуальный интерес.
- Часто используемый цвет для акцента — #a4885c.
Воздержитесь от включения специфических советов и «мета»-стратегий. Руководство должно быть беспристрастным источником информации.
Статьи должны быть написаны в нейтральном тоне.
Поощряйте взаимодействие с руководством.
- Если ваши встроенные сущности поддерживают это, предложение игроку осмотреть сущность для получения дополнительной информации — полезный способ передачи информации и обучения игроков.