common_game/protocols/
planet_explorer.rs

1//! # Planet and Explorer protocol messages
2//!
3//! Defines the types of messages exchanged of the full duplex communication channel
4//! between the Planets and the Explorers
5//! For a more detailed view of the interactions between these two entities, visit the communications [diagrams](https://github.com/unitn-ap-2025/common/blob/main/MESSAGE_DIAGRAMS.md)
6
7use crate::components::resource::{
8    BasicResource, BasicResourceType, ComplexResource, ComplexResourceRequest, ComplexResourceType,
9    GenericResource,
10};
11use crate::utils::ID;
12use enum_as_inner::EnumAsInner;
13use std::collections::HashSet;
14use strum_macros::EnumDiscriminants;
15
16#[cfg(doc)]
17use crate::components::energy_cell::EnergyCell;
18
19/// This enum describes all possible messages from an Explorer to a Planet.
20#[derive(Debug, EnumAsInner, EnumDiscriminants)]
21#[strum_discriminants(name(ExplorerToPlanetKind))]
22#[strum_discriminants(derive(Hash))]
23pub enum ExplorerToPlanet {
24    /// This variant is used to ask the Planet for the available [`BasicResourceType`]
25    ///
26    /// **Expected Response**: [`PlanetToExplorer::SupportedResourceResponse`]
27    ///
28    /// **Use Case**: Asking Available Basic Resources
29    SupportedResourceRequest {
30        ///The ID of the Explorer sending the message
31        explorer_id: ID,
32    },
33    /// This variant is used to ask the Planet for the available [`ComplexResourceType`]
34    ///
35    /// **Expected Response**: [`PlanetToExplorer::SupportedCombinationResponse`]
36    ///
37    /// **Use Case**: Asking Available Complex Resources
38    SupportedCombinationRequest {
39        ///The ID of the Explorer sending the message
40        explorer_id: ID,
41    },
42    /// This variant is used to ask the Planet to generate a [`BasicResource`]
43    ///
44    /// **Expected Response**: [`PlanetToExplorer::GenerateResourceResponse`]
45    ///
46    /// **Use Case**: Asking to craft a Basic Resource
47    GenerateResourceRequest {
48        ///The ID of the Explorer sending the message
49        explorer_id: ID,
50        ///The basic resource to be generated
51        resource: BasicResourceType,
52    },
53    /// This variant is used to ask the Planet to generate a [`ComplexResource`] using the [`ComplexResourceRequest`]
54    ///
55    /// **Expected Response**: [`PlanetToExplorer::CombineResourceResponse`]
56    ///
57    /// **Use Case**: Asking to craft a Complex Resource
58    CombineResourceRequest {
59        ///The ID of the Explorer sending the message
60        explorer_id: ID,
61        ///The struct containing the complex resource to generate and the resources to be combined for the crafting to take place
62        msg: ComplexResourceRequest,
63    },
64    /// This variant is used to ask the Planet for the available charged [`EnergyCell`] number
65    ///
66    /// **Expected Response**: [`PlanetToExplorer::AvailableEnergyCellResponse`]
67    ///
68    /// **Use Case**: Asking the number of charged cells available
69    AvailableEnergyCellRequest {
70        ///The ID of the Explorer sending the message
71        explorer_id: ID,
72    },
73}
74
75impl ExplorerToPlanet {
76    /// Helper method to extract the `explorer_id` field from any message variant
77    /// without needing to match a specific one.
78    #[must_use]
79    pub fn explorer_id(&self) -> ID {
80        match self {
81            ExplorerToPlanet::SupportedResourceRequest { explorer_id, .. }
82            | ExplorerToPlanet::SupportedCombinationRequest { explorer_id, .. }
83            | ExplorerToPlanet::GenerateResourceRequest { explorer_id, .. }
84            | ExplorerToPlanet::CombineResourceRequest { explorer_id, .. }
85            | ExplorerToPlanet::AvailableEnergyCellRequest { explorer_id, .. } => *explorer_id,
86        }
87    }
88}
89
90/// This enum describes all possible messages from a Planet to an Explorer.
91#[derive(Debug, EnumAsInner, EnumDiscriminants)]
92#[strum_discriminants(name(PlanetToExplorerKind))]
93#[strum_discriminants(derive(Hash))]
94pub enum PlanetToExplorer {
95    /// This variant is used to send the available [`BasicResourceType`] list to the Explorer
96    ///
97    /// **Response To**: [`ExplorerToPlanet::SupportedResourceRequest`]
98    SupportedResourceResponse {
99        ///The list of available [`BasicResourceType`]
100        resource_list: HashSet<BasicResourceType>,
101    },
102    /// This variant is used to send the available [`ComplexResourceType`] list to the Explorer
103    ///
104    /// **Response To**: [`ExplorerToPlanet::SupportedCombinationRequest`]
105    SupportedCombinationResponse {
106        ///The list of available [`ComplexResourceType`]
107        combination_list: HashSet<ComplexResourceType>,
108    },
109    /// This variant is used to send the generated Basic Resource
110    ///
111    /// **Response To**: [`ExplorerToPlanet::GenerateResourceRequest`]
112    GenerateResourceResponse {
113        ///The optional Basic Resource generated:
114        ///
115        /// [Some(BasicResource)] if resource has been crafted correctly
116        ///
117        /// [None] if some error occurred
118        resource: Option<BasicResource>,
119    },
120    /// This variant is used to send the [`ComplexResource`] generated
121    ///
122    /// **Response To**: [`ExplorerToPlanet::CombineResourceRequest`]
123    CombineResourceResponse {
124        ///The complex basic resource generated:
125        ///
126        ///[Ok(ComplexResource)] if complex resource has been crafted correctly
127        ///
128        ///An [Err] triplet containing an error String and the two resources that were intended to be combined that are given
129        ///back to the Explorer
130        complex_response: Result<ComplexResource, (String, GenericResource, GenericResource)>,
131    },
132    /// This variant is used to send the number of available energy cells to the Explorer
133    ///
134    /// **Response To**: [`ExplorerToPlanet::AvailableEnergyCellRequest`]
135    AvailableEnergyCellResponse {
136        ///The number of charged cells available
137        available_cells: ID,
138    },
139    /// This variant is used by planets that are currently in a *stopped* state
140    /// to acknowledge any message coming from an explorer
141    Stopped,
142}
common_game/protocols/planet_explorer.rs

common_game/protocols/
planet_explorer.rs
