Skip to main content

ScorePool.ixx File

Container for accumulated scores by type. More...

Included Headers​

#include <stdexcept> #include <unordered_map> #include <helios.core.types> #include <helios.engine.mechanics.scoring.types.ScorePoolId> #include <helios.engine.mechanics.scoring.types> #include <helios.engine.mechanics.scoring.MaxScorePoolSnapshot> #include <helios.engine.mechanics.scoring.ScorePoolSnapshot>

Namespaces Index​

namespacehelios
namespaceengine

Main engine module aggregating core infrastructure and game systems. More...

namespacemechanics

High-level gameplay systems and components for game logic. More...

namespacescoring

Score management and tracking system for game mechanics. More...

Classes Index​

classScorePool

Container that accumulates scores by type within a pool. More...

Description​

Container for accumulated scores by type.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file ScorePool.ixx
3 * @brief Container for accumulated scores by type.
4 */
5module;
6
7
8#include <stdexcept>
9#include <unordered_map>
10
11export module helios.engine.mechanics.scoring.ScorePool;
12
13import helios.engine.mechanics.scoring.ScorePoolSnapshot;
14import helios.engine.mechanics.scoring.MaxScorePoolSnapshot;
15
16import helios.engine.mechanics.scoring.types;
17
18import helios.engine.mechanics.scoring.types.ScorePoolId;
19
20import helios.core.types;
21
22export namespace helios::engine::mechanics::scoring {
23
24 /**
25 * @brief Container that accumulates scores by type within a pool.
26 *
27 * @details ScorePool maintains a collection of scores indexed by ScoreTypeId,
28 * along with a running total. It tracks changes via a revision number that
29 * is incremented whenever a score value changes, enabling efficient change
30 * detection by observers.
31 *
32 * ScorePools are managed by ScorePoolManager, which handles command processing
33 * and pool lifecycle.
34 *
35 * @see ScorePoolManager
36 * @see ScorePoolSnapshot
37 * @see ScoreValueContext
38 */
39 class ScorePool {
40
41 /**
42 * @brief Unique identifier for this score pool.
43 */
44 helios::engine::mechanics::scoring::types::ScorePoolId scorePoolId_;
45
46 /**
47 * @brief Per-type score values indexed by ScoreTypeId.
48 */
49 std::vector<double> scores_;
50
51 /**
52 * @brief Running total of all scores in this pool.
53 */
54 double totalScore_{};
55
56 /**
57 * @brief The highest total score observed so far.
58 */
59 double maxScore_{};
60
61 /**
62 * @brief Revision counter for maxScore changes.
63 */
64 helios::engine::mechanics::scoring::types::ScorePoolRevision maxScoreRevision_{};
65
66 /**
67 * @brief Adds to the running total.
68 *
69 * @param total Value to add.
70 */
71 void addTotal(const double total) noexcept {
72 totalScore_ += total;
73 }
74
75 /**
76 * @brief Sets the running total directly.
77 *
78 * @param total New total value.
79 */
80 void setTotal(const double total) noexcept {
81 totalScore_ = total;
82 }
83
84 /**
85 * @brief The current revision of this ScorePool.
86 */
87 helios::engine::mechanics::scoring::types::ScorePoolRevision revision_{};
88
89 public:
90
91 /**
92 * @brief Constructs a ScorePool with the given ID.
93 *
94 * @param scorePoolId Unique identifier for this pool.
95 */
96 explicit ScorePool(const helios::engine::mechanics::scoring::types::ScorePoolId scorePoolId)
97 : scorePoolId_{scorePoolId} {}
98
99 /**
100 * @brief Returns the pool's unique identifier.
101 *
102 * @return The ScorePoolId.
103 */
104 [[nodiscard]] helios::engine::mechanics::scoring::types::ScorePoolId id() const noexcept {
105 return scorePoolId_;
106 }
107
108 /**
109 * @brief Adds a score from the given context.
110 *
111 * Updates both the per-type score and the running total.
112 *
113 * @param scoreContext Context containing type ID and value.
114 */
115 void addScore(const helios::engine::mechanics::scoring::types::ScoreValueContext& scoreContext) {
116
117 auto id = scoreContext.scoreTypeId.value();
118
119 if (id >= scores_.size()) {
120 scores_.resize(id + 1, 0.0f);
121 }
122
123 const double oldScore = scores_[id];
124 scores_[id] += scoreContext.value;
125 if (oldScore != scores_[id]) {
126 revision_++;
127 }
128 addTotal(scoreContext.value);
129 updateMaxScore();
130 }
131
132 /**
133 * @brief Resets all scores to zero.
134 */
135 void reset() noexcept {
136 std::fill(scores_.begin(), scores_.end(), 0.0f);
137 setTotal(0.0f);
138 revision_++;
139 }
140
141
142 /**
143 * @brief Returns the running total of all scores.
144 *
145 * @return The total score value.
146 */
147 [[nodiscard]] double totalScore() const noexcept {
148 return totalScore_;
149 }
150
151 /**
152 * @brief Returns the pool's unique identifier.
153 *
154 * @return The ScorePoolId.
155 */
156 [[nodiscard]] helios::engine::mechanics::scoring::types::ScorePoolId scorePoolId() const noexcept {
157 return scorePoolId_;
158 }
159
160 /**
161 * @brief Returns the current revision number.
162 *
163 * @details The revision is incremented whenever a score value changes.
164 * Used by observers to detect changes without polling values.
165 *
166 * @return The current ScorePoolRevision.
167 */
168 [[nodiscard]] helios::engine::mechanics::scoring::types::ScorePoolRevision revision() const noexcept {
169 return revision_;
170 }
171
172 /**
173 * @brief Returns a snapshot of the current pool state.
174 *
175 * @details The snapshot contains the pool ID, total score, and current
176 * revision. Useful for observers and UI binding.
177 *
178 * @return A ScorePoolSnapshot with current values.
179 */
180 [[nodiscard]] helios::engine::mechanics::scoring::ScorePoolSnapshot snapshot() const noexcept {
181 return {.scorePoolId = scorePoolId_, .totalScore = totalScore_, .revision = revision_};
182 }
183
184
185 /**
186 * @brief Recalculates the high score from the current total.
187 *
188 * Increments maxScoreRevision if the high score changes.
189 * Called automatically by addScore().
190 */
191 void updateMaxScore() noexcept {
192 const auto tmpScore = std::max(totalScore_, maxScore_);
193 if (tmpScore != maxScore_) {
194 maxScoreRevision_++;
195 maxScore_ = tmpScore;
196 }
197 }
198
199 /**
200 * @brief Returns the highest total score observed.
201 *
202 * @return The maximum score value.
203 */
204 [[nodiscard]] double maxScore() const noexcept {
205 return maxScore_;
206 }
207
208 /**
209 * @brief Returns the revision counter for maxScore changes.
210 *
211 * @return The current max score revision.
212 */
213 [[nodiscard]] helios::engine::mechanics::scoring::types::ScorePoolRevision maxScoreRevision() const noexcept {
214 return maxScoreRevision_;
215 }
216
217 /**
218 * @brief Returns a snapshot of the current high score state.
219 *
220 * @return A MaxScorePoolSnapshot with current values.
221 *
222 * @see MaxScorePoolSnapshot
223 */
224 [[nodiscard]] helios::engine::mechanics::scoring::MaxScorePoolSnapshot maxScoreSnapshot() const noexcept {
225 return {.scorePoolId = scorePoolId_, .maxScore = maxScore_, .revision = maxScoreRevision_};
226 }
227
228
229 };
230
231}

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.