> ## 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.

# Robust Station Image

Формат **RSI** (Robust Station Image) предназначен для гибкого, открытого и читаемого способа {/*Вставьте больше маркетингового шума*/} определения иконок внутри спрайт-листов, аналогично формату BYOND `.dmi`. RSI считается «иконкой» и может содержать «состояния» (states), которые являются подразделами этой главной иконки. Эти состояния могут определять пользовательские флаги, анимации и направленные иконки «из коробки».

RSI — это папка с именем, оканчивающимся на `.rsi`, которая содержит `meta.json` и один или несколько PNG-файлов в соответствии с именами состояний.

Метаданные изображения (что определяет состояния, анимации и т.д.) хранятся в файле `meta.json` в формате JSON. Фактические спрайты хранятся в спрайт-листах в виде PNG-файлов в папке. Каждому уникальному состоянию соответствует спрайт-лист с тем же именем.

## JSON

Корень JSON-файла содержит следующие значения:

| Ключ        | Значение                                                                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`   | Простое целое число, соответствующее версии формата RSI. Может использоваться для определения версии RSI и позволяет реализации корректно включать режимы обратной совместимости при необходимости.                       |
| `size`      | Размеры спрайтов внутри RSI, хранящиеся в виде ассоциативного списка `{x: ?, y: ?}`. Это *не* размер PNG-файлов, хранящих спрайт-лист. Используется для корректного выделения отдельных спрайтов из файлов спрайт-листов. |
| `states`    | Список *состояний*, которые хранят основное содержание RSI (см. ниже).                                                                                                                                                    |
| `license`   | Обязательно. Действительный [SPDX License Identifier](https://spdx.org/licenses/), применяемый к данной работе.                                                                                                           |
| `copyright` | Обязательно. Произвольная информация об авторских правах, такая как имя, источник и т.д.                                                                                                                                  |
| `load`      | Специальные параметры загрузки, которые изменят то, как движок интерпретирует спрайты.                                                                                                                                    |
| `metaAtlas` | Логическое значение, указывающее, добавляется ли спрайт в общий атлас при загрузке. Включено по умолчанию, должно быть отключено для больших, редко используемых RSI.                                                     |

### Состояния

Состояние — это контейнер для метаданных определённого спрайт-листа. Они хранят данные, связанные с их спрайт-листом, такие как задержки анимации и направления. Состояние имеет сопровождающий спрайт-лист.

Состояния имеют одно поле, которое можно использовать для их различения:

| Ключ   | Значение                                                                                            |
| ------ | --------------------------------------------------------------------------------------------------- |
| `name` | Имя состояния. Может содержать только строчные буквы, цифры и некоторые специальные символы (`_-`). |

Состояния не могут иметь одинаковое идентифицирующее значение. Два состояния с одинаковым именем не могут существовать.

Помимо идентификатора, состояние имеет три других поля, связанных с фактическими спрайтами, отображаемыми в игре:

| Ключ         | Значение                                                                                                                                                                                                                     |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flags`      | Ассоциативный список `key: object` для определения дополнительных данных. В настоящее время ещё не используется. Опционально.                                                                                                |
| `directions` | Число, соответствующее количеству направлений, которые имеет состояние. Должно быть `1`, `4` или `8`.                                                                                                                        |
| `delays`     | Может быть опущено. Если определено, список списков задержек для анимированного состояния иконки. Каждый список в списке соответствует направлению. Задержки — это числа с плавающей точкой (float), представляющие секунды. |

Состояния всегда упорядочены по алфавиту по соответствующему имени файла.

#### Направления

В настоящее время поддерживаются три типа направлений: `1` (без направлений), `4` (Север Юг Запад Восток) и `8` (Север Юг Запад Восток плюс диагонали).
Эти направления упорядочены (для компоновки в поле `delays` и порядка в спрайт-листе) в следующем порядке:

* Юг
* Север
* Восток
* Запад
* Юго-Восток
* Юго-Запад
* Северо-Восток
* Северо-Запад

#### Спрайт-лист

PNG-файл, сопровождающий состояние, всегда называется именем состояния. Например, состояние с именем "hello" будет файлом `hello.png` на диске.

Файл содержит отдельные состояния, разрешённые с помощью направлений и задержек состояния. Размер файла всегда кратен `size` RSI. Спрайты упорядочиваются сверху слева направо вниз, всегда сначала по горизонтали. Количество спрайтов в строке или столбце всегда делается максимально равным, при этом строки предпочтительно длиннее столбцов, если количество состояний не делится идеально.

Спрайты записываются сгруппированными по направлениям, затем записывается каждая иконка в направлении по порядку. Таким образом, для 4 направлений сначала записываются ВСЕ южные состояния, затем северные и т.д.

### Пример JSON

Обратите внимание, что на практике JSON-писатель, вероятно, записывает максимально компактный JSON для уменьшения размера файла.

```json theme={null}
{
    "version": 1,

    "license": "CC0-1.0",
    "copyright": "GitHub @PJB3005",

    "size": {
        "x": 32,
        "y": 32
    },
    "states": [
        {
            "name": "hello",
            "flags": {},
            "directions": 4,
            "delays": [
                [1, 1, 1],
                [2, 3, 4],
                [3, 4, 5],
                [4, 5, 6]
            ]
        }
    ]
}
```

### Параметры загрузки

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

| Ключ   | Значение                                                                                                    |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| `srgb` | Логическое значение, указывающее, интерпретируется ли спрайт как sRGB шейдерами и т.д. По умолчанию `true`. |

## Цели дизайна

* Редактирование RSI должно быть возможно без специальных инструментов. Это означает отсутствие бинарных метаданных или метаданных внутри PNG-файлов.
* Оно должно легко поддаваться сравнению (diff) на GitHub.
* Оно не должно слишком сильно раздувать историю Git при внесении изменений (предотвращать большие перезаписи файлов).
* Один PNG — одно изображение.