Robust Station Image

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

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

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

JSON

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

КлючЗначение
versionПростое целое число, соответствующее версии формата RSI. Его можно использовать, чтобы определить, какой версии принадлежит RSI, и позволить реализации корректно включать режимы обратной совместимости при необходимости.
sizeРазмеры спрайтов внутри RSI, хранящиеся как ассоциативный список {x: ?, y: ?}. Это не размер файлов PNG, в которых хранится лист спрайтов. Он используется для корректного вырезания отдельных спрайтов из файлов листов спрайтов.
statesСписок состояний, в которых хранится сама суть RSI, см. ниже.
licenseОбязательно. Действительный идентификатор лицензии SPDX, применяемый к этой работе.
copyrightОбязательно. Прочая произвольная информация об авторских правах, такая как имя, источник, …
loadСпециальные параметры загрузки, которые изменяют то, как движок интерпретирует спрайты.
metaAtlasЛогическое значение, указывающее, добавляется ли спрайт в больший атлас при загрузке. Включено по умолчанию; это следует отключать для крупных, редких RSI.

Состояния

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

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

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

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

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

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

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

Направления

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

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

Лист спрайтов

Файл PNG, сопровождающий состояние, всегда называется по имени состояния. Например, состояние с именем “hello” на диске было бы hello.png.

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

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

Пример JSON

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

{
    "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.
  • Оно должно легко диффиться на GitHub.
  • Оно не должно слишком раздувать историю Git при внесении изменений (предотвращать крупные перезаписи файлов).
  • Один PNG — одно изображение

Subpages