Super strategic mode - Developer documentation
==============================================

1) Scope
--------

This document describes Super Strategic mode implementation.

Super Strategic is built on top of Strategic mode and adds:


* per-round event phase (\ ``event_time_start`` / ``event_time_end``\ )
* one-shot bonus cards per player
* event action resolution before card comparison scoring

For base Strategic architecture, see ``Doc/strategic_mode_for_developers.md``.

2) Main components
------------------

Backend
^^^^^^^


* ``apiserver/apiserver/routers/super_strategic_game.py``
* ``apiserver/apiserver/controllers/super_strategic_game_controller.py``
* ``apiserver/apiserver/services/super_strategic_game_service.py``
* ``apiserver/apiserver/models/super_strategic_room.py``
* ``apiserver/apiserver/models/super_strategic_player.py``
* inherited base logic: ``apiserver/apiserver/services/strategic_game_service.py``

Frontend
^^^^^^^^


* ``frontend/engines/SuperStrategicEngine.ts``
* ``frontend/class/SuperStrategicGame.ts``
* ``frontend/types/StrategicGame.ts``
* ``frontend/composables/useGameWebSocket.ts``
* ``frontend/pages/super-strategic-game-board.vue``

3) Transport and endpoints
--------------------------

REST
^^^^


* ``POST /super_strategic/create_room``

  * body: ``mode``\ , ``max_players``\ , ``deck_id``

Mode constraints:


* tutorial / solo / random match force ``max_players=2``
* otherwise ``max_players`` must be in ``{2,3,4}``

WebSocket
^^^^^^^^^


* ``GET WS /super_strategic/ws/{room_id}/{pseudo}``
* ``GET WS /super_strategic/ws/{room_id}/{pseudo}/{token}``

Core events:


* server to client: ``game_context``\ , ``player_join``\ , ``game_start``\ , ``round_start``\ , ``event_time_start``\ , ``event_card_played``\ , ``event_time_skipped``\ , ``event_time_end``\ , ``indicator_changed``\ , ``reveal_indicator``\ , ``hand_updated``\ , ``block``\ , ``steal``\ , ``round_result``\ , ``game_finish``\ , ``player_leave``\ , ``error``
* client to server: ``selected_card``\ , ``event_card``\ , ``event_skip``

4) Room state extensions
------------------------

``SuperStrategicRoom`` extends ``StrategicRoom`` with event-phase state:


* ``event_time_seconds``
* ``event_phase_active``\ , ``event_phase_deadline_ms``\ , ``event_phase_task``
* ``event_cards_catalog``\ , ``player_event_cards``
* ``pending_event_actions`` and sequence ordering
* round modifiers: ``double_down_players``\ , ``streak_bonus_players``\ , ``still_targets``
* indicator mutation support: ``pending_indicator_change``

5) Event phase lifecycle
------------------------

At round start:


#. Choose current indicator and round indicators.
#. Send ``round_start`` with each player's hand.
#. If at least one active non-bot player has event cards, open event phase and send ``event_time_start``.
#. Players either play an event card (\ ``event_card``\ ) or skip (\ ``event_skip``\ ).
#. Event phase ends on timeout or early-complete condition.
#. Backend applies event actions (with priority), sends resolution events, then transitions to normal card selection.

Important behavior:


* if no active player has event cards, event phase is skipped entirely
* in this case only ``round_start`` is emitted for that round

6) Event actions and priority
-----------------------------

Actions are normalized and resolved by priority:


* ``block`` > ``change`` > ``steal`` > ``swap`` > ``trade`` > ``reveal`` > ``double_down`` > ``streak``

Key effects:


* ``block``\ : cancels targeted or wildcard action
* ``change``\ : changes current indicator before play resolution
* ``steal``\ : redirects target player's adjusted points
* ``swap`` / ``trade``\ : mutate player hands
* ``reveal``\ : reveals selected card value for current indicator
* ``double_down``\ : 2x points multiplier
* ``streak``\ : streak-based multiplier

7) Round scoring
----------------

Base scoring comes from Strategic resolve logic. Super Strategic then applies event modifiers:


* ``double_down`` multiplies round points by 2
* ``streak`` multiplies by ``(current_streak + 1)`` when eligible
* ``steal`` transfers adjusted points from target to source

After resolution:


* streak counters are updated
* temporary event modifiers are cleared

8) Persistence and leaderboard
------------------------------


* game record is created at start and updated to finish at end
* leaderboard writes use ``game_type=SUPER_STRATEGIC``
* tutorial mode does not write leaderboard entries

9) Frontend runtime behavior
----------------------------

``SuperStrategicEngine`` maintains explicit flow phases:


* ``round_start``
* ``event_time``
* event-resolution subphase
* ``game_time``
* ``round_result``
* ``finished``

The engine consumes event-resolution messages (\ ``indicator_changed``\ , ``hand_updated``\ , ``reveal_indicator``\ , ``block``\ , ``steal``\ ) before opening/continuing card play UI.

10) Operational notes
---------------------


* Event phase timeout is configurable through ``SUPER_STRATEGIC_EVENT_TIME_SECONDS``.
* If only one active player remains, room auto-finishes.
* Pseudo toxicity and room-join validations are inherited from strategic base services.