@novely/core 0.50.0 → 0.51.1

package/dist/index.d.ts

@@ -4,6 +4,10 @@ type Stored<T> = {
     set: (val: T) => void;
     get: () => T;
 };
+type Derived<T> = {
+    subscribe: (cb: (value: T) => void) => () => void;
+    get: () => T;
+};
 
 declare const RU: {
     NewGame: string;
@@ -100,9 +104,9 @@ type Context = {
     text: (str: string, resolve: () => void) => void;
     vibrate: (pattern: VibratePattern) => void;
     audio: {
-        voice: (source: string) => void;
+        voice: (source: string, paused: Derived<boolean>) => void;
         voiceStop: () => void;
-        music: (source: string, method: 'music' | 'sound') => AudioHandle;
+        music: (source: string, paused: Derived<boolean>, method: 'music' | 'sound') => AudioHandle;
         /**
          * Stop all sounds
          */
@@ -224,6 +228,7 @@ type RendererInit<$Language extends Lang, $Characters extends Record<string, Cha
     getCharacterAssets: (character: string, emotion: string) => string[];
     getDialogOverview: () => Promise<DialogOverview>;
     getResourseType: (url: string) => Promise<'image' | 'audio' | 'other'>;
+    setLanguage: (language: string) => void;
 };
 
 type LocalStorageStorageSettings = {
@@ -292,6 +297,8 @@ type Assign<A extends object, B extends object> = Pick<A, Exclude<keyof A, keyof
 type NonEmptyRecord<T extends Record<PropertyKey, unknown>> = keyof T extends never ? never : T;
 type CoreData = {
     dataLoaded: boolean;
+    paused: boolean;
+    focused: boolean;
 };
 type StackHolder = Save[] & {
     previous: Save | undefined;
@@ -370,6 +377,7 @@ type StoryOptionsDynamic = {
     load: (scene: string) => Promise<Story>;
 };
 type StoryOptions = StoryOptionsStatic | StoryOptionsDynamic;
+type OnLanguageChange<$Lang extends Lang> = (language: $Lang) => void;
 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.
@@ -590,9 +598,13 @@ interface NovelyInit<$Language extends Lang, $Characters extends Record<string,
      */
     defaultTypewriterSpeed?: TypewriterSpeed;
     /**
-     *
+     * Options to control story loading behaviour
      */
     storyOptions?: StoryOptions;
+    /**
+     * Will be called ONLY when language was changed by player
+     */
+    onLanguageChange?: OnLanguageChange<NoInfer<$Language>>;
 }
 type StateFunction<S extends State> = {
     (value: DeepPartial<S> | ((prev: S) => S)): void;
@@ -670,11 +682,15 @@ type CustomHandlerFunctionParameters<L extends string, S extends State> = {
      */
     getDomNodes: CustomHandlerFunctionGetFn;
     /**
-     * Function to get current Path. Path can be mutated. Can be helpful when making complex custom actions.
+     * @deprecated use `getSave` instead
+     */
+    getPath: () => Path;
+    /**
+     * Function to get current Save. It can be mutated.
      *
      * Only use it when you know what you do
      */
-    getPath: () => Path;
+    getSave: () => Save<S>;
     /**
      * Renderer Context
      */
@@ -715,6 +731,10 @@ type CustomHandlerFunctionParameters<L extends string, S extends State> = {
      * Function to replace template content
      */
     templateReplace: (content: TextContent<L, State>, values?: State) => string;
+    /**
+     * Is game currently paused
+     */
+    paused: Derived<boolean>;
 };
 type CustomHandlerFunction<L extends string, S extends State> = (parameters: CustomHandlerFunctionParameters<L, S>) => Thenable<void>;
 type CustomHandlerCalling = {
@@ -921,7 +941,7 @@ type TypesFromEngine<T> = T extends {
     types: EngineTypes<infer $Lang, infer $State, infer $Data, infer $Characters> | null;
 } ? EngineTypes<$Lang, $State, $Data, $Characters> : 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, storyOptions, }: 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, onLanguageChange, }: NovelyInit<$Language, $Characters, $State, $Data, $Actions>) => {
     /**
      * Function to set game script
      *
@@ -1045,6 +1065,33 @@ declare const novely: <$Language extends string, $Characters extends Record<stri
      * ```
      */
     setStorageData: (data: StorageData<$Language, $Data>) => void;
+    /**
+     * Function to control paused state. Custom Actions are provided with `paused` store they can subscribe to.
+     * This function will notify Custom Actions. Pause state can be used when showing ads.
+     * @example
+     * ```ts
+     * sdk.on('pause' () => engine.setPaused(true));
+     * sdk.on('resume', () => engine.setPaused(false));
+     * ```
+     */
+    setPaused: (paused: boolean) => void;
+    /**
+     * Function to control focused state. It will affect `paused` store passed to Custom Actions.
+     * This function can be used to pause game when it's not focused.
+     * @example
+     * ```ts
+     * import { pauseOnBlur } from '@novely/core';
+     *
+     * // Will subscribe to blur/focus events and call `setFocused`
+     * pauseOnBlur(engine);
+     *
+     * // OR
+     *
+     * sdk.on('focus' () => engine.setFocused(true));
+     * sdk.on('blur', () => engine.setFocused(false));
+     * ```
+     */
+    setFocused: (focused: boolean) => void;
 };
 
 type Part = Record<string, (...args: any[]) => ValidAction>;
@@ -1093,4 +1140,10 @@ declare const asset: {
     audio(source: string): NovelyAsset;
 };
 
-export { type ActionChoiceChoice, type ActionChoiceChoiceObject, type ActionInputOnInputMeta, type ActionInputSetup, type ActionInputSetupCleanup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterAssetSizes, type CharacterHandle, type CharactersData, type ChoiceCheckFunction, type ChoiceCheckFunctionProps, type ChoiceOnSelectFunction, type ChoiceOnSelectFunctionProps, type ChoiceParams, type ConditionCheckFunction, type ConditionParams, type Context, type CoreData, type CustomActionHandle, type CustomHandler, type CustomHandlerFunction, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type CustomHandlerInfo, type Data, type DeepPartial, type DefaultActionProxy, EN, type Emotions, type EngineTypes, type FunctionParams, type FunctionableValue, type GetActionParameters, type InputHandler, type Lang, type NovelyAsset, type NovelyInit, type NovelyScreen, type NovelyStorage, type Path, type PathItem, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type RendererInitPreviewReturn, type Save, type Stack, type StackHolder, type State, type StateFunction, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypeEssentials, type TypesFromEngine, type TypewriterSpeed, type ValidAction, asset, extendAction, localStorageStorage, novely };
+declare const pauseOnBlur: (engine: {
+    setFocused: (focused: boolean) => void;
+}) => {
+    unsubscribe: () => void;
+};
+
+export { type ActionChoiceChoice, type ActionChoiceChoiceObject, type ActionInputOnInputMeta, type ActionInputSetup, type ActionInputSetupCleanup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterAssetSizes, type CharacterHandle, type CharactersData, type ChoiceCheckFunction, type ChoiceCheckFunctionProps, type ChoiceOnSelectFunction, type ChoiceOnSelectFunctionProps, type ChoiceParams, type ConditionCheckFunction, type ConditionParams, type Context, type CoreData, type CustomActionHandle, type CustomHandler, type CustomHandlerFunction, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type CustomHandlerInfo, type Data, type DeepPartial, type DefaultActionProxy, type Derived, EN, type Emotions, type EngineTypes, type FunctionParams, type FunctionableValue, type GetActionParameters, type InputHandler, type Lang, type NovelyAsset, type NovelyInit, type NovelyScreen, type NovelyStorage, type Path, type PathItem, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type RendererInitPreviewReturn, type Save, type Stack, type StackHolder, type State, type StateFunction, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypeEssentials, type TypesFromEngine, type TypewriterSpeed, type ValidAction, asset, extendAction, localStorageStorage, novely, pauseOnBlur };

package/dist/index.js

@@ -951,6 +951,48 @@ var getCharactersData = (characters) => {
   return Object.fromEntries(mapped);
 };
 
+// src/store.ts
+var store = (current, subscribers = /* @__PURE__ */ new Set()) => {
+  const subscribe = (cb) => {
+    subscribers.add(cb), cb(current);
+    return () => {
+      subscribers.delete(cb);
+    };
+  };
+  const push = (value) => {
+    for (const cb of subscribers) cb(value);
+  };
+  const update = (fn) => {
+    push(current = fn(current));
+  };
+  const set2 = (val) => {
+    update(() => val);
+  };
+  const get = () => {
+    return current;
+  };
+  return { subscribe, update, set: set2, get };
+};
+var derive = (input, map) => {
+  return {
+    get: () => map(input.get()),
+    subscribe: (subscriber) => {
+      return input.subscribe((value) => {
+        return subscriber(map(value));
+      });
+    }
+  };
+};
+var immutable = (value) => {
+  return {
+    get: () => value,
+    subscribe: (subscriber) => {
+      subscriber(value);
+      return noop;
+    }
+  };
+};
+
 // src/custom-action.ts
 var createCustomActionNode = (id) => {
   const div = document.createElement("div");
@@ -978,7 +1020,8 @@ var handleCustomAction = (ctx, fn, {
   setClear,
   remove: renderersRemove,
   getStack: getStack2,
-  templateReplace
+  templateReplace,
+  paused
 }) => {
   const holder = getCustomActionHolder(ctx, fn);
   const flags = {
@@ -1023,6 +1066,9 @@ var handleCustomAction = (ctx, fn, {
   const getPath = () => {
     return stack.value[0];
   };
+  const getSave = () => {
+    return stack.value;
+  };
   return fn({
     flags,
     lang,
@@ -1033,8 +1079,10 @@ var handleCustomAction = (ctx, fn, {
     remove,
     rendererContext: ctx,
     getDomNodes,
+    getSave,
     getPath,
-    contextKey: ctx.id
+    contextKey: ctx.id,
+    paused: flags.preview ? immutable(false) : paused
   });
 };
 
@@ -1164,29 +1212,6 @@ var localStorageStorage = (options) => {
   };
 };
 
-// src/store.ts
-var store = (current, subscribers = /* @__PURE__ */ new Set()) => {
-  const subscribe = (cb) => {
-    subscribers.add(cb), cb(current);
-    return () => {
-      subscribers.delete(cb);
-    };
-  };
-  const push = (value) => {
-    for (const cb of subscribers) cb(value);
-  };
-  const update = (fn) => {
-    push(current = fn(current));
-  };
-  const set2 = (val) => {
-    update(() => val);
-  };
-  const get = () => {
-    return current;
-  };
-  return { subscribe, update, set: set2, get };
-};
-
 // src/translation.ts
 var RGX = /{{(.*?)}}/g;
 var split = (input, delimeters) => {
@@ -1330,6 +1355,11 @@ var getDialogOverview = async function() {
   return entries;
 };
 
+// src/utilities/document.ts
+var setDocumentLanguage = (language) => {
+  document.documentElement.lang = language;
+};
+
 // src/novely.ts
 var novely = ({
   characters,
@@ -1355,7 +1385,8 @@ var novely = ({
   saveOnUnload = true,
   startKey = "start",
   defaultTypewriterSpeed = DEFAULT_TYPEWRITER_SPEED,
-  storyOptions = { mode: "static" }
+  storyOptions = { mode: "static" },
+  onLanguageChange
 }) => {
   const languages = Object.keys(translation);
   const limitScript = pLimit(1);
@@ -1412,6 +1443,7 @@ var novely = ({
   const getLanguageWithoutParameters = () => {
     const language = getLanguage2(languages, getLanguage);
     if (languages.includes(language)) {
+      setDocumentLanguage(language);
       return language;
     }
     if (DEV5) {
@@ -1428,8 +1460,11 @@ var novely = ({
   };
   const storageData = store(initialData);
   const coreData = store({
-    dataLoaded: false
+    dataLoaded: false,
+    paused: false,
+    focused: document.visibilityState === "visible"
   });
+  const paused = derive(coreData, (s) => s.paused || !s.focused);
   const onDataLoadedPromise = async ({ cancelled }) => {
     if (cancelled) {
       dataLoaded.promise.then(onDataLoadedPromise);
@@ -1775,6 +1810,18 @@ var novely = ({
     }
     return String(c);
   };
+  const setLanguage = (lang) => {
+    storageData.update((prev) => {
+      if (languages.includes(lang)) {
+        prev.meta[0] = lang;
+      }
+      if (lang === prev.meta[0]) {
+        setDocumentLanguage(lang);
+        onLanguageChange?.(lang);
+      }
+      return prev;
+    });
+  };
   const renderer = createRenderer({
     mainContextKey: MAIN_CONTEXT_KEY,
     characters: getCharactersData(characters),
@@ -1804,7 +1851,8 @@ var novely = ({
       getStack: () => useStack(MAIN_CONTEXT_KEY),
       templateReplace: (...args) => templateReplace(...args)
     }),
-    getResourseType: getResourseTypeWrapper
+    getResourseType: getResourseTypeWrapper,
+    setLanguage
   });
   const useStack = createUseStackFunction(renderer);
   useStack(MAIN_CONTEXT_KEY).push(initial);
@@ -1882,27 +1930,27 @@ var novely = ({
       push();
     },
     playMusic({ ctx, push }, [source]) {
-      ctx.audio.music(unwrapAudioAsset(source), "music").play(true);
+      ctx.audio.music(unwrapAudioAsset(source), paused, "music").play(true);
       push();
     },
     pauseMusic({ ctx, push }, [source]) {
-      ctx.audio.music(unwrapAudioAsset(source), "music").pause();
+      ctx.audio.music(unwrapAudioAsset(source), paused, "music").pause();
       push();
     },
     stopMusic({ ctx, push }, [source]) {
-      ctx.audio.music(unwrapAudioAsset(source), "music").stop();
+      ctx.audio.music(unwrapAudioAsset(source), paused, "music").stop();
       push();
     },
     playSound({ ctx, push }, [source, loop]) {
-      ctx.audio.music(unwrapAudioAsset(source), "sound").play(loop || false);
+      ctx.audio.music(unwrapAudioAsset(source), paused, "sound").play(loop || false);
       push();
     },
     pauseSound({ ctx, push }, [source]) {
-      ctx.audio.music(unwrapAudioAsset(source), "sound").pause();
+      ctx.audio.music(unwrapAudioAsset(source), paused, "sound").pause();
       push();
     },
     stopSound({ ctx, push }, [source]) {
-      ctx.audio.music(unwrapAudioAsset(source), "sound").stop();
+      ctx.audio.music(unwrapAudioAsset(source), paused, "sound").stop();
       push();
     },
     voice({ ctx, push }, [source]) {
@@ -1912,7 +1960,7 @@ var novely = ({
         push();
         return;
       }
-      ctx.audio.voice(unwrapAudioAsset(audioSource));
+      ctx.audio.voice(unwrapAudioAsset(audioSource), paused);
       push();
     },
     stopVoice({ ctx, push }) {
@@ -2069,6 +2117,7 @@ var novely = ({
         state,
         lang,
         getStack: useStack,
+        paused,
         templateReplace
       });
       const next2 = () => {
@@ -2347,6 +2396,7 @@ var novely = ({
      * Data updates still will work in case Novely already was loaded
      */
     destroy() {
+      if (destroyed) return;
       dataLoaded.cancel();
       UIInstance.unmount();
       removeEventListener("beforeunload", throttledShortOnStorageDataChange);
@@ -2377,7 +2427,44 @@ var novely = ({
      * }
      * ```
      */
-    setStorageData
+    setStorageData,
+    /**
+     * Function to control paused state. Custom Actions are provided with `paused` store they can subscribe to.
+     * This function will notify Custom Actions. Pause state can be used when showing ads.
+     * @example
+     * ```ts
+     * sdk.on('pause' () => engine.setPaused(true));
+     * sdk.on('resume', () => engine.setPaused(false));
+     * ```
+     */
+    setPaused: (paused2) => {
+      coreData.update((prev) => {
+        prev.paused = paused2;
+        return prev;
+      });
+    },
+    /**
+     * Function to control focused state. It will affect `paused` store passed to Custom Actions.
+     * This function can be used to pause game when it's not focused.
+     * @example
+     * ```ts
+     * import { pauseOnBlur } from '@novely/core';
+     *
+     * // Will subscribe to blur/focus events and call `setFocused`
+     * pauseOnBlur(engine);
+     *
+     * // OR
+     *
+     * sdk.on('focus' () => engine.setFocused(true));
+     * sdk.on('blur', () => engine.setFocused(false));
+     * ```
+     */
+    setFocused: (focused) => {
+      coreData.update((prev) => {
+        prev.focused = focused;
+        return prev;
+      });
+    }
   };
 };
 
@@ -2466,12 +2553,53 @@ var EN = {
   Close: "Close",
   DialogOverview: "Dialog Overview"
 };
+
+// src/browser-events.ts
+var BLUR_HANDLERS = /* @__PURE__ */ new Set();
+var FOCUS_HANDLERS = /* @__PURE__ */ new Set();
+var registerEventListeners = (listeners) => {
+  BLUR_HANDLERS.add(listeners.blur);
+  FOCUS_HANDLERS.add(listeners.focus);
+  return () => {
+    BLUR_HANDLERS.delete(listeners.blur);
+    FOCUS_HANDLERS.delete(listeners.focus);
+  };
+};
+addEventListener("focus", function(event) {
+  for (const handler of FOCUS_HANDLERS) {
+    try {
+      handler.call(this.document, event);
+    } catch {
+    }
+  }
+});
+addEventListener("blur", function(event) {
+  for (const handler of BLUR_HANDLERS) {
+    try {
+      handler.call(this.document, event);
+    } catch {
+    }
+  }
+});
+var pauseOnBlur = (engine) => {
+  return {
+    unsubscribe: registerEventListeners({
+      focus: () => {
+        engine.setFocused(true);
+      },
+      blur: () => {
+        engine.setFocused(false);
+      }
+    })
+  };
+};
 export {
   EN,
   RU,
   asset,
   extendAction,
   localStorageStorage,
-  novely
+  novely,
+  pauseOnBlur
 };
 //# sourceMappingURL=index.js.map