From 91e27c61608b73a6e83131b5220add68e9505ec9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=9C=A8=20Audrey=20=E2=9C=A8?= <audrey@audreyality.com>
Date: Tue, 11 Mar 2025 18:47:40 -0400
Subject: [PATCH] add name field and documentation

---
 .../src/tools/achievements/example-validators.ts      | 11 +++++++----
 libs/common/src/tools/achievements/types.ts           | 11 +++++++++--
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/libs/common/src/tools/achievements/example-validators.ts b/libs/common/src/tools/achievements/example-validators.ts
index ea5867b8130..8054ef25184 100644
--- a/libs/common/src/tools/achievements/example-validators.ts
+++ b/libs/common/src/tools/achievements/example-validators.ts
@@ -10,8 +10,9 @@ const FiveItemsCreatedAchievement = "five-vault-items-created" as AchievementId;
 
 const ItemCreatedValidator = {
   achievement: ItemCreatedAchievement,
+  name: "What an item!",
   metric: ItemCreatedProgress,
-  evaluator: Type.Threshold,
+  validator: Type.Threshold,
   trigger: "once",
   hidden: false,
   filter(item) {
@@ -27,8 +28,9 @@ const ItemCreatedValidator = {
 
 const ThreeItemsCreatedValidator = {
   achievement: ThreeItemsCreatedAchievement,
+  name: "Three times a charm",
   metric: ItemCreatedProgress,
-  evaluator: Type.Threshold,
+  validator: Type.Threshold,
   trigger: { low: 2, high: 3 },
   hidden: false,
   filter(item) {
@@ -45,9 +47,10 @@ const ThreeItemsCreatedValidator = {
 } satisfies AchievementValidator;
 
 const FiveItemsCreatedValidator = {
-  achievement: ThreeItemsCreatedAchievement,
+  achievement: FiveItemsCreatedAchievement,
+  name: "fiiivvve GoOoOoOolllllllD RIIIIIINGS!!!!!!",
   metric: ItemCreatedProgress,
-  evaluator: Type.Threshold,
+  validator: Type.Threshold,
   trigger: { low: 4, high: 5 },
   hidden: false,
   filter(item) {
diff --git a/libs/common/src/tools/achievements/types.ts b/libs/common/src/tools/achievements/types.ts
index 11dce304301..482106cb1f1 100644
--- a/libs/common/src/tools/achievements/types.ts
+++ b/libs/common/src/tools/achievements/types.ts
@@ -5,7 +5,7 @@ import { EventFormat, ServiceFormat, UserFormat } from "../log/ecs-format";
 
 import { Type } from "./data";
 
-export type EvaluatorType = keyof typeof Type;
+export type ValidatorId = keyof typeof Type;
 export type AchievementId = string & Tagged<"achievement">;
 export type MetricId = string & Tagged<"metric-id">;
 
@@ -19,15 +19,22 @@ export type AchievementEvent = AchievementProgressEvent | AchievementEarnedEvent
 
 // consumed by validator and achievement list (should this include a "toast-alerter"?)
 export type Achievement = {
+  // identifies the achievement being monitored
   achievement: AchievementId;
 
+  // human-readable name of the achievement
+  name: string;
+
+  // the metric observed by low/high triggers
   metric?: MetricId;
 
-  evaluator: EvaluatorType;
+  // identifies the validator containing filter/measure/earn methods
+  validator: ValidatorId;
 
   // pre-filter that disables the rule if it's met
   trigger: "once" | RequireAtLeastOne<{ low: number; high: number }>;
 
+  // whether or not the achievement is hidden until it is earned
   hidden: boolean;
 };