Decky Loader: с чего начать разработку плагинов. Часть 1 9 декабря 2025 г. | 9 мин Читать

Decky Loader: с чего начать разработку плагинов. Часть 1

Содержание

В этом руководстве мы настроим среду разработки, соберём тестовый плагин для Decky Loader и запустим его на Steam Deck.

Для разработки мы будем использовать Windows с виртуальной машиной Ubuntu Server на VirtualBox и сам Steam Deck.

Все три устройства должны быть подключены к одной сети.

Если используете Linux вместо Windows — пропустите подготовительную часть. Visual Studio Code настраивается аналогично.

Перед тем как начать

Установите на Windows:

Установите на Steam Deck:

Заранее ознакомьтесь с работой в консоли — с этим прекрасно справится любой ИИ.

Установка Ubuntu Server на VirtualBox

Самый простой способ собирать плагин — использовать Linux. Я выбрал Ubuntu Server. Лёгкая, быстрая, без графического интерфейса — идеальный вариант для удалённой разработки.

Можно использовать любой другой дистрибутив Linux.

Создание машины

Скачайте образ Ubuntu Server LTS 24.04.3 или новее.

Откройте VirtualBox в Windows. В меню Машина выберите Создать. Настройте параметры как на скриншотах ниже.

1. Виртуальная машина и операционная система
  • Имя: Ubuntu Server
  • Образ ISO: Укажите путь до скачанного iso образа
  • Тип: Linux
  • Версия: Ubuntu (64 bit)
  • Пропустить автоматическую установку: Да
2. Оборудование
  • Основная память: 4096 МБ
  • Процессоры: 2
3. Виртуальный жёсткий диск
  • Размер диска: 10GB
4. Настройка сети

Откройте настройки созданной машины Ubuntu Server. Перейдите на вкладку Сеть и выберите тип подключения Bridged Adapter.

Теперь виртуальная машина может подключаться к другим устройствам в сети, а другие устройства — к ней.

Установка Ubuntu Server

Запустите Ubuntu Server и следуйте установщику. Используйте клавиши стрелок, Tab, пробел и Enter для переключения пунктов.

На экране Choose the type of installation выберите Ubuntu Server.

На экране Profile configuration создайте пользователя. Я создам пользователя ubuntu с паролем password.

На экране SSH configuration поставьте галочку Install OpenSSH server.

После завершения установки Ubuntu Server перезагрузится и появится экран входа. Войдите под созданным пользователем ubuntu с паролем password.

SSH позволяет подключаться из Windows и работать в терминале Ubuntu удалённо, включим SSH:

Включаем сервис SSH:

sudo systemctl enable ssh

Проверяем статус SSH:

sudo systemctl status ssh

Статус enabled означает, что SSH запущен.

Для подключения по SSH понадобится IP-адрес Ubuntu Server. Узнаём IP-адрес, который роутер ей присвоил:

ip a

Нас интересует строка:

inet 192.168.1.65/24

Наш IP: 192.168.1.65 — этот адрес будем использовать при подключении из Windows.

Рекомендую закрепить IP в настройках роутера за Ubuntu Server, чтобы он не менялся.

Проверим подключение по SSH к Ubuntu Server. Откройте Terminal в Windows и выполните команду, где:

  • ubuntu — пользователь на Ubuntu Server
  • 192.168.1.65 — её адрес в нашей сети
ssh ubuntu@192.168.1.65

При первом подключении появится вопрос — отвечаем yes, затем вводим пароль password от пользователя ubuntu.

В последней строке видим:

ubuntu@virtualbox-ubuntu-server:~$

Это означает, что подключение по SSH прошло успешно.

  • ubuntu — пользователь, под которым мы сейчас работаем
  • virtualbox-ubuntu-server — имя компьютера, к которому мы подключились

Теперь все команды, которые вы вводите в терминал Windows, будут выполняться на Ubuntu Server.

