@novely/core 0.48.0 → 0.49.0

package/dist/index.d.ts

@@ -124,6 +124,7 @@ type Context = {
          */
         start: () => void;
     };
+    loading: (shown: boolean) => void;
     meta: {
         get restoring(): boolean;
         set restoring(value: boolean);
@@ -229,8 +230,8 @@ type RendererInit<$Language extends Lang, $Characters extends Record<string, Cha
     getLanguageDisplayName: (lang: Lang) => string;
     getCharacterColor: (character: string) => string;
     getCharacterAssets: (character: string, emotion: string) => string[];
+    getDialogOverview: () => Promise<DialogOverview>;
     getResourseType: (url: string) => Promise<'image' | 'audio' | 'other'>;
-    getDialogOverview: () => DialogOverview;
 };
 
 type LocalStorageStorageSettings = {
@@ -333,6 +334,50 @@ type CharactersData<$Characters extends Record<string, Character<Lang>>> = {
 };
 type AssetsPreloading = 'lazy' | 'blocking' | 'automatic';
 type CloneFN = <T>(value: T) => T;
+type StoryOptionsStatic = {
+    /**
+     * Static mode means that story is static
+     */
+    mode: 'static';
+};
+type StoryOptionsDynamic = {
+    /**
+     * Dynamic mode means that story parts can be loaded dynamically
+     */
+    mode: 'dynamic';
+    /**
+     * Number of saves to preload story for
+     * @default 4
+     */
+    preloadSaves?: number;
+    /**
+     * Function to dynamically load story parts.
+     *
+     * When engine find's unknown scene it will run this function.
+     * @example
+     * ```
+     * const load = async (scene: string): Promise<Story> => {
+     *   if (['part_2__act_1', 'part_2__act_2', 'part_2__act_3'].includes(scene)) {
+     *     const { getStory } = await import('./part-2.ts');
+     *
+     *     return getStory(engine.action);
+     *   }
+     *
+     *   if (scene === 'end') {
+     *     return {
+     *       'end': [
+     *         engine.action.text('The End')
+     *       ]
+     *     }
+     *   }
+     *
+     *   throw new Error(`Unknown scene: ${scene}`);
+     * }
+     * ```
+     */
+    load: (scene: string) => Promise<Story>;
+};
+type StoryOptions = StoryOptionsStatic | StoryOptionsDynamic;
 interface NovelyInit<$Language extends Lang, $Characters extends Record<string, Character<NoInfer<$Language>>>, $State extends State, $Data extends Data, $Actions extends Record<string, (...args: any[]) => ValidAction>> {
     /**
      * An object containing the characters in the game.
@@ -548,6 +593,10 @@ interface NovelyInit<$Language extends Lang, $Characters extends Record<string,
      * Typewriter speed set by default
      */
     defaultTypewriterSpeed?: TypewriterSpeed;
+    /**
+     *
+     */
+    storyOptions?: StoryOptions;
 }
 type StateFunction<S extends State> = {
     (value: DeepPartial<S> | ((prev: S) => S)): void;
@@ -858,7 +907,7 @@ type ChoiceParams<T> = T extends TypeEssentials<infer $Lang, infer $State, any,
 type FunctionParams<T> = T extends TypeEssentials<infer $Lang, infer $State, any, any> ? FunctionActionProps<$Lang, $State> : never;
 type InputHandler<T> = T extends TypeEssentials<infer $Lang, infer $State, any, any> ? ActionInputOnInputMeta<$Lang, $State> : never;
 
-declare const novely: <$Language extends string, $Characters extends Record<string, Character<$Language>>, $State extends State, $Data extends Data, $Actions extends Record<string, (...args: any[]) => ValidAction>>({ characters, characterAssetSizes, defaultEmotions, storage, storageDelay, renderer: createRenderer, initialScreen, translation, state: defaultState, data: defaultData, autosaves, migrations, throttleTimeout, getLanguage, overrideLanguage, askBeforeExit, preloadAssets, parallelAssetsDownloadLimit, fetch: request, cloneFunction: clone, saveOnUnload, startKey, defaultTypewriterSpeed, }: NovelyInit<$Language, $Characters, $State, $Data, $Actions>) => {
+declare const novely: <$Language extends string, $Characters extends Record<string, Character<$Language>>, $State extends State, $Data extends Data, $Actions extends Record<string, (...args: any[]) => ValidAction>>({ characters, characterAssetSizes, defaultEmotions, storage, storageDelay, renderer: createRenderer, initialScreen, translation, state: defaultState, data: defaultData, autosaves, migrations, throttleTimeout, getLanguage, overrideLanguage, askBeforeExit, preloadAssets, parallelAssetsDownloadLimit, fetch: request, cloneFunction: clone, saveOnUnload, startKey, defaultTypewriterSpeed, storyOptions, }: NovelyInit<$Language, $Characters, $State, $Data, $Actions>) => {
     /**
      * Function to set game script
      *

package/dist/index.global.js

@@ -600,40 +600,66 @@ var Novely = (() => {
     }
     return !blockExitStatements.every(([name], i) => name && name.startsWith(blockStatements[i][0]));
   };
-  var createReferFunction = (story) => {
-    const refer = (path) => {
+  var createReferFunction = ({ story, onUnknownSceneHit }) => {
+    const refer = async (path) => {
+      const { promise: ready, resolve: setReady } = Promise.withResolvers();
       let current = story;
       let precurrent = story;
       const blocks = [];
-      for (const [type, val] of path) {
-        if (type === "jump") {
-          precurrent = story;
-          current = current[val];
-        } else if (type === null) {
-          precurrent = current;
-          current = current[val];
-        } else if (type === "choice") {
-          blocks.push(precurrent);
-          current = current[val + 1][1];
-        } else if (type === "condition") {
-          blocks.push(precurrent);
-          current = current[2][val];
-        } else if (type === "block") {
-          blocks.push(precurrent);
-          current = story[val];
-        } else if (type === "block:exit" || type === "choice:exit" || type === "condition:exit") {
-          current = blocks.pop();
+      const refer2 = async () => {
+        for (const [type, val] of path) {
+          if (type === "jump") {
+            if (!current[val]) {
+              setReady(true);
+              await onUnknownSceneHit(val);
+            }
+            if (DEV && !story[val]) {
+              throw new Error(`Attempt to jump to unknown scene "${val}"`);
+            }
+            if (DEV && story[val].length === 0) {
+              throw new Error(`Attempt to jump to empty scene "${val}"`);
+            }
+            precurrent = story;
+            current = current[val];
+          } else if (type === null) {
+            precurrent = current;
+            current = current[val];
+          } else if (type === "choice") {
+            blocks.push(precurrent);
+            current = current[val + 1][1];
+          } else if (type === "condition") {
+            blocks.push(precurrent);
+            current = current[2][val];
+          } else if (type === "block") {
+            blocks.push(precurrent);
+            current = story[val];
+          } else if (type === "block:exit" || type === "choice:exit" || type === "condition:exit") {
+            current = blocks.pop();
+          }
         }
-      }
-      return current;
+        setReady(false);
+        return current;
+      };
+      const value = refer2();
+      const found = await ready;
+      return {
+        found,
+        value
+      };
+    };
+    const referGuarded = async (path) => {
+      return await (await refer(path)).value;
+    };
+    return {
+      refer,
+      referGuarded
     };
-    return refer;
   };
-  var exitPath = ({ path, refer, onExitImpossible }) => {
+  var exitPath = async ({ path, refer, onExitImpossible }) => {
     const last = path.at(-1);
     const ignore = [];
     let wasExitImpossible = false;
-    if (!isAction(refer(path))) {
+    if (!isAction(await refer(path))) {
       if (last && isNull(last[0]) && isNumber(last[1])) {
         last[1]--;
       } else {
@@ -641,7 +667,7 @@ var Novely = (() => {
       }
     }
     if (isExitImpossible(path)) {
-      const referred = refer(path);
+      const referred = await refer(path);
       if (isAction(referred) && isSkippedDuringRestore(referred[0])) {
         onExitImpossible?.();
       }
@@ -663,7 +689,7 @@ var Novely = (() => {
       path.push([`${name}:exit`]);
       const prev = findLastPathItemBeforeItemOfType(path.slice(0, i + 1), name);
       if (prev) path.push([null, prev[1] + 1]);
-      if (!isAction(refer(path))) {
+      if (!isAction(await refer(path))) {
         path.pop();
         continue;
       }
@@ -682,12 +708,16 @@ var Novely = (() => {
     }
     return path;
   };
-  var collectActionsBeforeBlockingAction = ({ path, refer, clone }) => {
+  var collectActionsBeforeBlockingAction = async ({
+    path,
+    refer,
+    clone
+  }) => {
     const collection = [];
-    let action = refer(path);
+    let action = await refer(path);
     while (true) {
       if (action == void 0) {
-        const { exitImpossible } = exitPath({
+        const { exitImpossible } = await exitPath({
           path,
           refer
         });
@@ -707,7 +737,7 @@ var Novely = (() => {
             if (!Array.isArray(branchContent)) continue;
             const virtualPath = clone(path);
             virtualPath.push(["choice", i], [null, 0]);
-            const innerActions = collectActionsBeforeBlockingAction({
+            const innerActions = await collectActionsBeforeBlockingAction({
               path: virtualPath,
               refer,
               clone
@@ -720,7 +750,7 @@ var Novely = (() => {
           for (const condition of conditions) {
             const virtualPath = clone(path);
             virtualPath.push(["condition", condition], [null, 0]);
-            const innerActions = collectActionsBeforeBlockingAction({
+            const innerActions = await collectActionsBeforeBlockingAction({
               path: virtualPath,
               refer,
               clone
@@ -741,7 +771,7 @@ var Novely = (() => {
       } else {
         nextPath(path);
       }
-      action = refer(path);
+      action = await refer(path);
     }
     return collection;
   };
@@ -761,7 +791,7 @@ var Novely = (() => {
     };
     return MAP[action];
   };
-  var getActionsFromPath = (story, path, filter) => {
+  var getActionsFromPath = async ({ story, path, filter, referGuarded }) => {
     let current = story;
     let precurrent;
     let ignoreNestedBefore = null;
@@ -776,6 +806,7 @@ var Novely = (() => {
     }, 0);
     const queue = [];
     const blocks = [];
+    await referGuarded(path);
     for (const [type, val] of path) {
       if (type === "jump") {
         precurrent = story;
@@ -919,7 +950,7 @@ var Novely = (() => {
       }
     }
     const run = async (match) => {
-      for await (const item of processedQueue) {
+      for (const item of processedQueue) {
         const result = match(item);
         if (isPromise(result)) {
           await result;
@@ -1456,7 +1487,8 @@ var Novely = (() => {
     cloneFunction: clone = klona,
     saveOnUnload = true,
     startKey = "start",
-    defaultTypewriterSpeed = DEFAULT_TYPEWRITER_SPEED
+    defaultTypewriterSpeed = DEFAULT_TYPEWRITER_SPEED,
+    storyOptions = { mode: "static" }
   }) => {
     const languages = Object.keys(translation);
     const limitScript = pLimit(1);
@@ -1466,21 +1498,27 @@ var Novely = (() => {
     const dataLoaded = createControlledPromise();
     let initialScreenWasShown = false;
     let destroyed = false;
+    if (storyOptions.mode === "dynamic") {
+      storyOptions.preloadSaves ??= 4;
+    }
+    const storyLoad = storyOptions.mode === "static" ? noop : storyOptions.load;
+    const onUnknownSceneHit = memoize(async (scene) => {
+      const part = await storyLoad(scene);
+      if (part) {
+        await script(part);
+      }
+    });
     const intime = (value) => {
       return times.add(value), value;
     };
     const scriptBase = async (part) => {
       if (destroyed) return;
       Object.assign(story, flatStory(part));
-      let loadingIsShown = false;
       if (!initialScreenWasShown) {
         renderer.ui.showLoading();
-        loadingIsShown = true;
       }
       if (preloadAssets === "blocking" && ASSETS_TO_PRELOAD.size > 0) {
-        if (!loadingIsShown) {
-          renderer.ui.showLoading();
-        }
+        renderer.ui.showLoading();
         await handleAssetsPreloading({
           ...renderer.misc,
           limiter: limitAssetsDownload,
@@ -1533,11 +1571,23 @@ var Novely = (() => {
     const coreData = store({
       dataLoaded: false
     });
-    const onDataLoadedPromise = ({ cancelled }) => {
+    const onDataLoadedPromise = async ({ cancelled }) => {
       if (cancelled) {
         dataLoaded.promise.then(onDataLoadedPromise);
         return;
       }
+      const preload = () => {
+        const saves = [...storageData.get().saves].reverse();
+        const sliced = saves.slice(0, storyOptions.mode === "dynamic" ? storyOptions.preloadSaves : 0);
+        for (const [path] of sliced) {
+          referGuarded(path);
+        }
+      };
+      if (preloadAssets === "blocking") {
+        await preload();
+      } else {
+        void preload();
+      }
       coreData.update((data2) => {
         data2.dataLoaded = true;
         return data2;
@@ -1663,7 +1713,14 @@ var Novely = (() => {
       const previous = stack.previous;
       const [path] = stack.value = latest;
       renderer.ui.showScreen("game");
-      const { queue, skip, skipPreserve } = getActionsFromPath(story, path, false);
+      const { found } = await refer(path);
+      if (found) context.loading(true);
+      const { queue, skip, skipPreserve } = await getActionsFromPath({
+        story,
+        path,
+        filter: false,
+        referGuarded
+      });
       const {
         run,
         keep: { keep, characters: characters2, audio: audio2 }
@@ -1672,7 +1729,12 @@ var Novely = (() => {
         skipPreserve
       });
       if (previous) {
-        const { queue: prevQueue } = getActionsFromPath(story, previous[0], false);
+        const { queue: prevQueue } = await getActionsFromPath({
+          story,
+          path: previous[0],
+          filter: false,
+          referGuarded
+        });
         for (let i = prevQueue.length - 1; i > queue.length - 1; i--) {
           const element = prevQueue[i];
           if (!isAction(element)) {
@@ -1690,6 +1752,7 @@ var Novely = (() => {
           data: latest[1]
         });
       }
+      context.loading(false);
       const lastQueueItem = queue.at(-1);
       const lastQueueItemRequiresUserAction = lastQueueItem && isBlockingAction(lastQueueItem);
       await run((item) => {
@@ -1706,10 +1769,13 @@ var Novely = (() => {
       if (!context.meta.goingBack) {
         context.meta.restoring = false;
       }
-      render(context);
+      await render(context);
       context.meta.restoring = context.meta.goingBack = false;
     };
-    const refer = createReferFunction(story);
+    const { refer, referGuarded } = createReferFunction({
+      story,
+      onUnknownSceneHit
+    });
     const exit = (force = false, saving = true) => {
       const ctx = renderer.getContext(MAIN_CONTEXT_KEY);
       const stack = useStack(ctx);
@@ -1761,8 +1827,16 @@ var Novely = (() => {
         });
       }
       const [path, data2] = save2;
-      const { queue } = getActionsFromPath(story, path, true);
       const ctx = renderer.getContext(name);
+      const { found } = await refer(path);
+      if (found) ctx.loading(true);
+      const { queue } = await getActionsFromPath({
+        story,
+        path,
+        filter: true,
+        referGuarded
+      });
+      ctx.loading(false);
       ctx.meta.restoring = true;
       ctx.meta.preview = true;
       const processor = createQueueProcessor(queue, {
@@ -1851,21 +1925,26 @@ var Novely = (() => {
       }
       return String(c) || "";
     };
-    const getDialogOverview = () => {
+    const getDialogOverview = async () => {
       const { value: save2 } = useStack(MAIN_CONTEXT_KEY);
       const stateSnapshots = save2[3];
       if (stateSnapshots.length == 0) {
         return [];
       }
-      const { queue } = getActionsFromPath(story, save2[0], false);
+      const { queue } = await getActionsFromPath({
+        story,
+        path: save2[0],
+        filter: false,
+        referGuarded
+      });
       const [lang] = storageData.get().meta;
       const dialogItems = [];
-      for (let p = 0, a = stateSnapshots.length, i = queue.length - 1; a > 0; i--) {
+      for (let p = 0, a = stateSnapshots.length, i = queue.length - 1; a > 0 && i > 0; i--) {
         const action2 = queue[i];
         if (action2[0] === "dialog") {
           const [_, name, text] = action2;
           let voice = void 0;
-          for (let j = i - 1; j > p; j--) {
+          for (let j = i - 1; j > p && j > 0; j--) {
             const action3 = queue[j];
             if (isUserRequiredAction(action3) || isSkippedDuringRestore(action3[0])) break;
             if (action3[0] === "stopVoice") break;
@@ -1947,14 +2026,14 @@ var Novely = (() => {
         matchActionOptions.push(ctx);
         if (!ctx.meta.preview) interactivity(true);
       },
-      onBeforeActionCall({ action: action2, props, ctx }) {
+      async onBeforeActionCall({ action: action2, props, ctx }) {
         if (preloadAssets !== "automatic") return;
         if (ctx.meta.preview || ctx.meta.restoring) return;
         if (!isBlockingAction([action2, ...props])) return;
         try {
-          const collection = collectActionsBeforeBlockingAction({
+          const collection = await collectActionsBeforeBlockingAction({
             path: nextPath(clone(useStack(ctx).value[0])),
-            refer,
+            refer: referGuarded,
             clone
           });
           for (const [action3, ...props2] of collection) {
@@ -2127,12 +2206,6 @@ var Novely = (() => {
         });
       },
       jump({ ctx, data: data2 }, [scene]) {
-        if (DEV && !story[scene]) {
-          throw new Error(`Attempt to jump to unknown scene "${scene}"`);
-        }
-        if (DEV && story[scene].length === 0) {
-          throw new Error(`Attempt to jump to empty scene "${scene}"`);
-        }
         const stack = useStack(ctx);
         stack.value[0] = [
           ["jump", scene],
@@ -2233,11 +2306,11 @@ var Novely = (() => {
         ctx.clearBlockingActions("text");
         ctx.text(string, forward);
       },
-      exit({ ctx, data: data2 }) {
+      async exit({ ctx, data: data2 }) {
         if (ctx.meta.restoring) return;
-        const { exitImpossible } = exitPath({
+        const { exitImpossible } = await exitPath({
           path: useStack(ctx).value[0],
-          refer,
+          refer: referGuarded,
           onExitImpossible: () => {
             match("end", [], {
               ctx,
@@ -2283,10 +2356,17 @@ var Novely = (() => {
       preloadAssets,
       storageData
     });
-    const render = (ctx) => {
+    const render = async (ctx) => {
       const stack = useStack(ctx);
       const [path, state] = stack.value;
-      const referred = refer(path);
+      const { found, value } = await refer(path);
+      if (found) {
+        ctx.loading(true);
+      }
+      const referred = await value;
+      if (found) {
+        ctx.loading(false);
+      }
       if (isAction(referred)) {
         const [action2, ...props] = referred;
         match(action2, props, {