squiffy-runtime 7.0.0-beta.4 → 7.0.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -30,6 +30,12 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
30
30
  const emitter = new Emitter<SquiffyEventMap>();
31
31
  const transitions: (() => Promise<void>)[] = [];
32
32
  let runningTransitions = false;
33
+ // A {{goto ... after=}} waiting to happen (#375)
34
+ let gotoTimer: ReturnType<typeof setTimeout> | undefined;
35
+ // {{goto}}s followed one after another without the player doing anything, so a loop can't hang
36
+ // the browser
37
+ let gotoHops = 0;
38
+ const MAX_GOTO_HOPS = 100;
33
39
 
34
40
  async function handleLink(link: HTMLElement): Promise<boolean> {
35
41
  if (runningTransitions) return false;
@@ -46,6 +52,12 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
46
52
  const passage = link.getAttribute("data-passage");
47
53
  const section = link.getAttribute("data-section");
48
54
 
55
+ if (passage !== null || section !== null) {
56
+ gotoHops = 0;
57
+ // The story-wide turn count (#377). A {{goto}} isn't a turn, as the player didn't click it.
58
+ set("turns", (get("turns") || 0) + 1);
59
+ }
60
+
49
61
  if (passage !== null) {
50
62
  disableLink(link);
51
63
  set("_turncount", get("_turncount") + 1);
@@ -113,7 +125,55 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
113
125
  }
114
126
  if (!load()) {
115
127
  await go(story.start);
128
+ return;
129
+ }
130
+ // Saved while waiting for a {{goto}}, so carry on waiting
131
+ const element = currentPassageElement ?? currentSectionElement;
132
+ const section = element?.getAttribute("data-goto");
133
+ if (section && section in story.sections) {
134
+ await followGoto({ section, after: Number(element.getAttribute("data-goto-after") || 0) });
135
+ }
136
+ }
137
+
138
+ function cancelGoto() {
139
+ clearTimeout(gotoTimer);
140
+ gotoTimer = undefined;
141
+ textProcessor.goto = null;
142
+ }
143
+
144
+ // Takes the {{goto}} from the text just shown, if there was one, and marks the section or
145
+ // passage element with it, so that going back skips it, and loading resumes it.
146
+ function takeGoto(element: HTMLElement) {
147
+ const pending = textProcessor.goto;
148
+ textProcessor.goto = null;
149
+ if (pending) {
150
+ element.setAttribute("data-goto", pending.section);
151
+ if (pending.after) element.setAttribute("data-goto-after", String(pending.after));
152
+ }
153
+ return pending;
154
+ }
155
+
156
+ async function followGoto(pending: { section: string; after: number } | null) {
157
+ if (!pending) return;
158
+ if (pending.after > 0) {
159
+ gotoTimer = setTimeout(() => {
160
+ gotoTimer = undefined;
161
+ gotoHops = 0;
162
+ void go(pending.section);
163
+ }, pending.after);
164
+ return;
165
+ }
166
+ if (++gotoHops > MAX_GOTO_HOPS) {
167
+ gotoHops = 0;
168
+ const element = currentPassageElement ?? currentSectionElement;
169
+ element.removeAttribute("data-goto");
170
+ const message = `stopped after ${MAX_GOTO_HOPS} in a row without the player clicking anything, going to "${pending.section}". Is there a loop?`;
171
+ console.error("Squiffy error in {{goto}}:", message);
172
+ element.insertAdjacentHTML("beforeend", errorHtml("Error in {{goto}}:", message));
173
+ save();
174
+ return;
116
175
  }
176
+ await go(pending.section);
117
177
  }
118
178
 
119
179
  async function processLink(link: HTMLElement) {
@@ -230,10 +290,14 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
230
290
  }
231
291
 
232
292
  async function go(sectionName: string) {
293
+ cancelGoto();
233
294
  const oldCanGoBack = canGoBack();
234
295
  currentSection = story.sections[sectionName];
235
296
  if (!currentSection) return;
236
297
  set("_section", sectionName);
298
+ // The story-wide turn count starts at 0 (#377), in a new story or one saved before it existed.
299
+ // It isn't a change the player made, so it isn't undone.
300
+ if (get("turns") === null) state.setInternal("turns", 0, false);
237
301
  state.setSeen(sectionName);
238
302
  const master = story.sections[""];
239
303
  if (master?.clear || currentSection.clear) {
@@ -261,6 +325,7 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
261
325
  setupInputValidation(currentSectionElement);
262
326
 
263
327
  set("_turncount", 0);
328
+ const pending = takeGoto(currentSectionElement);
264
329
  writeUndoLog();
265
330
  save();
266
331
 
@@ -269,6 +334,7 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
269
334
  emitter.emit("canGoBackChanged", { canGoBack: newCanGoBack });
270
335
  }
271
336
  emitter.emit("navigated", { section: sectionName });
337
+ await followGoto(pending);
272
338
  }
