Шаблон плагина Decky

Эталонный пример использования decky-frontend-lib (@decky/ui) в плагине для decky-loader.

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

Разработчикам

Зависимости

Этот шаблон предполагает, что в системе пользователя установлены Node.js v16.14 или выше и pnpm (v9). Пожалуйста, убедитесь, что установили pnpm v9, чтобы избежать проблем с CI во время отправки плагина. pnpm можно скачать напрямую через npm, что является рекомендуемым способом.

Linux

sudo npm i -g pnpm@9

Если вы хотите создавать плагины что имеют свои кастомные бэкенды, вам потребуется Docker, поскольку он используется в инструменте Decky CLI.

Создание собственного плагина

1. Вы можете создать форк этого репозитория или воспользоваться кнопкой "Use this template" на Github.
2. В вашем локальном форке/собственном плагин-репозитории выполните эти команды:
   1. pnpm i
   2. pnpm run build
   • Это настройка pnpm и сборка кода фронтенда для тестирования.
3. Обратитесь к decky-frontend-lib чтобы узнать, как выполнить ваши задачи
   • Документация и примеры всё еще сырые,
   • Decky loader в первую очередь ориентирован на оборудование Steam Deck, так что учитывайте это при разработке вашего плагина.
4. Если вы используете VSCodium/VSCode, запустите задачи setup, build и deploy. Если вы не используете VSCodium и т.д., вы можете составить собственный makefile или просто вручную использовать скрипты для этих команд по своему усмотрению.

Если вы используете VSCode или его производные (мы рекомендуем VSCodium!) просто запустите задачи setup и build. Всё действительно настолько просто.

Другая важная информация

Каждый раз, когда вы меняете код фронтенда (index.tsx и т.д.), вам нужно будет пересобрать его, используя команды из шага 2 выше или задачу сборки (build), если вы используете vscode или его производную.

Примечание: Если вы получаете ошибки при сборке из-за устаревшей библиотеки, вам следует выполнить эту команду внутри вашего репозитория:

pnpm update @decky/ui --latest

Поддержка бэкенда

Если вы разрабатываете плагин с бэкендом и хотите отправить его в decky-plugin-database вам нужно разместить весь код бэкенда в папке backend/src, при этом папка backend должна находиться в корне вашего git-репозитория. При сборке вашего плагина исходный код будет компилироваться, а все готовые бинарные файлы будут помещены в backend/out (эта папка создается во время CI). Если ваш скрипт сборки, makefile или любой другой метод сборки не поместит бинарные файлы в директорию backend/out, они не будут корректно обнаружены во время CI, и ваш плагин не будет включать необходимые бинарные файлы для распространения.

Пример: Обратите внимание, что нашем makefile, используемом для демонстрации процесса CI по сборке и распространению бэкенда плагина, makefile явно создает папку out (backend/out) и затем компилирует бинарный файл в эту папку. Вот соответствующий фрагмент.

hello:
	mkdir -p ./out
	gcc -o ./out/hello ./src/main.c

CI сам создает папку out, но мы рекомендуем создавать ее самостоятельно, если это возможно, в процессе сборки, чтобы процесс сборки прошел гладко.

Примечание: При локальной сборке вашего плагина он будет помещен в папку с названием 'out', что отличается от концепции, описанной выше.

Папка out не отправляется в итоговый плагин, а затем помещается в папку «bin», которая находится в корневом каталоге плагина.
Более подробную информацию о папке bin можно найти ниже в разделе о дистрибуции.

Дистрибуция (Распространение)

Мы рекомендуем следовать инструкциям в decky-plugin-database о том, как разместить ваш плагин в магазине плагинов. Это лучший способ представить ваш плагин пользователям. Вы также можете выбрать распространение через zip-файл, содержащий необходимые файлы; если этот zip-файл будет загружен по URL, его затем можно будет скачать и установить через decky-loader.

ПРИМЕЧАНИЕ: В данный момент у нас нет способа установки из загруженного zip-файла в «игровом режиме» из-за отсутствия рабочего диалогового окна выбора файла. _{^{Перевод. Прим.: Не является актуальной информацией, установка плагина в формате zip из памяти устройства прекрасно работает, диалоговое окно выбора файла присутствует.}}

Структура плагина в формате zip, готового к распространению:

pluginname-v1.0.0.zip (Номер версии не является обязательным, но рекомендуется для удобства пользователей)
   |
   pluginname/ <директория>
   |  |  |
   |  |  bin/ <директория> (необязательно)
   |  |     |
   |  |     binary (необязательно)
   |  |
   |  dist/ <директория> [необходимо]
   |      |
   |      index.js [необходимо]
   | 
   package.json [необходимо]
   plugin.json [необходимо]
   main.py {необходимо если вы используете серверную часть decky-loader на Python: serverAPI}
   README.md (необязательно но рекомендуется)
   LICENSE(.md) [необходимо, имя файла должно быть примерно таким же, суффикс не нужен]

Примечание по поводу лицензий: Включение лицензии обязательно для магазина плагинов, если выбранная вами лицензия требует, чтобы лицензия была включена вместе с использемым исходным кодом/бинарными файлами!

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

Мы не можем и не будем распространять ваш плагин в магазине плагинов, если его лицензия требует включения, но вы не включили лицензию на повторное распространение вместе с вашим плагином в корень вашего git-репозитория.