Завершите сессию SSH, закрыв Terminal или выполнив команду:

exit

Настройка SSH на Windows

Настроим вход по SSH-ключу, чтобы входить одной короткой командой и не вводить постоянно пароль.

Создадим папку .ssh, в которой будут храниться SSH-ключи:

New-Item -ItemType Directory "$env:USERPROFILE\.ssh" -Force

Создадим SSH-ключ, пропустите ввод passphrase нажатием Enter:

ssh-keygen -t rsa -f "$env:USERPROFILE\.ssh\virtualbox"

Скопируем публичный ключ в Ubuntu Server. Команда потребует ввести пароль password от пользователя ubuntu.

type $env:USERPROFILE\.ssh\virtualbox.pub | ssh ubuntu@192.168.1.65 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Добавим SSH конфигурацию virtualbox:

Add-Content "$env:USERPROFILE\.ssh\config" @"
Host virtualbox
    HostName 192.168.1.65
    Port 22
    User ubuntu
    IdentityFile ~/.ssh/virtualbox
"@

Перезапустите терминал, чтобы применить изменения.

Теперь для подключения к Ubuntu Server используйте команду:

ssh virtualbox

После успешного подключения можно закрыть окно Terminal.

Настройка SSH на Steam Deck

Аналогично настроим подключение по SSH, чтобы Ubuntu Server мог подключаться к Steam Deck. Это позволит устанавливать плагины прямо из Ubuntu Server на Steam Deck без копирования файлов вручную.

Перейдите в Desktop Mode на Steam Deck. В Steam Deck по умолчанию имя пользователя deck.

Откройте Konsole на Steam Deck и установите пароль deckpassword с помощью команды (если пароль установлен — пропустите шаг):

passwd

Включаем SSHD — название службы SSH на Steam Deck. Введите пароль deckpassword.

sudo systemctl enable sshd

Проверим статус SSHD:

sudo systemctl status sshd

Статус enabled означает, что SSH запущен.

Для подключения по SSH понадобится IP-адрес Steam Deck. Узнаём IP-адрес, который роутер ей присвоил:

ip a

Нас интересует строка:

inet 192.168.1.128/24

Наш IP: 192.168.1.128 — этот адрес будем использовать при подключении из Ubuntu Server.

Рекомендую закрепить IP в настройках роутера за Steam Deck, чтобы он не менялся.

Создадим ключ SSH на Ubuntu Server и добавим публичный ключ на Steam Deck. Откройте Terminal на Windows и выполните:

Подключимся к Ubuntu Server:

ssh virtualbox

Создадим SSH-ключ в ~/.ssh/deck. В этот раз запомним путь до ключа — он понадобится нам позже.

ssh-keygen -t rsa -f ~/.ssh/deck

Скопируем ключ на Steam Deck. Введите yes, затем пароль deckpassword от пользователя deck.

cat ~/.ssh/deck.pub | ssh deck@192.168.1.128 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Добавим SSH конфигурацию steamdeck:

cat << 'EOF' >> ~/.ssh/config
Host steamdeck
    HostName 192.168.1.128
    Port 22
    User deck
    IdentityFile ~/.ssh/deck
EOF

Теперь для подключения к Steam Deck из Ubuntu Server используйте:

ssh steamdeck

В последней строке видим:

(1)(deck@steamdeck-lcd)$

Это означает, что мы подключились к Steam Deck по SSH. Закройте Terminal.

Как это работает

На этом этапе вы, наверное, запутались, как мы подключились к Steam Deck. Рассмотрим схему подключения:

Windows → SSH → Ubuntu Server → SSH → Steam Deck

Мы подключаемся по ssh virtualbox к Ubuntu Server. На ней мы будем писать код в Visual Studio Code и собирать плагин. Когда нам понадобится установить плагин на Steam Deck, Ubuntu Server подключится по ssh steamdeck к Steam Deck и установит плагин.

