🎨 Palette: Enhance score readability and achievement feedback

.Jules/palette.md

@@ -33,3 +33,7 @@
 ## 2024-04-24 - Avoiding Trailing Artifacts in CLI Applications
 **Learning:** When dynamically updating terminal lines using carriage return (`\r`), relying on hardcoded padding spaces to overwrite old text is brittle and leads to trailing text artifacts when new lines are shorter than previous ones.
 **Action:** Always use the ANSI escape sequence `\033[K` (Erase in Line) immediately after the carriage return (`\r`) to cleanly clear the line before writing new content, rather than manually managing padding spaces.
+
+## 2024-05-24 - Readable Numerics and Achievement Context
+**Learning:** In clicker-style games where scores can grow rapidly, raw integers become difficult to parse at a glance. Comma formatting (e.g., 1,234,567) significantly improves HUD readability. Additionally, "New Best" notifications are more impactful when they provide context by showing the previous record being surpassed.
+**Action:** Always format large numeric values with thousands separators in terminal HUDs and include the previous high score in achievement celebrations to provide immediate context for the player's progress.

src/main.cpp

@@ -9,6 +9,7 @@
 #include <algorithm>
 #include <csignal>
 #include <cstdlib>
+#include "utils.hpp"
 
 // Color and formatting macros for terminal output
 #define RESET     "\033[0m"
@@ -78,7 +79,7 @@ int main() {
     std::cout << CLR_CTRL << "==========================\n      SPEED CLICKER\n==========================\n" << CLR_RESET;
 
     if (highscore > 0) {
-        std::cout << " Personal Best: " << CLR_SCORE << highscore << CLR_RESET << "\n\n";
+        std::cout << " Personal Best: " << CLR_SCORE << formatWithCommas(highscore) << CLR_RESET << "\n\n";
     }
 
     std::cout << "Controls:\n " << CLR_CTRL << "[h]" << CLR_RESET << " Toggle Hard Mode (10x Speed!)\n "
@@ -142,10 +143,10 @@ int main() {
         }
 
         if (updateUI) {
-            std::cout << "\r" ERASE_LINE << CLR_SCORE << "Score: " << score << CLR_RESET << " | High: " << highscore << " "
+            std::cout << "\r" ERASE_LINE << CLR_SCORE << "Score: " << formatWithCommas(score) << CLR_RESET << " | High: " << formatWithCommas(highscore) << " "
                       << (hardMode ? CLR_HARD "[HARD MODE]" : CLR_NORM "[NORMAL MODE]")
-                      << (score > initialHighscore ? " NEW BEST! 🥳" : "")
-                      << std::flush;
+                      << (score > initialHighscore ? CLR_CTRL " ✨ NEW BEST! 🥳 (was " + formatWithCommas(initialHighscore) + ")" : "")
+                      << CLR_RESET << std::flush;
             updateUI = false;
         }
     }
@@ -155,9 +156,9 @@ int main() {
     }
 
     tcsetattr(STDIN_FILENO, TCSANOW, &oldt);
-    std::cout << "\n\n" << CLR_SCORE << "Final Score: " << score << CLR_RESET << "\n";
+    std::cout << "\n\n" << CLR_SCORE << "Final Score: " << formatWithCommas(score) << CLR_RESET << "\n";
     if (score > initialHighscore) {
-        std::cout << "Congratulations! A new personal best!\n";
+        std::cout << CLR_CTRL << "✨ Congratulations! A new personal best! ✨" << CLR_RESET << "\n";
     }
     std::cout << "Thanks for playing!\n";
     std::cout << "\033[?25h" << std::flush;

src/utils.hpp

@@ -0,0 +1,20 @@
+#ifndef UTILS_HPP
+#define UTILS_HPP
+
+#include <string>
+
+/**
+ * Formats a long long value with thousands separators (commas).
+ * Example: 1234567 -> "1,234,567"
+ */
+inline std::string formatWithCommas(long long value) {
+    std::string s = std::to_string(value);
+    int insertPosition = static_cast<int>(s.length()) - 3;
+    while (insertPosition > (value < 0 ? 1 : 0)) {
+        s.insert(insertPosition, ",");
+        insertPosition -= 3;
+    }
+    return s;
+}
+
+#endif