BlueGit

timfa questward

Files

questward / shared / quests / questProgress.js

questProgress.js

feat: branch quest steps and remember which steps were finished
timfa project_85689633_bot_760517ee9267c86ff1d6c3a0237abf7d · pushed by timfa · 4 weeks ago
25915c58 History
questProgress.js 3.3 KiB Download Raw
1/**
2 * Player quest position: step id, with a numeric index fallback for saves
3 * written before branching quests. `completedStepIds` in the progress blob
4 * records every step the player has ever finished (merge/loop safe).
5 */
6
7/** 1-based step index stored by older builds, or null when `state` is a step id. */
8export function legacyQuestStepNumber (state)
9{
10 if (typeof state === "number" && Number.isFinite(state))
11 {
12 const n = state | 0;
13 return n >= 1 ? n : null;
14 }
15 if (typeof state === "string" && /^\d+$/.test(state))
16 {
17 const n = Number(state) | 0;
18 return n >= 1 ? n : null;
19 }
20 return null;
21}
22
23/**
24 * DB `state_value` → runtime value.
25 * Pure integer strings stay numeric (legacy index). Anything else is a step id.
26 * A step id that is itself all digits is ambiguous with a legacy index; callers
27 * that know the quest def must prefer an exact stepId match (see resolveQuestStepId).
28 */
29export function parseStoredQuestState (stateValue)
30{
31 if (stateValue === "not-started" || stateValue === "completed")
32 { return stateValue; }
33 const index = legacyQuestStepNumber(stateValue);
34 if (index != null)
35 { return index; }
36 const text = String(stateValue ?? "").trim();
37 return text || "not-started";
38}
39
40export function serializeQuestState (state)
41{
42 if (state === "not-started" || state === "completed")
43 { return state; }
44 if (typeof state === "number" && Number.isFinite(state))
45 { return String(state | 0); }
46 return String(state ?? "");
47}
48
49export function isActiveQuestState (state)
50{
51 return state != null && state !== "not-started" && state !== "completed";
52}
53
54/**
55 * Current step id for an active quest, or the terminal token.
56 * Exact stepId match wins over a legacy index so a step literally named "2"
57 * is not read as "the second step".
58 */
59export function resolveQuestStepId (def, state)
60{
61 if (state === "completed")
62 { return "completed"; }
63 if (!isActiveQuestState(state))
64 { return "not-started"; }
65 const steps = def?.steps ?? [];
66 const text = typeof state === "number" ? String(state | 0) : String(state);
67 const byId = steps.find((step) => step?.stepId === text);
68 if (byId)
69 { return byId.stepId; }
70 const index = legacyQuestStepNumber(state);
71 if (index != null)
72 { return steps[index - 1]?.stepId ?? null; }
73 return text;
74}
75
76/**
77 * Steps the player has finished.
78 * A stored `completedStepIds` array is authoritative (including an empty one).
79 * Older rows derive it: every step before the numeric index, or every step
80 * when the quest is already completed.
81 */
82export function deriveCompletedStepIds (def, state, progress)
83{
84 if (Array.isArray(progress?.completedStepIds))
85 {
86 const out = [];
87 const seen = new Set();
88 for (const id of progress.completedStepIds)
89 {
90 const stepId = String(id ?? "").trim();
91 if (!stepId || seen.has(stepId))
92 { continue; }
93 seen.add(stepId);
94 out.push(stepId);
95 }
96 return out;
97 }
98 const steps = def?.steps ?? [];
99 if (state === "completed")
100 { return steps.map((step) => step.stepId).filter(Boolean); }
101 const index = legacyQuestStepNumber(state);
102 if (index == null)
103 { return []; }
104 return steps.slice(0, Math.max(0, index - 1)).map((step) => step.stepId).filter(Boolean);
105}
106
107export function rememberCompletedStep (ids, stepId)
108{
109 const next = Array.isArray(ids) ? [...ids] : [];
110 const id = String(stepId ?? "").trim();
111 if (id && !next.includes(id))
112 { next.push(id); }
113 return next;
114}