273
339
 
274
340
  function runJs(index: number, extra: any = null) {
@@ -283,6 +349,7 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
283
349
  story: {
284
350
  go: go,
285
351
  seen: (sectionOrPassage: string) => state.getSeen(sectionOrPassage),
352
+ visits: (sectionOrPassage: string) => state.getVisits(sectionOrPassage),
286
353
  },
287
354
  element: outputElementContainer,
288
355
  import: imports,
@@ -322,6 +389,7 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
322
389
  }
323
390
 
324
391
  async function showPassage(passageName: string) {
392
+ cancelGoto();
325
393
  const oldCanGoBack = canGoBack();
326
394
  let passage = currentSection.passages && currentSection.passages[passageName];
327
395
  const masterSection = story.sections[""];
@@ -383,6 +451,7 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
383
451
  // Setup validation for any inputs added by passages
384
452
  setupInputValidation(currentSectionElement);
385
453
 
454
+ const pending = takeGoto(currentPassageElement!);
386
455
  writeUndoLog();
387
456
  save();
388
457
  const newCanGoBack = canGoBack();
@@ -390,6 +459,7 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
390
459
  emitter.emit("canGoBackChanged", { canGoBack: newCanGoBack });
391
460
  }
392
461
  emitter.emit("navigated", { section: get("_section"), passage: passageName });
462
+ await followGoto(pending);
393
463
  }
394
464
 
395
465
  async function processAttributes(attributes: string[]) {
@@ -399,6 +469,7 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
399
469
  }
400
470
 
401
471
  function restart() {
472
+ cancelGoto();
402
473
  state.reset();
403
474
  // TODO: This feels like the wrong way of triggering location.reload()
404
475
  // - should be a separate setting to the scroll setting.
@@ -686,7 +757,11 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
686
757
  }
687
758
 
688
759
  function canGoBack() {
689
- return getHistoryCount() > 1;
760
+ // Sections and passages that went somewhere else with {{goto}} are skipped by goBack(), so
761
+ // they don't count, unless it's the current one, still waiting for its after= delay
762
+ const current = currentPassageElement ?? currentSectionElement;
763
+ const redirected = [...outputElement.querySelectorAll("[data-goto]")].filter(el => el !== current).length;
764
+ return getHistoryCount() - redirected > 1;
690
765
  }
691
766
 
692
767
  function goBack() {
@@ -696,6 +771,24 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
696
771
  return;
697
772
  }
698
773
 
774
+ cancelGoto();
775
+ // Undo back to the section or passage the player clicked through to, not one that went
776
+ // somewhere else with {{goto}}
777
+ do {
778
+ undoLast();
779
+ } while ((currentPassageElement ?? currentSectionElement).hasAttribute("data-goto") && getHistoryCount() > 1);
780
+ // The attributes were saved as they were undone, so save the output to match. Otherwise a saved
781
+ // game would come back with the text that was undone.
782
+ save();
783
+
784
+ if (!canGoBack()) {
785
+ emitter.emit("canGoBackChanged", { canGoBack: false });
786
+ }
787
+ const passage = currentPassageElement?.getAttribute("data-passage");
788
+ emitter.emit("navigated", passage ? { section: get("_section"), passage } : { section: get("_section") });
789
+ }
790
+
791
+ function undoLast() {
699
792
  const clearStack = getClearStack();
700
793
 
701
794
  if (currentPassageElement) {
@@ -755,12 +848,6 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
755
848
  setCurrentPassageElement();
756
849
  enableInputs(currentSectionElement);
757
850
  }
758
-
759
- if (!canGoBack()) {
760
- emitter.emit("canGoBackChanged", { canGoBack: false });
761
- }
762
- const passage = currentPassageElement?.getAttribute("data-passage");
763
- emitter.emit("navigated", passage ? { section: get("_section"), passage } : { section: get("_section") });
764
851
  }
765
852
 
766
853
  // We create a separate div inside the passed-in element. This allows us to clear the text output, but
@@ -875,6 +962,7 @@ export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> =>
875
962
  clickLink: handleLink,
876
963
  update: update,
877
964
  goBack: goBack,
965
+ canGoBack: canGoBack,
878
966
  on: (e, h) => emitter.on(e, h),
879
967
  off: (e, h) => emitter.off(e, h),
880
968
  once: (e, h) => emitter.once(e, h),
package/src/state.ts CHANGED
@@ -107,9 +107,15 @@ export class State {
107
107
  }
108
108
  }
109
109
 
