@novely/core 0.38.2 → 0.39.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import * as micro_memoize from 'micro-memoize';
+
 interface LocalStorageStorageSettings {
     key: string;
 }
@@ -99,7 +101,7 @@ type Context = {
     get root(): HTMLElement;
     set root(value: HTMLElement);
     character: (character: string) => CharacterHandle;
-    background: (background: string | BackgroundImage) => void;
+    background: (background: Record<string, string>) => void;
     dialog: (content: string, name: string, character: string | undefined, emotion: string | undefined, resolve: () => void) => void;
     choices: (question: string, choices: [name: string, active: boolean][], resolve: (selected: number) => void) => void;
     input: (question: string, onInput: (meta: ActionInputOnInputMeta<Lang, State>) => void, setup: ActionInputSetup, resolve: () => void) => void;
@@ -205,7 +207,7 @@ type RendererInitPreviewReturn = {
     assets: string[];
 };
 type RendererInit<$Language extends Lang, $Characters extends Record<string, Character<$Language>>> = {
-    characters: $Characters;
+    characters: CharactersData<$Characters>;
     characterAssetSizes: CharacterAssetSizes<$Characters>;
     set: (save: Save<State>) => Promise<void>;
     restore: (save?: Save<State>) => Promise<void>;
@@ -235,11 +237,17 @@ type RendererInit<$Language extends Lang, $Characters extends Record<string, Cha
     getStateFunction: (context: string) => StateFunction<State>;
     clearCustomAction: (ctx: Context, customAction: CustomHandler) => void;
     getLanguageDisplayName: (lang: Lang) => string;
+    getCharacterColor: (character: string) => string;
+    getCharacterAssets: (character: string, emotion: string) => string[];
     getResourseType: (url: string) => Promise<"image" | "audio" | "other">;
 };
 
 declare const getLanguage: (languages: string[]) => string;
 
+type NovelyAsset = {
+    readonly source: string;
+    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 Path = PathItem[];
@@ -315,6 +323,12 @@ type CharacterAssetSizes<$Characters extends Record<string, Character<Lang>>> =
         height: number;
     };
 };
+type CharactersData<$Characters extends Record<string, Character<Lang>>> = {
+    [Character in keyof $Characters]: {
+        name: $Characters[Character]['name'];
+        emotions: Array<keyof $Characters[Character]['emotions']>;
+    };
+};
 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.
@@ -535,7 +549,7 @@ type TypeEssentials<$Lang extends Lang, $State extends State, $Data extends Data
 };
 
 type Name<$Lang extends Lang> = string | Record<$Lang, string>;
