Feat: Card Timing & State Management Implementation

[manlikeHB]

Overview

Implement card timing and state management functionality for RoundPlayer. This issue covers starting cards, tracking timing, and managing card state transitions.

Requirements

Functions to Implement

start_next_card() - Start Next Card

fn start_next_card(self: @RoundPlayer, start_time: u64) -> Result<RoundPlayer, RoundPlayerValidation>

• Start the next card for a ready player
• Set card start time and increment card index
• Validate player can start a new card
• Return updated player with active card state

is_answering_card() - Check Active Card State

fn is_answering_card(self: @RoundPlayer) -> bool

• Check if player is currently answering a card
• Return true if card is active (start time > 0)
• Simple state query with no side effects

current_card_timed_out() - Check Timeout Status

fn current_card_timed_out(self: @RoundPlayer, current_time: u64) -> bool

• Check if current card has exceeded timeout
• Compare elapsed time against card timeout
• Return false if no active card
• Handle edge cases gracefully

get_time_remaining() - Calculate Remaining Time

fn get_time_remaining(self: @RoundPlayer, current_time: u64) -> u64

• Calculate remaining time for current card
• Return 0 if no active card or timed out
• Provide countdown functionality for UI
• Handle negative time scenarios

Business Logic

Card Start Rules

• Player must be in ready state to start cards
• Round must not be completed
• Only one card can be active at a time
• Card index increments with each new card

Timing Logic

• Card timing starts when start_next_card() is called
• Timeout calculated as: elapsed_time > card_timeout
• Time remaining: max(0, card_timeout - elapsed_time)
• Active card indicated by current_card_start_time > 0

State Management

• Card index tracks progression through round
• Start time of 0 indicates no active card
• Timeout detection is time-based, not automatic
• State queries are read-only operations

Acceptance Criteria

• All 4 card timing methods implemented correctly
• Card starting validation working properly
• Timeout detection accurate and reliable
• Time remaining calculations correct
• State queries perform efficiently
• Comprehensive error handling
• Complete test coverage
• All timing edge cases handled
• Documentation comments added

Note

Target Branch

• refac/modular-architecture

File Location

• src/models/round_player.cairo

Target Trait

• RoundPlayerTrait

[Devsol-01]

please i would really love to work on this issue

[Xaxxoo]

please i would really love to work on this issue

How far with this issue ?

[manlikeHB]

Hi @Devsol-01, any update on this?

[emarc99]

Would love to do this!