> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ss14.art/llms.txt
> Use this file to discover all available pages before exploring further.

# Краткий курс YAML

Потому что, очевидно, нет хороших.

SS14 использует YAML для определения prototypes. Это как JSON, но на самом деле предназначен для написания существами, основанными на углероде, с умеренным интеллектом, вроде нас с вами.

## Комментарии

Прежде всего, вы можете сделать однострочный комментарий, поставив #; всё после него игнорируется. Пример:

`yml
foo: bar # Look a comment.
`

## Типы данных

Для наших целей в YAML есть что-то вроде 3 типов данных: строки, списки и словари. Если вы знаете о YAML достаточно, чтобы понимать, что это неправда, прокрутите вниз до объяснения.

### Строка

Определить строку легко, просто напишите её.

`yml
hello
`

Отлично, вы мастер YAML, вы определили строку с содержимым hello.

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

`yml
"hello: hi"
`

Всё ещё одна строка.

Двойные кавычки (") допускают escape-последовательности, такие как наш друг \n (новая строка); одинарные кавычки (') — нет.

### Список

Определение списка делается простым добавлением - перед чем-то, например строкой:

\`yml

* A
* B
* C
  \`

Это определяет список с 3 элементами: A, B и C. Вау!
Значения — это обычные строки, и вы можете делать с ними что угодно: кавычки и прочее.

> **Ужасные советы от Ygg:**
> Вы также можете определить YAML инлайн. Вместо вышеуказанного можно написать:
> `yml    [A, B, C]
> `
> **Инлайн YAML по соглашению не рекомендуется**, особенно для определения списков компонентов в сущности. Обычно используется для обозначения простого одноэлементного списка, например:
> `yaml
>    x: [ DoAct ]
> `

### Словарь

И наконец, словари, которые представляют собой просто отображение ключ/значение. Так что можно сделать A равно B и C равно D.
Просто используйте двоеточия (:) для определения, вот так:

`yml
A: B
C: D
`

Вжух.
Значения (и ключи, и значения!) ТАКЖЕ являются обычными строками, так что можно и так:

`yml
"A": "B"
"C": "D"
`

Чудеса современных технологий.

> **Ужасные советы от Ygg:**
> Как и списки, словари также можно определять инлайн.
>
> ```yml theme={null}
> { A: B, C: D}
> ```
>
> Если вы думаете: «Погодите-ка, инлайн YAML — это просто JSON». Вы правы. YAML является надмножеством JSON, и вы можете анализировать JSON-файлы как YAML напрямую, если захотите.

## Вложение вещей

Оказывается, вместо строк можно также использовать словари и списки.

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

Когда у вас есть список, вы можете поместить словарь в элемент, сделав отступ. Так можно сделать следующее:

\`yml

# Like this, first key on the same line.

* A: B
  X: "Y"
  \`

На самом деле это просто имеет смысл.

Точно так же можно поместить список внутрь словаря, но в этом случае список *должен* начинаться на следующей строке:

\`yml
A:

* "X"
* "Y"
* "Z"

B:

* "U"
* "V"
* "W"
  \`

Легко.

И да, можно смешивать:

<Warning>
  Не ждите, что эти примеры prototypes будут актуальными для SS14. Они здесь только для демонстрации синтаксиса.
</Warning>

\`yml

# First, this entire thing is stored in a massive list. That's why there's a -.

# We're looking at one entry, a dictionary.

* type: entity # Simple key/value pairs.
  id: SMES
  name: SMES
  description: Stores power in its super-magnetic cells
  components:
  # AHA! A list in a key. Wow!
  # This list ALSO stores dictionaries.
  * type: Sprite
    sprite: Buildings/smes.rsi
    scale: 2, 2
    layers:
    * state: smes
    * state: smes-display
      shader: unshaded
    # Input lights.
    * shader: unshaded
      state: smes-oc0
    # Charge meter.
    * visible: false
      shader: unshaded
      state: smes-og1
    # Output lights.
    * shader: unshaded
      state: smes-op0
  * type: Icon
    sprite: Buildings/smes.rsi
    state: smes
    \`

## Примечания

YAML на самом деле имеет гораздо больше типов данных. YAML также является полным беспорядком. Есть как минимум 10+ способов определения строк. Вся спецификация занимает более 100 страниц и переусложнена.

> **Ужасные советы от Ygg:**
> Кстати, о типах данных:
> \`yml
> behaviors:
>
> * !type: HeartBehavior {}
>   \`
>   На что ссылается !type?
>   На класс в SpaceStation14 и/или RobustToolbox.
>   На C#.
>   Это, конечно, сбивает с толку любой YAML-валидатор, пытающийся найти схему тегов YAML. Будьте осторожны при автоматическом форматировании .yml Resources.

SS14 не использует прямую десериализацию объектов, и YamlDotNet (библиотека, которую мы используем для парсинга YAML) достаточно любезен, чтобы обрабатывать скаляры только как строки. Он не пытается парсить строки как числа или что-то ещё при использовании API «YAML to LINQ» (который я называю «вменяемым, не полностью бесполезным для практического использования»). Парсинг чисел обрабатывается нашим собственным кодом на C# на месте, так что если код ожидает boolean, он правильно обработает 	rue и alse; если ожидает строку, он просто увидит её как строку.