plaza_wire 0.7.1

//! The flow-control notice payloads: what the turn, round and phase managers
//! wrap into an application's ops.
//!
//! They live here rather than beside the managers in `plaza` core because they
//! cross the wire and this crate is the wire vocabulary: a client names them
//! without the server's runtime and [`build`](crate::build)'s baked-in
//! vocabulary version covers their shape without any consumer listing another
//! crate's source files. Core re-exports them, so
//! `plaza::game_common::flow_control::phases::op_payloads::*` names them too.

use std::fmt::Debug;
use std::time::Duration;

use serde::{Deserialize, Serialize};

use crate::envelope::AgentId;

/// Payload for an Op that signals a phase change in the match flow.
/// Typically generated by `StateLogic` and broadcast to clients.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(bound = "PhaseId: Serialize + for<'de2> Deserialize<'de2>")]
pub struct PhaseChangedNoticePayload<PhaseId: Clone + Debug> {
  pub new_phase: PhaseId,
  pub previous_phase: Option<PhaseId>,
  /// Optional: Hint for how long this new phase might last (e.g., countdown duration).
  pub duration_hint: Option<Duration>,
  pub reason: Option<String>,
}

/// Payload for an Op allowing a client (e.g., admin, or via voting) to request a phase transition.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(bound = "PhaseId: Serialize + for<'de2> Deserialize<'de2>")]
pub struct RequestPhaseTransitionPayload<PhaseId: Clone + Debug> {
  pub target_phase: PhaseId,
}

/// Payload for an Op to update clients about countdown progress within a phase.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct CountdownTickNoticePayload {
  pub remaining_seconds: u32,
  /// Optional: An identifier for the phase this countdown belongs to, for client context.
  pub phase_context_id: Option<String>,
}

/// Payload for an Op sent by a client to indicate they are ending their turn.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(bound = "AppID: Serialize + for<'de2> Deserialize<'de2>")]
pub struct EndTurnRequestPayload<AppID: AgentId> {
  /// The player making the request (for validation).
  pub player_id: AppID,
}

/// Payload for an Op that signals a change in whose turn it is.
/// Typically generated by `StateLogic` (driven by a `TurnManager`) and broadcast to clients.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(bound = "TurnActorId: Serialize + for<'de2> Deserialize<'de2>")]
pub struct TurnChangedNoticePayload<TurnActorId: Clone + Debug> {
  /// `None` if, e.g., turns are over for a round.
  pub new_turn_actor: Option<TurnActorId>,
  pub previous_turn_actor: Option<TurnActorId>,
  /// Turns taken since the order began, counting from 1.
  ///
  /// Whether that means "this round" or "this match" is decided by how long
  /// you keep one manager: a per-round manager counts per round, a match-long
  /// one counts the match.
  pub turn_number: u32,
  pub time_limit_for_turn: Option<Duration>,
}

/// Payload for an Op that signals the start of a new round.
/// Typically generated by `StateLogic` (driven by a `RoundManager`) and broadcast.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct RoundStartedNoticePayload {
  pub round_number: u32,
  /// If a fixed number of rounds is known.
  pub total_rounds: Option<u32>,
}

/// Payload for an Op that signals the end of a round.
/// `AppSpecificRoundSummaryData` would be a type defined by the application,
/// needing `Clone + Debug + Serialize + Deserialize`.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(bound = "AppSpecificRoundSummaryData: Serialize + for<'de2> Deserialize<'de2>")]
pub struct RoundEndedNoticePayload<AppSpecificRoundSummaryData: Clone + Debug> {
  pub round_number: u32,
  pub reason: String,
  /// E.g., round winner, scores this round.
  pub summary_data: Option<AppSpecificRoundSummaryData>,
}