62 lines
3.7 KiB
Markdown
62 lines
3.7 KiB
Markdown
# 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
|