Написание записей руководства

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

Это руководство объясняет, как написать запись руководства и настроить её в игре, а также даёт полезные советы по созданию качественных записей. После этого, если вы хотите узнать, как сделать pull request для вашей новой записи, ознакомьтесь с Git for the SS14 Developer.

Записи руководства состоят из двух частей: файла .xml для содержимого самого руководства и YAML-прототипа, который определяет метаданные о самом руководстве. Сначала мы разберём файл, из которого состоит содержимое руководства.

Написание руководств

Все записи руководства хранятся в пути /Resources/ServerInfo/Guidebook/ в основном репозитории. Структура файлов самих руководств должна примерно соответствовать структуре самих записей, хотя это и не обязательно. Самый важный аспект - просто убедиться, что файлы примерно организованы.

Сами записи по сути представляют собой обычные текстовые файлы с некоторыми дополнительными тегами, используемыми для стилизации. Единственная обязательная часть записи - тег <Document>.

Таким образом, простейшая запись, которую вы можете создать, выглядит так:

<Document>
</Document>

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

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

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

Пример

Вот пример записи руководства, magboots.xml

<Document>
# Магнитные сапоги: человек, миф, легенда
Мы знаем, что магнитные сапоги потрясающие, но насколько именно? Ответ довольно очевиден: [color=#ff0000]чрезвычайно.[/color]
  
## Узрите
<Box>
<GuideEntityEmbed Entity="ClothingShoesBootsMag" Caption="Идеально"/>
</Box>

## Вдобавок
<Box>Магнитные сапоги также круты по следующим причинам:</Box>
- Они бывают разных цветов.
- Они заставляют меня чувствовать себя уютно и тепло.
- Они следят за тем, чтобы я не улетел в космос.

Вам не превзойти энергичность магнитных сапог.
</Document>

И вот как это выглядит в игре: markup-example.png

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

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

Box

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

Он имеет следующие свойства:

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

Table

Тег <Table> можно использовать для создания таблицы с заданным количеством столбцов. Вы можете построить таблицу, используя этот тег вместе с тегами <Box> и <ColorBox>.

<ColorBox> - это вариация <Box>, которая располагается на PanelContainer. Для целей руководства это просто означает, что его можно использовать для обозначения отдельных ячеек таблицы. Вы можете использовать свойство 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>

И вот как это выглядит в игре: guidebook-table-example.png

CommandButton

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

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

Он имеет следующие свойства:

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

GuideEntityEmbed

Тег <GuideEntityEmbed> позволяет встраивать внутриигровые прототипы в руководство. В зависимости от того, как он настроен, вы даже можете взаимодействовать с ними и осматривать их.

Он имеет следующие свойства:

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

Полезные советы Эмо: Если вы не видите определённый текст осмотра или взаимодействия у вашей встроенной сущности, вероятно, это потому, что ваша логика находится на сервере.

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

GuideReagentEmbed

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

Он имеет следующие свойства:

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

GuideReagentGroupEmbed

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

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

Он имеет следующие свойства:

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

ProtoTag

ProtoTag - это формат richtext, который берёт информацию о (неабстрактном) прототипе напрямую из кода сущности. Это можно использовать для обеспечения будущей совместимости страницы руководства, которая может измениться позже - поскольку он всегда будет искать данные из самой сущности, вам не придётся обновлять никакую информацию в вашем руководстве.

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

Warning

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

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

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

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

Каждая запись состоит из одного прототипа с несколькими переменными, которые вы можете задать. Вот пример прототипа для записи, которую мы только что написали:

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

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

Полезные советы Эмо: Теперь, когда вы написали свою запись и создали прототип, вы можете открыть руководство и просмотреть её.

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

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

id

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

name

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

Вы можете узнать больше о локализации здесь.

text

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

priority

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

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

children

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

Внутриигровая интеграция

Полезный способ сделать записи руководства более заметными для игроков - использовать компонент GuideHelpComponent. Когда сущности с этим компонентом осматриваются, в правом нижнем углу окна осмотра появляется небольшой блок в виде знака вопроса, и при нажатии на него открывается запись, указанная в компоненте.

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

Просто добавьте компонент к соответствующим прототипам и добавьте соответствующие 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
  #это та часть, которую вы добавляете
  - type: GuideHelp
    guides:
    - MachineUpgrading #это руководство, которое открывается

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

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

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

Subpages