From 65e17a69756301767f7caf0413aaf3621de7b3f4 Mon Sep 17 00:00:00 2001 From: faint <46868845+ficcialfaint@users.noreply.github.com> Date: Fri, 29 Sep 2023 01:02:24 +0300 Subject: [PATCH] Specifications :)))) --- .../robust-generic-attribution.md | 39 +++++++ src/ru/specifications/robust-station-image.md | 100 ++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 src/ru/specifications/robust-generic-attribution.md create mode 100644 src/ru/specifications/robust-station-image.md diff --git a/src/ru/specifications/robust-generic-attribution.md b/src/ru/specifications/robust-generic-attribution.md new file mode 100644 index 000000000..d5cd9353e --- /dev/null +++ b/src/ru/specifications/robust-generic-attribution.md @@ -0,0 +1,39 @@ +# Robust Generic Attribution + +**RGA** (Robust Generic Attribution) стандарт задуман как гибкий, открытый и читаемый способ обозначать различные метаданные, такие как лицензия и атрибуция, для произвольной коллекции файлов разных типов, таких как звуковые эффекты или прототипы. RGA файл содержит метаданные для всех файлов в той же директории, что и он сам (не учитывая подкаталоги). Записи в RGA файле содержат конкретные метаданные, такие как автор файла(ов) или описание любых их модификаций (в соответствии со многими Creative Commons лицензиями). + +RGA — это YAML файл с названием `attributions.yml`, содержащий произвольное число записей, как обозначено ниже. + +Обычно всегда, когда добавляются новые файлы, добавляется и новая запись, т.к. скорее всего она не будет содержать такие же метаданные, как и уже существующие записи. Однако файлы могут быть добавлены в уже существующую запись, если их метаданные идентичны. + +## YAML + +RGA файл должен быть назван `attributions.yml`. Все значения в записях должны быть заключены в двойные кавычки (`""`). + +YAML файл содержит произвольное количество записей, охватывая все файлы в той же директории, что и RGA файл. Запись задаётся следующим образом: + +Ключ | Значение +---- | -------- +`files` | Список названий файлов (с их расширениями), на которых распространяется эта запись. Порядок файлов произвольный. Шаблон поиска `*` поддерживается (например, `*.ogg` обозначает все OGG файлы в директории). +`copyright` | Правообладатель и другая соответствующая информация. Любое раскрытие модификаций для соответствия определённым лицензиям также пишется в это поле. +`license` | Действительный [SPDX License Identifier](https://spdx.org/licenses/), применяющийся ко всем файлам в записи. Если лицензия не имеет действующего SPDX идентификатора, `Custom` может быть использован, но ссылка на лицензию должна быть указана в поле `copyright`. +`source` | Действительная URL-ссылка, указывающая на место, откуда может быть загружен файл. Если вы создатель работы и не имеете альтернативного места загрузки (например, Bandcamp), то укажите ссылку на pull request, добавляющий файл в игру. Если же это производная работа, это также должно быть отмечено в `copyright` поле. Если файл был лишь немного модифицирован, то просто укажите ссылку на оригинальный файл. Если же файл был сильно модифицирован, то укажите ссылку на модифицированную версию, но также укажите ссылку на любые оригинальные файлы в поле `copyright`. + +### YAML Пример + +```yaml +- files: ["thunderdome.ogg"] + license: "CC-BY-NC-SA-3.0" + copyright: "-Sector11 by MashedByMachines. Converted from MP3 to OGG." + source: "https://www.newgrounds.com/audio/listen/312622" +- files: ["endless_space.ogg"] + license: "CC-BY-3.0" + copyright: "Endless Space by SolusLunes. Converted from MP3 to OGG." + source: "https://www.newgrounds.com/audio/listen/67583" +``` + +## Цели дизайна + +* Редактирование RGA должно быть возможно без любого инструментария. Это означает отсутствие метаданных в бинарных файлах. +* RGA должен быть легко сравним на GitHub'е. +* Оно не должно так сильно засорять Git историю при изменениях (предотвратить переписывание больших файлов). \ No newline at end of file diff --git a/src/ru/specifications/robust-station-image.md b/src/ru/specifications/robust-station-image.md new file mode 100644 index 000000000..9ae54aa6c --- /dev/null +++ b/src/ru/specifications/robust-station-image.md @@ -0,0 +1,100 @@ +# 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` | Может быть упущено. Другая произвольная информация об авторских правах: название, источник, ... + +### Состояния + +"Состояние" — это контейнер для метаданных определённого спрайт-листа. Они хранят информацию об их спрайт-листа, такие как задержка анимаций и направления. Состояние имеет соответствующий спрайт-лист. + +Состояния имеют одно поле, которое может быть использовано для их различения: S + +Ключ | Значение +---- | -------- +`name` | Название состояния. Может содержать только буквы нижнего регистра, цифры и некоторые специальные (`_-`) символы. + +Состояния не могут иметь одинаковые идентифицирующие значения. Два состояния не могут иметь идентичные названия. + +Помимо идентификатора, состояние имеет три остальных поля, связанных со спрайтами, которые видны в игре: + +Ключ | Значение +---- | -------- +`flags` | Свойственный список типа `key: object` для обозначения дополнительной информации. Пока что нет ни одного его применения. Опционально. +`directions` | Число, соответствующее количеству направлений состояния. Должно быть `1`, `4` или `8`. +`delays` | Может быть упущено. Если задано, то это список задержек для состояния анимированной иконки. Каждый список в списке соответствует направлению. Задержки — числа с плавающей точкой (floats), обозначающие секунды. + +Состояния всегда расположены в алфавитном порядке по их соответствующим названиям файлов. + +#### Направления + +На данный момент есть три поддерживающихся типов направления: `1` (нет направлений), `4` (Север Юг Восток Запад), `8` (Север Юг Восток Запад + диагонали). Эти направления расположены (для расстановки в поле `delays` и для расположения в спрайт-листе) следующим образом: + +* Юг +* Север +* Восток +* Запад +* Юго-восток +* Юго-запад +* Северо-восток +* Северо-запад + +#### Спрайт-лист + +PNG файл, соответствующий состоянию, всегда имеет такое же имя, как и название состояния. Например, состояние с названием "hello" будет `hello.png` на диске. + +Файл содержит отдельные состояния с их направлениями и задержками. Размер файла всегда кратен полю `size` у RSI. Спрайты расположены от левого верхнего угла к нижнему правому углу, сначала всегда по горизонтали. Количество спрайтов на строку или столбец всегда делается настолько равным, насколько возможно, при этом строки не должны быть длиннее столбцов, если количество состояний не может быть идеально поделено. + +Спрайты записываются сгруппированными по направлению, затем каждая иконка записывается в определенном направлении, поэтому при 4 направлениях, ВСЕ южные состояния должны быть записаны первыми, затем северные и т.д. + +### JSON Пример + +Учтите, что на практике средство записи 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] + ] + } + ] +} +``` + +## Цели дизайна + +* Редактирование RSI должно быть возможно без любого инструментария. Это означает отсутствие метаданных в бинарных файлах. +* RGA должен быть легко сравним на GitHub'е. +* Оно не должно так сильно засорять Git историю при изменениях (предотвратить переписывание больших файлов). +* Один PNG = Одна картинка \ No newline at end of file