Decision Timer

Purpose

Enforces sequential turn order with configurable countdown timers, adding realism and pressure to bot and human decision-making.

ADDED Requirements

Requirement: Sequential action timer with countdown display

The system SHALL enforce sequential turn order where each active player receives an independent countdown timer. The timer duration SHALL be configurable (5-30 seconds, default 10s). A visual countdown indicator SHALL be displayed for the current acting player. When the timer reaches zero, the system SHALL execute a timeout action.

Scenario: Timer counts down for current player

WHEN it is Bot #2's turn to act and timer is set to 10s
THEN a countdown from 10 to 0 is displayed, then turn advances to next active player

Scenario: Timer expires triggers timeout action

WHEN a bot's timer reaches zero before the bot makes a decision
THEN the system executes the bot's archetype-appropriate timeout default action

Requirement: Archetype-specific timeout defaults

The system SHALL define a default timeout action per archetype: Nit folds, TAG checks or folds, LAG calls, Maniac raises, Calling Station calls, Loose Fish calls, Old Man calls, Monster TAG checks. The timeout action SHALL be recorded in the action history and counted as a mistake for skill assessment.

Scenario: Nit times out by folding

WHEN a Nit bot's timer expires during a betting round
THEN the bot folds and the turn advances to the next active player

Scenario: Maniac times out by raising

WHEN a Maniac bot's timer expires and raising is a valid action
THEN the bot makes a raise and the turn advances

Requirement: Optional human player timer

The system SHALL support three human timer modes: "Same as bots" (human gets same duration as bot timer), "No limit" (human has unlimited time), or "Custom" (player specifies duration). In No Limit mode, no countdown is displayed for the human. Timer mode SHALL be configurable in table setup.

Scenario: Human plays with no timer

WHEN human timer is set to "No limit" and it is the human's turn
THEN no countdown appears and the human may take unlimited time to decide

Scenario: Human shares bot timer duration

WHEN human timer is set to "Same as bots" with 10s bot timer
THEN the human has a 10-second countdown when it is their turn

Requirement: Timing data recorded for observation

The system SHALL record the decision time (in seconds) for every action taken by every player. The recorded timing data SHALL be available to the observation tracking system and classification engine. Decision time SHALL be measured from when the timer starts for a player to when they commit an action.

Scenario: Fast action is recorded

WHEN Bot #3 calls within 1.5 seconds of their timer starting
THEN the action history records decision_time: 1.5 for that action

Scenario: Slow hesitation is recorded

WHEN Bot #5 takes 8.2 seconds to decide before folding
THEN the action history records decision_time: 8.2 for that fold

Requirement: Timer decrements correctly without resetting

The decision timer SHALL count down from the configured duration to zero, decrementing exactly once per second, without being reset by reactive effect re-runs.

Scenario: Normal countdown

WHEN a timer is activated with duration of 10 seconds
THEN the displayed remaining time follows the sequence: 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0 — each value displayed for approximately one second

Scenario: Timer does not reset mid-countdown

WHEN the timer is counting down and a reactive state change occurs in the component
THEN the countdown continues without being interrupted or reset to the initial duration

3.7 KiB Raw Blame History