Звучит сложно, но на деле это довольно просто — мы убедимся в этом позже.

Настройка Visual Studio Code на Windows

Visual Studio Code позволяет работать с файлами на Ubuntu Server так, как будто они локальные.

Установите расширения:

  • Remote Explorer
  • Remote — SSH
  • Remote — SSH: Editing Configuration Files

Или установите расширения автоматически, выполнив команду в Terminal:

"ms-vscode-remote.remote-ssh",
"ms-vscode-remote.remote-ssh-edit",
"ms-vscode.remote-explorer" |
ForEach-Object { code --install-extension $_ }

После установки расширений откройте Visual Studio Code. В левом нижнем углу нажмите на две стрелки ><, а в выпадающем списке выберите Connect to Host..

Затем выберите SSH-подключение virtualbox, которое мы создали ранее.

И укажите платформу Linux, так как мы используем Linux на виртуальной машине.

Через несколько секунд Visual Studio Code подключится к Ubuntu Server. В нижнем левом углу экрана теперь написано virtualbox — это означает, что мы работаем удалённо на Ubuntu Server.

Настройка Ubuntu Server для разработки Decky-плагинов

Разработка происходит следующим образом: Visual Studio Code на Windows подключается к Ubuntu Server. Всё, что вы делаете: создание файлов, выполнение команд, установка программ и пакетов — теперь происходит на Ubuntu Server. Что-то вроде удалённого рабочего стола.

Откройте терминал внутри Visual Studio Code нажатием Ctrl+J. Обратите внимание на строку в терминале:

ubuntu@virtualbox-ubuntu-server:~$

Мы подключены и работаем непосредственно на Ubuntu Server.

Создадим папку Documents для проектов:

mkdir ~/Documents

Перейдём в папку Documents:

cd ~/Documents

В качестве примера возьмём официальный плагин Decky Plugin Template.

Склонируем Decky Plugin Template в папку Documents:

git clone https://github.com/SteamDeckHomebrew/decky-plugin-template.git

Проверим, что папка decky-plugin-template появилась в Documents:

ls

Откроем папку decky-plugin-template в Visual Studio Code. Нажмите в Visual Studio Code Open folder, в выпадающем списке выберите Documents, затем папку с плагином decky-plugin-template и нажмите OK.

Проект открылся. Нажмите Yes, I trust the authors. Теперь мы можем посмотреть структуру проекта, открывать, изменять и создавать файлы прямо из Visual Studio Code.

Для сборки плагина понадобятся пакеты:

  • curl
  • wget
  • nodejs npm
  • pnpm
  • docker

Воспользуемся моим скриптом для быстрой настройки окружения. Скачиваем из репозитория MagicPodsDecky скрипт для установки всех необходимых пакетов.

Откройте терминал в Visual Studio Code (Ctrl+J) и выполните команду. Команда потребует ввести пароль password от пользователя ubuntu.

curl -L https://github.com/steam3d/MagicPodsDecky/raw/refs/heads/master/.vscode/envsetup.sh -o .vscode/envsetup.sh \
&& chmod +x .vscode/envsetup.sh \
&& sudo .vscode/envsetup.sh

Дождитесь завершения установки — это может занять некоторое время.

Добавим дополнительные задачи в Visual Studio Code из репозитория MagicPodsDecky. Подробнее рассмотрим, для чего они нужны, в следующем разделе.

curl -L https://github.com/steam3d/MagicPodsDecky/raw/refs/heads/master/.vscode/tasks.json -o .vscode/tasks.json

Чтобы после сборки плагин можно было сразу установить на Steam Deck, необходимо указать параметры подключения. Плагин предоставляет шаблон настроек defsettings.json. Возьмём его за основу:

cp .vscode/defsettings.json .vscode/settings.json

Откройте файл settings.json в папке .vscode и заполните параметры подключения: deckip, deckpass и deckkey, которые мы получили ранее. Сохраните изменения.