-type Emotions<Emotion extends string = string> = Record<Emotion, string | string[]>;
+type Emotions<Emotion extends string = string> = Record<Emotion, string | NovelyAsset | (string | NovelyAsset)[]>;
 type Character<$Lang extends Lang = string> = {
     name: Name<$Lang>;
     color: string;
@@ -545,7 +559,7 @@ type Character<$Lang extends Lang = string> = {
 type ValidAction = ['choice', number] | ['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] | ['say', string, TextContent<string, State>] | ['end'] | ['showBackground', string | NonEmptyRecord<BackgroundImage>] | ['playMusic', string] | ['stopMusic', string] | ['pauseMusic', string] | ['playSound', audio: string, loop?: boolean] | ['pauseSound', string] | ['stopSound', string] | ['voice', string | Record<string, string>] | ['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] | ['say', string, TextContent<string, State>] | ['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[];
 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);
@@ -707,8 +721,8 @@ type ConditionCheckFunction<S extends State, R extends string | true | false> =
 type FunctionAction<L extends string, S extends State> = (props: FunctionActionProps<L, S>) => Thenable<void>;
 type ActionInputSetupCleanup = () => void;
 type ActionInputSetup = (input: HTMLInputElement) => ActionInputSetupCleanup | void;
-type BackgroundImage = Partial<Record<'portrait' | 'landscape' | 'all', string>> & Record<string, string>;
-type VoiceAction<L extends Lang> = (params: string | Partial<Record<L, string>>) => ValidAction;
+type BackgroundImage = Record<string, string | NovelyAsset>;
+type VoiceAction<L extends Lang> = (params: string | NovelyAsset | Partial<Record<L, string | NovelyAsset>>) => ValidAction;
 type ActionProxy<Characters extends Record<string, Character>, Languages extends Lang, S extends State> = {
     choice: {
         (...choices: [name: TextContent<Languages, S>, actions: ValidAction[], active?: ChoiceCheckFunction<Languages, S>][]): ValidAction;
@@ -727,13 +741,16 @@ type ActionProxy<Characters extends Record<string, Character>, Languages extends
     };
     say: (character: keyof Characters, content: TextContent<Languages, S>) => ValidAction;
     end: () => ValidAction;
-    showBackground: <T extends string | BackgroundImage>(background: T extends string ? T : T extends Record<PropertyKey, unknown> ? NonEmptyRecord<T> : never) => ValidAction;
-    playMusic: (audio: string) => ValidAction;
-    pauseMusic: (audio: string) => ValidAction;
-    stopMusic: (audio: string) => ValidAction;
-    playSound: (audio: string, loop?: boolean) => ValidAction;
-    pauseSound: (audio: string) => ValidAction;
-    stopSound: (audio: string) => ValidAction;
+    showBackground: {
+        (background: string | NovelyAsset): ValidAction;
+        <T extends Record<string, string | NovelyAsset>>(background: NonEmptyRecord<T>): ValidAction;
+    };
+    playMusic: (audio: string | NovelyAsset) => ValidAction;
+    pauseMusic: (audio: string | NovelyAsset) => ValidAction;
+    stopMusic: (audio: string | NovelyAsset) => ValidAction;
+    playSound: (audio: string | NovelyAsset, loop?: boolean) => ValidAction;
+    pauseSound: (audio: string | NovelyAsset) => ValidAction;
+    stopSound: (audio: string | NovelyAsset) => ValidAction;
     /**
      * Plays voice
      *
@@ -896,4 +913,30 @@ declare const novely: <$Language extends string, $Characters extends Record<stri
  */
 declare const extendAction: <Part0 extends Record<string, (...args: any[]) => ValidAction>, Part1 extends Record<string, (...args: any[]) => ValidAction>>(base: Part0, extension: Part1) => Readonly<Assign<Part0, Part1>>;
 
-export { type ActionInputOnInputMeta, type ActionInputSetup, type ActionInputSetupCleanup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterHandle, type ChoiceParams, type ConditionParams, type Context, type CoreData, type CustomActionHandle, type CustomHandler, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type Data, type DeepPartial, type DefaultActionProxy, EN, type Emotions, type FunctionParams, type FunctionableValue, type GetActionParameters, type InputHandler, JP, KK, type Lang, type NovelyInit, type NovelyScreen, type Path, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type RendererInitPreviewReturn, type Save, type Stack, type StackHolder, type State, type StateFunction, type Storage, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypeEssentials, type TypewriterSpeed, type ValidAction, extendAction, localStorageStorage, novely };
+/**
+ * Memoizes and returns an asset selection object based on provided file variants.
+ * The selected asset depends on the client's support for various formats.
+ *
+ * @param {...string} variants - A variable number of strings, each representing a potential asset file URL.
+ * @returns {NovelyAsset} An object representing the selected asset with `source` and `type` properties.
+ *
+ * @throws {Error} If in DEV mode and no arguments are provided.
+ * @example
+ * ```
+ * import { asset } from 'novely';
+ *
+ * // Passed first have higher priority
+ * const classroom = asset(
+ *   'classroom.avif',
+ *   'classroom.webp',
+ *   'classroom.jpeg'
+ * );
+ *
+ * setTimeout(() => {
+ *   console.log(classroom.source);
+ * }, 100);
+ * ```
+ */
+declare const asset: micro_memoize.Memoized<(...variants: string[]) => NovelyAsset>;
+
+export { 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 ChoiceParams, type ConditionParams, type Context, type CoreData, type CustomActionHandle, type CustomHandler, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type Data, type DeepPartial, type DefaultActionProxy, EN, type Emotions, type FunctionParams, type FunctionableValue, type GetActionParameters, type InputHandler, JP, KK, type Lang, type NovelyInit, type NovelyScreen, type Path, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type RendererInitPreviewReturn, type Save, type Stack, type StackHolder, type State, type StateFunction, type Storage, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypeEssentials, type TypewriterSpeed, type ValidAction, asset, extendAction, localStorageStorage, novely };