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:

  1. Choose current indicator and round indicators.

  2. Send round_start with each player’s hand.

  3. If at least one active non-bot player has event cards, open event phase and send event_time_start.

  4. Players either play an event card (event_card) or skip (event_skip).

  5. Event phase ends on timeout or early-complete condition.

  6. 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.