{
    "deckip"    : "192.168.1.128",
    "deckport"  : "22",
    "deckuser"  : "deck",
    "deckpass"  : "deckpassword",
    "deckkey"   : "-i ${env:HOME}/.ssh/deck",
    "deckdir"   : "/home/deck",
    "pluginname": "Example Plugin",
    "python.analysis.extraPaths": [
        "./py_modules"
    ]
}

Сборка и установка плагина на Steam Deck

Для сборки плагина выполним задачу Visual Studio Code Build. Нажмите Ctrl+Shift+P, выберите Task: Run Task.

Выберите из списка Build.

Decky CLI спросит подтверждение — нажимаем Enter.

При каждой сборке необходимо вводить пароль password пользователя ubuntu. Ниже я расскажу, как делать сборку без ввода пароля.

После сборки в папке out появится архив с плагином Example Plugin.zip.

Для установки плагина нужно скопировать Example Plugin.zip на Steam Deck. Открыть настройки Decky Loader, перейти на вкладку Developer и выбрать Install Plugin from ZIP File и в проводнике выбрать скопированный плагин. Ниже я расскажу, как упростить этот процесс.

Чтобы сборка плагина работала без ввода пароля, отредактируем файл build.sh в папке .vscode. Заменим содержимое файла, обратите внимание на пароль password нашего пользователя ubuntu.

Хранить пароль в тексте файла — небезопасно, но для учебных целей допустимо. Используйте переменные окружения для этого.

#!/usr/bin/env bash
CLI_LOCATION="$(pwd)/cli"
printf "Building plugin in $(pwd)"
echo "password" | sudo -S $CLI_LOCATION/decky plugin build $(pwd)

Для того чтобы сразу после сборки установить плагин на Steam Deck, есть две задачи: builddeploy и builddeployrestart (моя задача, в официальном плагине её нет — будьте внимательны).

  • builddeploy — соберёт плагин и установит на Steam Deck
  • builddeployrestart — соберёт плагин, установит на Steam Deck и перезагрузит Decky Loader

По моему опыту, если плагин устанавливается впервые (как в нашем случае), проще использовать builddeployrestart, так как перезагрузка Decky Loader заставит принудительно обновить список установленных плагинов и не придётся ждать, пока Decky Loader сделает это в фоне.

Включите Steam Deck в игровом режиме — он должен быть подключён к Wi-Fi. Аналогично нажмите Ctrl+Shift+P, выберите Task: Run Task и запустите задачу builddeployrestart. Начнётся сборка плагина, затем он будет установлен на Steam Deck, а Decky Loader перезагружен вместе с интерфейсом SteamOS.

Теперь откроем Decky Loader на Steam Deck — и мы увидим наш плагин Example Plugin.

Отладка пользовательского интерфейса плагина

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

На Steam Deck откройте настройки Decky Loader. На вкладке Developer включите переключатель Allow Remote CEF Debugging.

На Windows откройте любой хромиум-браузер, например Google Chrome.

В адресной строке введите:

chrome://inspect/#devices

Выберите Configure и укажите 192.168.1.128:8081 — IP-адрес Steam Deck и порт 8081.

Через несколько секунд появится список страниц, доступных для дебага. Иногда требуется перезапустить браузер. Нажмите inspect, чтобы подключиться к странице и посмотреть информацию.

SharedJSContext — содержит логи плагинов Decky Loader. Например, если написать в плагине console.log("Hello World");, то сообщение отобразится на этой вкладке в console.

QuickAccess_uid2 — содержит непосредственно интерфейс QuickAccess, где находится интерфейс нашего плагина.

Изучите оставшиеся вкладки самостоятельно.

Заключение

Я показал один из способов организовать разработку плагинов для Decky Loader. Далее ознакомьтесь со структурой проекта и изучите другие Decky плагины.