110
+ // Records a visit to a section or passage: adds it to _seen_sections, and counts it in
111
+ // _visits (#377). Both are attributes, so going back undoes them.
110
112
  setSeen(sectionName: string) {
111
113
  let seenSections = this.get("_seen_sections");
112
114
  if (!seenSections) seenSections = [];
115
+ const visits = this.get("_visits") || {};
116
+ // A save from before _visits has the name in _seen_sections with no count: that's one visit
117
+ visits[sectionName] = this.getVisitsFrom(visits, seenSections, sectionName) + 1;
118
+ this.set("_visits", visits);
113
119
  if (seenSections.indexOf(sectionName) == -1) {
114
120
  seenSections.push(sectionName);
115
121
  this.set("_seen_sections", seenSections);
@@ -121,4 +127,14 @@ export class State {
121
127
  if (!seenSections) return false;
122
128
  return (seenSections.indexOf(sectionName) > -1);
123
129
  }
130
+
131
+ // How many times a section or passage has been visited, or 0 if it hasn't
132
+ getVisits(sectionName: string): number {
133
+ return this.getVisitsFrom(this.get("_visits") || {}, this.get("_seen_sections") || [], sectionName);
134
+ }
135
+
136
+ private getVisitsFrom(visits: Record<string, number>, seenSections: string[], sectionName: string): number {
137
+ if (Object.prototype.hasOwnProperty.call(visits, sectionName)) return visits[sectionName];
138
+ return seenSections.indexOf(sectionName) > -1 ? 1 : 0;
139
+ }
124
140
  }
@@ -31,6 +31,7 @@ export class TextProcessor {
31
31
  });
32
32
 
33
33
  this.handlebars.registerHelper("seen", (name: string) => this.state.getSeen(name));
34
+ this.handlebars.registerHelper("visits", (name: string) => this.state.getVisits(name));
34
35
  this.handlebars.registerHelper("get", (attribute: string) => this.state.get(attribute));
35
36
  this.handlebars.registerHelper("at", (section: string | string[]) => {
36
37
  const currentSection = this.state.get("_section");
@@ -48,6 +49,27 @@ export class TextProcessor {
48
49
  return value;
49
50
  };
50
51
 
52
+ // {{goto "section"}} and {{goto "section" after=3000}} (#375): the runtime goes there once
53
+ // the section or passage being shown has been written. Only the first one counts.
54
+ this.handlebars.registerHelper("goto", (...args: any[]) => {
55
+ const options = args.pop();
56
+ const section = args.length ? unwrapValue(args[0]) : undefined;
57
+ if (typeof section != "string" || !section || !(section in this.getStory().sections)) {
58
+ return new Handlebars.SafeString(errorHtml("Error in {{goto}}:",
59
+ section === undefined ? "expected a section name, e.g. {{goto \"cave\"}}" : `there is no section called "${section}"`));
60
+ }
61
+ let after = 0;
62
+ if (options.hash.after !== undefined) {
63
+ after = Number(unwrapValue(options.hash.after));
64
+ if (!Number.isFinite(after) || after < 0) {
65
+ return new Handlebars.SafeString(errorHtml("Error in {{goto}}:",
66
+ `after= should be a number of milliseconds, e.g. after=3000, not "${options.hash.after}"`));
67
+ }
68
+ }
69
+ this.goto ??= { section, after };
70
+ return "";
71
+ });
72
+
51
73
  // State modification helpers (side effects, no output)
52
74
  // These execute at render time, so they respect {{#if}} conditions
53
75
  this.handlebars.registerHelper("set", (attribute: string, value: any) => {
@@ -253,6 +275,10 @@ export class TextProcessor {
253
275
  return this.evaluated;
254
276
  }
255
277
 
278
+ // Where a {{goto}} asked to go. The runtime clears it before showing a section or passage, and
279
+ // follows it afterwards.
280
+ goto: { section: string; after: number } | null = null;
281
+
256
282
  private expressionCache = new Map<string, HandlebarsTemplateDelegate>();
257
283
  // Where the __value helper puts the value of the expression being evaluated
258
284
  private evaluated: unknown;
package/src/types.ts CHANGED
@@ -39,6 +39,8 @@ export interface SquiffyApi {
39
39
  clickLink: (link: HTMLElement) => Promise<boolean>;
40
40
  update: (story: Story) => void;
41
41
  goBack: () => void;
42
+ // Whether goBack() would go anywhere, e.g. to enable a Back button. canGoBackChanged says when it changes.
43
+ canGoBack: () => boolean;
42
44
 
43
45
  on<E extends keyof SquiffyEventMap>(
44
46
  event: E,
@@ -67,6 +69,7 @@ interface SquiffyJsFunctionApi {
67
69
  story: {
68
70
  go: (section: string) => void;
69
71
  seen: (sectionOrPassage: string) => boolean;
72
+ visits: (sectionOrPassage: string) => number;
70
73
  };
71
74
  }
72
75