WebshopLink

WebshopLink

Мод для Minecraft Forge, который позволяет игрокам просматривать и использовать внешний веб-магазин прямо в игровом окне браузера, а купленные предметы сразу попадают в инвентарь.

В документации этот проект везде называется «модом», даже там, где речь идёт о версии-плагине — функциональность в обоих случаях одинаковая.

WebshopLink отвечает только за игровую часть. Сам магазин (каталог, цены, какие предметы получает игрок) живёт во внешнем веб-сервисе, который запускаете вы и который общается по HTTP-протоколу WebshopLink. Контракт описан в Wiki, а рабочий пример реализации — в demo/.

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

1. Игрок вводит в игре `/shop `.
2. WebshopLink (на стороне сервера) отправляет текущий инвентарь игрока в API вашего магазина и получает обратно URL сессии.
3. URL открывается в полноэкранном игровом браузере (рендерится через MCEF) поверх игрового мира, с небольшой панелью кнопок внизу.
4. Игрок собирает корзину на веб-странице и нажимает Finish Trade.
5. WebshopLink забирает получившийся инвентарь из вашего API, проверяет, что инвентарь игрока не изменился с начала сессии, и применяет его. Закрытие окна (или Cancel / ESC) отменяет сессию.

Player ──/shop──▶ WebshopLink (server) ──HTTP──▶ Your shop API
                        │                              │
                        └──── opens in-game browser ───┘
                                     │
                        Finish Trade ▼
                  inventory applied to player

Возможности

• Покупки прямо в игре — веб-магазин рендерится в браузере Chromium поверх игры; не нужно переключаться на внешний браузер.
• Проверка инвентаря — покупка отклоняется, если инвентарь игрока изменился между началом сессии и подтверждением, что защищает от дюпа и гонок.
• Двухфакторный код сессии — на каждом запросе с вашим API сверяется защитный код, так что сессию нельзя подделать извне.
• Поддержка API-ключа — каждый запрос к API вашего магазина несёт настраиваемый заголовок X-Webshop-Api-Key.
• Поддержка основного инвентаря и Ender Chest, с полной сериализацией NBT для сложных предметов.
• Оверлей баланса (опционально) — небольшой HUD-блок в настраиваемом углу экрана рендерит страницу баланса вашего магазина, чтобы игроки всегда видели свой баланс. Включён по умолчанию; позиция, размер и URL настраиваются на стороне клиента. См. Balance overlay.
• Опциональная сеть — мод регистрирует свой сетевой канал как опциональный, поэтому ванильные клиенты (или клиенты без мода) всё равно могут подключаться к серверу; просто они не смогут открыть браузер.

Требования

• Minecraft 1.20.1, Forge 47.x
• MCEF 2.2.0+ (только клиент — выделенный сервер его никогда не загружает)

Игрокам, у которых на клиенте нет мода/MCEF, при вводе /shop скажут их установить.

Команды

Обычная игра требует только /shop — остальное делают кнопки в браузере. Остальные команды существуют как запасной вариант и для клиентов без внутриигрового браузера.

По умолчанию /shop может выполнить любой. Чтобы ограничить её операторами/командными блоками (так магазины открываются только в определённых местах), задайте shopCommandPermissionLevel в конфиге — см. Ограничение доступа к /shop.

Установка

Сервер

1. Скачайте последний релизный JAR WebshopLink.
2. Положите его в папку mods/ сервера.
3. Запустите сервер один раз, чтобы создался config/webshoplink-common.toml, затем укажите в нём адрес API вашего магазина (см. Вики).
4. Перезапустите.

Клиент (каждый игрок)

1. Установите MCEF.
2. Установите мод WebshopLink.

Документация

• Вики — настройка для операторов сервера: полный справочник по конфигу, HTTP API, который должен реализовать ваш магазин, формат данных инвентаря и модель безопасности.
• demo/ — небольшой эталонный магазин с подробными комментариями (Bun + Tailwind), который можно запустить локально, чтобы попробовать мод или разобраться в контракте.

Лицензия

См. LICENSE.