@scrthq/runlog 0.0.44 → 0.0.46

package/dist/runlog.js

@@ -26525,6 +26525,9 @@ var EntryBase = {
   tags: external_exports.array(external_exports.string()).optional().describe("Free tags, for cross-referencing and for filtering results out in some modes."),
   points: external_exports.number().int().min(0).optional().describe(
     "What a contestant earns for completing this result in a moderated mode. A result with points is a challenge the moderator can award; one without is an effect that lands on everyone."
+  ),
+  needs: external_exports.array(Id).optional().describe(
+    "Requirements this result depends on, by id from the pack's `requires`. A run that said it lacks one of them draws again instead of landing here \u2014 a barbell movement for someone without a barbell, an oven dish in a kitchen without one."
   )
 };
 var LookupEntry = external_exports.object({
@@ -26715,6 +26718,20 @@ var ResourceDef = external_exports.object({
 }).strict().describe(
   "A numeric track the player fills or spends: a progress clock, a word count, training volume, stock on hand."
 );
+var Clock = external_exports.object({
+  kind: external_exports.enum(["stopwatch", "timer"]).describe("A stopwatch counts up from the start of the unit; a timer counts down from `minutes`."),
+  minutes: external_exports.number().positive().max(24 * 60).optional().describe("How long a timer runs. Required for a timer; ignored by a stopwatch."),
+  label: external_exports.string().optional().describe("What the clock is called on screen. Defaults to the unit's name and number."),
+  auto: external_exports.boolean().default(true).describe("Start it when the unit is entered and stop it when the unit closes. Off, the player starts it by hand; it still stops with the unit.")
+}).strict().refine((c) => c.kind !== "timer" || c.minutes !== void 0, { message: "a timer needs minutes", path: ["minutes"] }).describe("A clock the unit runs: `stopwatch` to time it, `timer` with `minutes` to limit it. The time lands in the log when the unit closes.");
+var Requirement = external_exports.object({
+  id: Id.describe("Unique among requirements. Table entries name it in `needs`."),
+  label: external_exports.string().min(1).describe("What it is, in the words a person would use: Rocket League, a potter's wheel, an oven."),
+  kind: external_exports.enum(["game", "platform", "software", "equipment", "supplies", "space", "other"]).default("other").describe("What sort of thing it is, so a catalog can say 'needs a game' or 'needs equipment' at a glance."),
+  optional: external_exports.boolean().default(false).describe("Nice to have rather than needed. A player says at the start whether they have it, and results that `need` it are drawn again when they do not."),
+  note: external_exports.string().optional().describe("A line on where to get it, which version, or what will do instead."),
+  url: external_exports.string().url().optional().describe("Where to find it.")
+}).strict().describe("A physical or software requirement: the game and the system to play it on, a mod or training pack, a wheel, a kitchen, supplies.");
 var ChecklistItem = external_exports.union([
   external_exports.string().min(1),
   external_exports.object({
@@ -26864,6 +26881,7 @@ var Mode = external_exports.object({
   ).optional().describe(
     "Per-unit overrides, for modes with a fixed shape \u2014 'unit three always suffers a consequence', and the like."
   ),
+  clock: Clock.optional().describe("This mode's clock on every unit, instead of the pack's `unit.clock`."),
   moderated: external_exports.object({
     contestants: external_exports.object({
       min: external_exports.number().int().min(1).default(2).describe("Fewest contestants."),
@@ -26944,6 +26962,11 @@ var Pack = external_exports.object({
   author: external_exports.string().optional().describe("Who wrote the game."),
   description: external_exports.string().optional().describe("One or two sentences on what the game is."),
   homepage: external_exports.string().url().optional().describe("Where to find out more."),
+  category: external_exports.string().min(1).max(40).optional().describe("What kind of thing this is, in a word or two, for a catalog to group by: everyday, games, craft, fitness, cooking, writing\u2026"),
+  tags: external_exports.array(external_exports.string().min(1).max(40)).max(12).optional().describe("Free tags for a catalog to filter by: the game it is for, the hobby, the shape of play. Short, and in the words a person would search for."),
+  requires: external_exports.array(Requirement).max(20).optional().describe(
+    "What a person needs before playing, shown in the catalog and the rulebook: the game and a system that runs it, mods or training packs, a wheel, a kitchen, supplies. Mark the ones that are nice to have `optional`; results can `need` those and be drawn again for a player who lacks them."
+  ),
   license: License,
   capabilities: external_exports.array(Capability).default([]).describe(
     "Engine features this pack needs. Declaring them lets an older app refuse the pack with a clear message instead of misplaying it."
@@ -26953,6 +26976,7 @@ var Pack = external_exports.object({
   ),
   vocabulary: Vocabulary,
   unit: external_exports.object({
+    clock: Clock.optional().describe("A clock every unit runs. A mode can set its own with `clock`."),
     createsSubject: external_exports.boolean().default(true).describe("Whether entering a unit produces a new subject."),
     min: external_exports.number().int().min(1).default(1).describe("Fewest units in a run."),
     max: external_exports.number().int().min(1).default(20).describe("Most units in a run.")
@@ -27300,6 +27324,7 @@ function lintPack(pack) {
           }
           usesDecks = true;
           break;
+        case "startStopwatch":
         case "startTimer":
           usesTimers = true;
           break;
@@ -27320,6 +27345,18 @@ function lintPack(pack) {
       }
     });
   }
+  const requirements = new Map((pack.requires ?? []).map((r) => [r.id, r]));
+  for (const [tableId, table] of Object.entries(pack.tables)) {
+    table.entries.forEach((e, i) => {
+      for (const need of e.needs ?? []) {
+        const r = requirements.get(need);
+        if (!r) d.push(err("ref/unknown-requirement", `tables.${tableId}.entries[${i}].needs`, `needs unknown requirement ${need}`));
+        else if (!r.optional) {
+          d.push(warn("requirement/never-lacked", `tables.${tableId}.entries[${i}].needs`, `needs ${need}, which is not optional, so no run can lack it; the entry will never be skipped`));
+        }
+      }
+    });
+  }
   const predicateSites = [];
   for (const [tableId, table] of Object.entries(pack.tables)) {
     table.entries.forEach(
@@ -27591,7 +27628,8 @@ function lintPack(pack) {
   requireCap("decks", usesDecks, "uses decks");
   requireCap("resources", usesResources, "uses resources");
   requireCap("counters", counterIds.size > 0, "declares counters");
-  requireCap("timers", usesTimers, "starts timers");
+  const unitClock = Boolean(pack.unit.clock) || Object.values(pack.modes).some((m) => m.clock);
+  requireCap("timers", usesTimers || unitClock, "runs a clock");
   requireCap(
     "backwardTargeting",
     usesResolveTarget || !!pack.targeting && pack.targeting.strategy !== "none",
@@ -27966,6 +28004,14 @@ function howConsulted(table) {
       return "Find the row whose key matches what was drawn.";
   }
 }
+function an(word, capital = false) {
+  const w = word.trim().toLowerCase();
+  const vowel = /^[aeiou]/.test(w);
+  const soundsConsonant = /^(u[^aeiou]|un[aeiou]|uni|use|usu|ute|eu|one(?![a-z])|onc)/.test(w) || /^u[st][aeiou]/.test(w);
+  const silentH = /^(hour|honest|honor|heir|herb)/.test(w);
+  const article = vowel && !soundsConsonant || silentH ? "an" : "a";
+  return `${capital ? article[0].toUpperCase() + article.slice(1) : article} ${word}`;
+}
 function nouns(pack) {
   const v = pack.vocabulary;
   return {
@@ -28082,6 +28128,8 @@ function actionInWords(pack, a) {
     }
     case "startTimer":
       return a.label ? `${a.label} (${a.minutes} min)` : `start a ${a.minutes}-minute timer`;
+    case "startStopwatch":
+      return a.label ? `start the ${a.label} stopwatch` : "start a stopwatch";
     case "note":
       return a.text;
     case "setFlag":
@@ -28110,7 +28158,7 @@ function triggerPointInWords(pack, on) {
     case "immediately":
       return "Then";
     case "onEnterUnit":
-      return `When a ${n.unit} begins`;
+      return `When ${an(n.unit)} begins`;
     case "onDeclareSubject":
       return `When the ${n.subject} is declared`;
     case "afterWork":
@@ -28272,13 +28320,17 @@ function stepDetail(pack, step) {
 function whatYouNeed(pack) {
   const n = nouns(pack);
   const items = [];
+  for (const r of pack.requires ?? []) {
+    items.push(`${cap(r.label)}${r.optional ? " (optional; results that need it are drawn again without it)" : ""}${r.note ? ` \u2014 ${r.note}` : ""}${r.url ? ` (${r.url})` : ""}.`);
+  }
   const dice = diceInWords(diceNeeded(pack));
   if (dice) items.push(cap(dice) + ".");
   for (const deck of Object.values(pack.decks ?? {})) {
     if (deck.kind === "standard52") items.push(`A standard deck of playing cards${deck.includeJokers ? " with the jokers in" : ""}.`);
     else items.push(`${plural(deck.cards.length, "card", "cards")} for ${deck.title} \u2014 write them out, or use the app.`);
   }
-  if (pack.capabilities.includes("timers")) items.push("A timer.");
+  if (pack.capabilities.includes("timers") && !pack.unit.clock) items.push("A timer.");
+  if (pack.unit.clock) items.push(pack.unit.clock.kind === "timer" ? `A clock: every ${n.unit} is timed, ${pack.unit.clock.minutes} minutes. The app keeps it.` : `A clock: every ${n.unit} is timed. The app keeps it.`);
   items.push(pack.journal?.enabled === false ? `Somewhere to keep the ${n.run} log.` : `Somewhere to keep the ${n.run} log \u2014 the run log sheet, or the app.`);
   return items;
 }
@@ -28349,11 +28401,12 @@ function summaryDoc(pack) {
   const n = nouns(pack);
   const b = new Builder();
   b.p(pack.description);
+  b.p([pack.category ? `Category: ${pack.category}` : "", pack.tags?.length ? `Tags: ${pack.tags.join(", ")}` : ""].filter(Boolean).join(" \xB7 "), "muted");
   b.p(license(pack), "muted");
   b.h(2, "How it plays");
   const unitRange = `${pack.unit.min === pack.unit.max ? pack.unit.min : `${pack.unit.min}\u2013${pack.unit.max}`}`;
   b.p(
-    `A ${n.run} is a series of ${n.units}${pack.unit.createsSubject ? `, each producing a ${n.subject}` : ""}; ${unitRange} of them, depending on the mode. Each ${n.unit} moves through ${plural(pack.phases.length, "phase", "phases")}: ${pack.phases.map((p) => p.label).join(", ")}.`
+    `${an(n.run, true)} is a series of ${n.units}${pack.unit.createsSubject ? `, each producing ${an(n.subject)}` : ""}; ${unitRange} of them, depending on the mode. Each ${n.unit} moves through ${plural(pack.phases.length, "phase", "phases")}: ${pack.phases.map((p) => p.label).join(", ")}.`
   );
   b.table(["Mode", "Length", "Players", "About"], modeRows(pack, { notes: false }));
   b.h(2, "What is inside");
@@ -28363,7 +28416,7 @@ function summaryDoc(pack) {
   if (tables.length) parts.push(`${plural(tables.length, "table", "tables")}: ${tables.map((t) => `${t.title} (${howConsulted(t).replace(/\.$/, "").toLowerCase()}, ${plural(t.entries.length, "entry", "entries")})`).join("; ")}.`);
   if (decks.length) parts.push(`${plural(decks.length, "deck", "decks")}: ${decks.map((d) => d.kind === "cards" ? `${d.title} (${plural(d.cards.length, "card", "cards")})` : `${d.title} (a standard deck)`).join("; ")}.`);
   const states = Object.values(pack.states ?? {});
-  if (states.length) parts.push(`${plural(states.length, "state", "states")} a ${n.subject} or ${n.run} can carry: ${states.map((s) => s.label).join(", ")}.`);
+  if (states.length) parts.push(`${plural(states.length, "state", "states")} ${an(n.subject)} or ${n.run} can carry: ${states.map((s) => s.label).join(", ")}.`);
   const counters = Object.values(pack.counters ?? {}).filter((c) => !c.hidden);
   if (counters.length) parts.push(`${plural(counters.length, "tally", "tallies")}: ${counters.map((c) => c.label).join(", ")}.`);
   const resources = Object.values(pack.resources ?? {});
@@ -28388,14 +28441,14 @@ function rulebookDoc(pack) {
   b.list(whatYouNeed(pack));
   b.h(2, "Terms");
   b.terms([
-    { term: cap(n.run), text: `One session of play. A ${n.run} is a series of ${n.units}, and ends when you say so or when the game does.` },
+    { term: cap(n.run), text: `One session of play. ${an(n.run, true)} is a series of ${n.units}, and ends when you say so or when the game does.` },
     { term: cap(n.unit), text: `One round. Every ${n.unit} passes through the same phases${pack.unit.createsSubject ? ` and produces one ${n.subject}` : ""}.` },
-    ...pack.unit.createsSubject ? [{ term: cap(n.subject), text: `The thing a ${n.unit} makes. States attach to it, and consequences can land on it later.` }] : [],
-    { term: cap(n.finalize), text: `Closing a ${n.unit}. Once ${n.finalize.toLowerCase()}d, what it made is fixed unless a rule says otherwise.` },
+    ...pack.unit.createsSubject ? [{ term: cap(n.subject), text: `The thing ${an(n.unit)} makes. States attach to it, and consequences can land on it later.` }] : [],
+    { term: cap(n.finalize), text: `Closing ${an(n.unit)}. Once ${n.finalize.toLowerCase()}d, what it made is fixed unless a rule says otherwise.` },
     ...Object.entries(pack.vocabulary.terms ?? {}).map(([term, text]) => ({ term, text }))
   ]);
   if (pack.hierarchy?.length) b.p(`When rules contradict each other, the more specific wins, in this order: ${pack.hierarchy.join(" > ")}.`, "note");
-  b.h(2, `A ${n.unit}, step by step`);
+  b.h(2, `${an(n.unit, true)}, step by step`);
   b.list(flowSteps(pack, { detail: true }), true);
   if (pack.journal?.enabled !== false) b.p(`${pack.journal?.prompt ? `After each ${n.unit}: \u201C${pack.journal.prompt}\u201D` : `Keep a line of notes per ${n.unit}.`}${pack.journal?.required ? " A note is required before moving on." : ""}`);
   b.h(2, "Modes");
@@ -28430,7 +28483,7 @@ function rulebookDoc(pack) {
       ["State", "On", "Means"],
       states.map(([, s]) => [
         s.short ? `${s.label} (${s.short})` : s.label,
-        s.scope === "run" ? `the ${n.run}` : s.scope === "contestant" ? "a contestant" : `a ${n.subject}`,
+        s.scope === "run" ? `the ${n.run}` : s.scope === "contestant" ? "a contestant" : an(n.subject),
         [s.description ?? "", ...(s.semantics ?? []).map(semanticInWords), s.group ? `Replaces any other \u201C${s.group}\u201D state.` : "", s.until === "unitEnd" ? `Lifts when the ${n.unit} closes.` : ""].filter(Boolean).join(" ")
       ])
     );
@@ -28475,7 +28528,7 @@ function rulebookDoc(pack) {
     b.list(pack.triggers.map((t) => sentence(cap(triggerInWords(pack, t)))));
   }
   if (pack.endings?.length) {
-    b.h(2, `Ending a ${n.run}`);
+    b.h(2, `Ending ${an(n.run)}`);
     b.terms(pack.endings.map((e) => ({ term: e.label, text: [e.text ?? "", e.requires?.length ? `Available when ${conditionsInWords(pack, e.requires)}.` : ""].filter(Boolean).join(" ") })));
   }
   return { kind: "rulebook", layout: "book", title: pack.title, subtitle: byline(pack), blocks: b.blocks };
@@ -28487,7 +28540,7 @@ function quickstartDoc(pack) {
   b.h(2, "What you need");
   b.list(whatYouNeed(pack));
   b.h(2, "The words");
-  b.p(`A ${n.run} is one session. It is made of ${n.units}${pack.unit.createsSubject ? `, and each ${n.unit} makes one ${n.subject}` : ""}. Closing a ${n.unit} is called \u201C${n.finalize}\u201D.`);
+  b.p(`${an(n.run, true)} is one session. It is made of ${n.units}${pack.unit.createsSubject ? `, and each ${n.unit} makes one ${n.subject}` : ""}. Closing a ${n.unit} is called \u201C${n.finalize}\u201D.`);
   b.h(2, `Each ${n.unit}`);
   b.list(flowSteps(pack, { detail: false }), true);
   const d = pack.modes[pack.defaultMode];
@@ -28817,6 +28870,8 @@ function initialState(pack, e) {
     outcomes: [],
     obligations: [],
     firedOnce: [],
+    lacks: e.lacks ?? [],
+    clocks: [],
     contestants: [],
     awards: [],
     ending: null
@@ -29030,6 +29085,50 @@ function reduce(pack, log) {
         state.status = "ended";
         state.ending = event.ending;
         break;
+      case "ClockStarted":
+        if (!state.clocks.some((c) => c.id === event.clock)) {
+          state.clocks.push({
+            id: event.clock,
+            kind: event.kind,
+            label: event.label,
+            seconds: event.kind === "timer" ? event.seconds ?? null : null,
+            unit: state.unit,
+            status: "running",
+            startedAt: event.at,
+            runningSince: event.at,
+            accumulatedMs: 0,
+            elapsedMs: null,
+            expired: false
+          });
+        }
+        break;
+      case "ClockPaused": {
+        const c = state.clocks.find((x) => x.id === event.clock);
+        if (c && c.status === "running" && c.runningSince) {
+          c.accumulatedMs += Math.max(0, Date.parse(event.at) - Date.parse(c.runningSince));
+          c.runningSince = null;
+          c.status = "paused";
+        }
+        break;
+      }
+      case "ClockResumed": {
+        const c = state.clocks.find((x) => x.id === event.clock);
+        if (c && c.status === "paused") {
+          c.runningSince = event.at;
+          c.status = "running";
+        }
+        break;
+      }
+      case "ClockStopped": {
+        const c = state.clocks.find((x) => x.id === event.clock);
+        if (c && c.status !== "done") {
+          c.elapsedMs = event.elapsedMs;
+          c.runningSince = null;
+          c.status = "done";
+          c.expired = event.expired === true;
+        }
+        break;
+      }
       case "ContestantAdded":
         if (!state.contestants.some((c) => c.id === event.contestant)) {
           state.contestants.push({ id: event.contestant, name: event.name, states: [] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scrthq/runlog",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "Validate, lint, bundle and test Runlog rule packs.",
   "type": "module",
   "license": "MIT",