Plugin SDK — руководство

Добавление новой игры

Создать services/api/app/plugins/<plugin_id>/plugin.py
Наследовать GamePlugin из app/plugins/base.py
Зарегистрировать в app/plugins/registry.py
Добавить docs/05-games/<plugin_id>/game-spec.md
Добавить Gherkin тесты
Обновить catalog-roadmap.md

Обязательные методы

class MyPlugin(GamePlugin):
    plugin_id = "my_game"
    display_name = "Моя игра"
    min_players = 2
    max_players = 4
    version = "0.1"

    def initial_state(self, player_ids, player_names, config) -> dict: ...
    def validate_action(self, state, action_type, payload, player_id) -> ValidationResult: ...
    def apply_action(self, state, action_type, payload, player_id) -> dict: ...
    def get_current_player(self, state) -> str | None: ...
    def is_finished(self, state) -> bool: ...
    def get_winner(self, state) -> str | None: ...
    def render_web(self, state, player_names) -> WebViewModel: ...
    def render_telegram(self, state, player_names) -> TelegramViewModel: ...

Action contract

Все действия через POST /api/v1/games/{id}/actions:

{
  "action_id": "uuid",
  "action_type": "roll_dice",
  "payload": {}
}

action_id — идемпотентность
Сервер валидирует фазу и игрока
CSPRNG для случайных событий на сервере

Зарегистрированные плагины

plugin_id	Статус
dice_board	✅
shlyapa	✅
kontakt	✅