@novely/core 0.49.0 → 0.51.0

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;
@@ -45,14 +49,6 @@ declare const RU: {
 };
 type BaseTranslationStrings = keyof typeof RU;
 declare const EN: Record<BaseTranslationStrings, string>;
-/**
- * Translated automatically
- */
-declare const KK: Record<BaseTranslationStrings, string>;
-/**
- * Translated automatically
- */
-declare const JP: Record<BaseTranslationStrings, string>;
 
 type CharacterHandle = {
     emotion: (emotion: string, render: boolean) => void;
@@ -108,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
          */
@@ -232,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 = {
@@ -256,7 +253,7 @@ type NovelyAsset = {
     readonly type: 'audio' | 'image';
 };
 type Thenable<T> = T | Promise<T>;
-type PathItem = [null, number | string] | ['jump', string] | ['choice', number] | ['choice:exit'] | ['condition', string] | ['condition:exit'] | ['exit'] | ['block', string] | ['block:exit'];
+type PathItem = [null, number] | ['jump', string] | ['choice', number] | ['choice:exit'] | ['condition', string] | ['condition:exit'] | ['exit'] | ['block', string] | ['block:exit'];
 type Path = PathItem[];
 type State = Record<string, any>;
 type Data = Record<string, any>;
@@ -300,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;
@@ -332,7 +331,7 @@ type CharactersData<$Characters extends Record<string, Character<Lang>>> = {
         emotions: Array<keyof $Characters[Character]['emotions']>;
     };
 };
-type AssetsPreloading = 'lazy' | 'blocking' | 'automatic';
+type AssetsPreloading = 'lazy' | 'automatic';
 type CloneFN = <T>(value: T) => T;
 type StoryOptionsStatic = {
     /**
@@ -378,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.
@@ -552,7 +552,11 @@ interface NovelyInit<$Language extends Lang, $Characters extends Record<string,
      */
     askBeforeExit?: boolean;
     /**
-     * @default "lazy"
+     * "automatic" will try to preload assets when possible
+     *
+     * "lazy" will load assets only when they are shown
+     *
+     * @default "automatic"
      */
     preloadAssets?: AssetsPreloading;
     /**
@@ -594,20 +598,33 @@ 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;
     (): S;
 };
+/**
+ * @deprecated `EngineTypes` should be used instead
+ */
 type TypeEssentials<$Lang extends Lang, $State extends State, $Data extends Data, $Characters extends Record<string, Character<$Lang>>> = {
     readonly l: $Lang | null;
     readonly s: $State | null;
     readonly d: $Data | null;
     readonly c: $Characters | null;
 };
+type EngineTypes<$Lang extends Lang = Lang, $State extends State = State, $Data extends Data = Data, $Characters extends Record<string, Character<$Lang>> = Record<string, Character<$Lang>>> = {
+    readonly l: $Lang;
+    readonly s: $State;
+    readonly d: $Data;
+    readonly c: $Characters;
+};
 type DialogOverviewEntry = {
     /**
      * Link to character voice
@@ -635,7 +652,7 @@ type Character<$Lang extends Lang = string> = {
 type ValidAction = ['choice', string | undefined, ...[string, unknown[], (() => boolean)?, (() => boolean)?, string?][]] | ['clear', Set<keyof DefaultActionProxy>?, Set<string>?, {
     music: Set<string>;
     sounds: Set<string>;
-}?] | ['condition', (state: State) => boolean, Record<string, ValidAction[]>] | ['dialog', string | undefined, TextContent<string, State>, string | undefined] | ['end'] | ['showBackground', string | NovelyAsset | BackgroundImage] | ['playMusic', string | NovelyAsset] | ['stopMusic', string | NovelyAsset] | ['pauseMusic', string | NovelyAsset] | ['playSound', audio: string | NovelyAsset, loop?: boolean] | ['pauseSound', string | NovelyAsset] | ['stopSound', string | NovelyAsset] | ['voice', string | NovelyAsset | Record<string, string | NovelyAsset>] | ['stopVoice'] | ['jump', string] | ['showCharacter', string, keyof Character['emotions'], string?, string?] | ['hideCharacter', string, string?, string?, number?] | ['animateCharacter', string, number, ...string[]] | ['wait', number | ((state: State) => number)] | ['function', FunctionAction<string, State>] | ['input', string, (meta: ActionInputOnInputMeta<string, State>) => void, ActionInputSetup?] | ['custom', CustomHandler<string, State>] | ['vibrate', ...number[]] | ['next'] | ['text', ...TextContent<string, State>[]] | ['exit'] | ['preload', string] | ['block', string] | ValidAction[];
+}?] | ['condition', (state: State) => boolean, Record<string, ValidAction[]>] | ['dialog', string | undefined, TextContent<string, State>, string | undefined] | ['end'] | ['showBackground', string | NovelyAsset | BackgroundImage] | ['playMusic', string | NovelyAsset] | ['stopMusic', string | NovelyAsset] | ['pauseMusic', string | NovelyAsset] | ['playSound', audio: string | NovelyAsset, loop?: boolean] | ['pauseSound', string | NovelyAsset] | ['stopSound', string | NovelyAsset] | ['voice', string | NovelyAsset | Record<string, string | NovelyAsset>] | ['stopVoice'] | ['jump', string] | ['showCharacter', string, keyof Character['emotions'], string?, string?] | ['hideCharacter', string, string?, string?, number?] | ['animateCharacter', string, number, ...string[]] | ['wait', number | ((state: State) => number)] | ['function', FunctionAction<string, State>] | ['input', string, (meta: ActionInputOnInputMeta<string, State>) => void, ActionInputSetup?] | ['custom', CustomHandler<string, State>] | ['vibrate', ...number[]] | ['next'] | ['text', ...TextContent<string, State>[]] | ['exit'] | ['preload', string | NovelyAsset] | ['block', string] | ValidAction[];
 type Story = Record<string, ValidAction[]>;
 type TextContent<L extends string, S extends State> = string | ((state: S) => string) | Record<L, string | ((state: S) => string)>;
 type FunctionableValue<T> = T | (() => T);
@@ -710,6 +727,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 = {
@@ -892,7 +913,7 @@ type ActionProxy<Characters extends Record<string, Character>, Languages extends
     vibrate: (...pattern: number[]) => ValidAction;
     next: () => ValidAction;
     text: (...text: TextContent<Languages, S>[]) => ValidAction;
-    preload: (source: string) => ValidAction;
+    preload: (source: string | NovelyAsset) => ValidAction;
     block: (scene: string) => ValidAction;
 };
 type DefaultActionProxy = ActionProxy<Record<string, Character>, Lang, State>;
@@ -902,12 +923,21 @@ type VirtualActions<$Characters extends Record<string, Character>, $Lang extends
     say: (character: keyof $Characters, content: TextContent<$Lang, $State>) => ValidAction;
 };
 
-type ConditionParams<T> = T extends TypeEssentials<any, infer $State, any, any> ? $State : never;
-type ChoiceParams<T> = T extends TypeEssentials<infer $Lang, infer $State, any, any> ? ChoiceCheckFunctionProps<$Lang, $State> : never;
-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;
+type ConditionParams<T> = T extends EngineTypes<any, infer $State, any, any> ? $State : never;
+type ChoiceParams<T> = T extends EngineTypes<infer $Lang, infer $State, any, any> ? ChoiceCheckFunctionProps<$Lang, $State> : never;
+type FunctionParams<T> = T extends EngineTypes<infer $Lang, infer $State, any, any> ? FunctionActionProps<$Lang, $State> : never;
+type InputHandler<T> = T extends EngineTypes<infer $Lang, infer $State, any, any> ? ActionInputOnInputMeta<$Lang, $State> : never;
+/**
+ * @example
+ * ```ts
+ * type Types = TypesFromEngine<typeof engine>;
+ * ```
+ */
+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
      *
@@ -958,7 +988,7 @@ declare const novely: <$Language extends string, $Characters extends Record<stri
     data: StateFunction<$Data>;
     /**
      * Used in combination with type utilities
-     *
+     * @deprecated Use `engine.types` instead
      * @example
      * ```ts
      * import type { ConditionParams, StateFunction } from '@novely/core';
@@ -969,6 +999,20 @@ declare const novely: <$Language extends string, $Characters extends Record<stri
      * ```
      */
     typeEssentials: TypeEssentials<$Language, $State, $Data, $Characters>;
+    /**
+     * Used in combination with type utilities
+     * @example
+     * ```ts
+     * import type { TypesFromEngine, ConditionParams, StateFunction } from '@novely/core';
+     *
+     * type Types = TypesFromEngine<typeof engine>;
+     *
+     * const conditionCheck = (state: StateFunction<ConditionParams<Types>>) => {
+     *   return state.age >= 18;
+     * }
+     * ```
+     */
+    types: EngineTypes<$Language, $State, $Data, $Characters> | null;
     /**
      * Replaces content inside {{braces}} using global data
      * @example
@@ -1017,6 +1061,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>;
@@ -1065,4 +1136,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 FunctionParams, type FunctionableValue, type GetActionParameters, type InputHandler, JP, KK, type Lang, type NovelyAsset, type NovelyInit, type NovelyScreen, type NovelyStorage, type Path, 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 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 };