add name field and documentation

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) {

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;
 };