| 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. */ |
| 8 | export 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 | */ |
| 29 | export 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 | |
| 40 | export 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 | |
| 49 | export 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 | */ |
| 59 | export 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 | */ |
| 82 | export 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 | |
| 107 | export 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 | } |