narraleaf-react 0.1.3 → 0.1.4

package/README.md

@@ -1,8 +1,8 @@
-![](./docs/nlr-logo-banner.png)
+![](docs/nlr-logo-banner.png)
 
 # NarraLeaf-React
 
-English | [简体中文](./docs/README.zh-CN.md)
+English | [简体中文](docs/README.zh-CN.md)
 
 A React visual novel player framework
 
@@ -34,7 +34,7 @@ Read more in [🛠React.NarraLeaf.com](https://react.narraleaf.com)
 ### Example
 
 ```bash
-npx create-react-app my-first-narraleaf-app --template my-first-narraleaf-app
+npx create-react-app nlr-app --template my-first-narraleaf-app
 ```
 
 to start
@@ -43,39 +43,11 @@ to start
 npm start
 ```
 
-### Performance
-
-Please enable image cache for a better performance.  
-Narraleaf-React tries to cache the images before showing them, but it is recommended to enable cache on your server.
-
-for NextJS, add this to your `next.config.js`:
-
-```js
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-        async headers() {
-            return [
-                {
-                    source: '/YOUR_IMAGE_ENDPOINT/(.*)', // ex: /static/images/(.*)
-                    headers: [
-                        {
-                            key: 'Cache-Control',
-                            value: 'public, max-age=31536000, immutable',
-                        },
-                    ],
-                }
-            ]
-        }
-    };
-
-export default nextConfig;
-```
-
 ## License
 
 > NarraLeaf-React is licensed under the MPL License.
-> 
-> We updated the license to MPL on 2024-9-24. 
+>
+> We updated the license to MPL on 2024-9-24.
 
 ## Contributing
 

package/dist/game/nlcore/action/actionTypes.d.ts

@@ -11,6 +11,7 @@ import type { Sound } from "../elements/sound";
 import type { Script } from "../elements/script";
 import { Sentence } from "../elements/character/sentence";
 import type { TransformDefinitions } from "../elements/transform/type";
+import { Image } from "../elements/image";
 export declare const CharacterActionTypes: {
     readonly say: "character:say";
     readonly action: "character:action";
@@ -56,9 +57,10 @@ export declare const ImageActionTypes: {
     readonly setTransition: "image:setTransition";
     readonly applyTransition: "image:applyTransition";
     readonly flush: "image:flush";
+    readonly initWearable: "image:initWearable";
 };
 export type ImageActionContentType = {
-    [K in typeof ImageActionTypes[keyof typeof ImageActionTypes]]: K extends "image:setSrc" ? [string] : K extends "image:setPosition" ? [CommonDisplayable["position"], Transform<TransformDefinitions.ImageTransformProps>] : K extends "image:show" ? [void, Transform<TransformDefinitions.ImageTransformProps>] : K extends "image:hide" ? [void, Transform<TransformDefinitions.ImageTransformProps>] : K extends "image:applyTransform" ? [void, Transform<TransformDefinitions.ImageTransformProps>, string] : K extends "image:init" ? [Scene?] : K extends "image:dispose" ? [] : K extends "image:setTransition" ? [ITransition | null] : K extends "image:applyTransition" ? [ITransition] : K extends "image:flush" ? [] : any;
+    [K in typeof ImageActionTypes[keyof typeof ImageActionTypes]]: K extends "image:setSrc" ? [string] : K extends "image:setPosition" ? [CommonDisplayable["position"], Transform<TransformDefinitions.ImageTransformProps>] : K extends "image:show" ? [void, Transform<TransformDefinitions.ImageTransformProps>] : K extends "image:hide" ? [void, Transform<TransformDefinitions.ImageTransformProps>] : K extends "image:applyTransform" ? [void, Transform<TransformDefinitions.ImageTransformProps>, string] : K extends "image:init" ? [Scene?] : K extends "image:dispose" ? [] : K extends "image:setTransition" ? [ITransition | null] : K extends "image:applyTransition" ? [ITransition] : K extends "image:flush" ? [] : K extends "image:initWearable" ? [Image] : any;
 };
 export declare const ConditionActionTypes: {
     readonly action: "condition:action";

package/dist/game/nlcore/action/actions/imageAction.d.ts

@@ -17,6 +17,7 @@ export declare class ImageAction<T extends typeof ImageActionTypes[keyof typeof
         readonly setTransition: "image:setTransition";
         readonly applyTransition: "image:applyTransition";
         readonly flush: "image:flush";
+        readonly initWearable: "image:initWearable";
     };
     executeAction(state: GameState): CalledActionResult | Awaitable<CalledActionResult, any>;
 }

package/dist/game/nlcore/action/actions.d.ts

@@ -2,8 +2,11 @@ import { ContentNode } from "../action/tree/actionTree";
 import { LogicAction } from "../action/logicAction";
 import { Action } from "../action/action";
 import { Chained, Proxied } from "../action/chain";
+import { Awaitable } from "../../../util/data";
+import { CalledActionResult } from "../gameTypes";
 export declare class TypedAction<ContentType extends Record<string, any> = Record<string, any>, T extends keyof ContentType & string = keyof ContentType & string, Callee extends LogicAction.GameElement = LogicAction.GameElement> extends Action<ContentType[T], Callee, T> {
     callee: Callee;
     constructor(callee: Proxied<Callee, Chained<LogicAction.Actions, Callee>>, type: T, contentNode: ContentNode<ContentType[T]>);
     unknownType(): void;
+    resolveAwaitable<T extends CalledActionResult = any>(handler: (resolve: ((value: T) => void), awaitable: Awaitable<CalledActionResult, T>) => Promise<void> | void, awaitable?: Awaitable<CalledActionResult, T>): Awaitable<CalledActionResult, T>;
 }

package/dist/game/nlcore/action/logicAction.d.ts

@@ -22,7 +22,7 @@ import { ControlAction } from "../action/actions/controlAction";
 import { Text } from "../elements/text";
 import { TextAction } from "../action/actions/textAction";
 export declare namespace LogicAction {
-    type Displayable = Text;
+    type Displayable = Text | Image;
     type GameElement = Character | Scene | Story | Image | Condition | Script | Menu | Sound | Control | Text;
     type Actions = (TypedAction | CharacterAction | ConditionAction | ImageAction | SceneAction | ScriptAction | StoryAction | MenuAction | SoundAction | ControlAction | TextAction);
     type ActionTypes = Values<typeof CharacterActionTypes> | Values<typeof ConditionActionTypes> | Values<typeof ImageActionTypes> | Values<typeof SceneActionTypes> | Values<typeof ScriptActionTypes> | Values<typeof StoryActionTypes> | Values<typeof MenuActionTypes> | Values<typeof SoundAction.ActionTypes> | Values<typeof ControlAction.ActionTypes> | Values<typeof TextAction.ActionTypes>;

package/dist/game/nlcore/elements/image.d.ts

@@ -1,4 +1,3 @@
-import React from "react";
 import type { TransformDefinitions } from "../elements/transform/type";
 import { Actionable } from "../action/actionable";
 import { Transform } from "./transform/transform";
@@ -11,25 +10,21 @@ export type ImageConfig = {
     src: string | StaticImageData;
     display: boolean;
     disposed?: boolean;
+    wearables: Image[];
+    isWearable?: boolean;
 } & CommonDisplayable;
 export type ImageDataRaw = {
     state: Record<string, any>;
 };
 export type ImageEventTypes = {
-    "event:image.init": [];
-    "event:image.mount": [];
-    "event:image.unmount": [];
-    "event:image.ready": [React.MutableRefObject<HTMLDivElement | null>];
-    "event:image.elementLoaded": [];
-    "event:image.flush": [];
-    "event:image.flushComponent": [];
     "event:displayable.applyTransition": [ITransition];
     "event:displayable.applyTransform": [Transform];
     "event:displayable.init": [];
+    "event:wearable.create": [Image];
 };
 export declare class Image extends Actionable<ImageDataRaw, Image> implements EventfulDisplayable {
-    constructor(name: string, config: DeepPartial<ImageConfig>);
-    constructor(config: DeepPartial<ImageConfig>);
+    constructor(name: string, config: Partial<ImageConfig>);
+    constructor(config?: DeepPartial<ImageConfig>);
     /**
      * Dispose the image
      *
@@ -109,5 +104,14 @@ export declare class Image extends Actionable<ImageDataRaw, Image> implements Ev
     hide(): Proxied<Image, Chained<LogicAction.Actions>>;
     hide(transform: Transform<TransformDefinitions.ImageTransformProps>): Proxied<Image, Chained<LogicAction.Actions>>;
     hide(transform: Partial<TransformDefinitions.CommonTransformProps>): Proxied<Image, Chained<LogicAction.Actions>>;
+    /**
+     * Add a wearable to the image
+     * @param children - Wearable image or images
+     */
+    addWearable(children: Image | Image[]): this;
+    /**
+     * Bind this image to a parent image as a wearable
+     */
+    bindWearable(parent: Image): this;
     copy(): Image;
 }

package/dist/game/nlcore/elements/scene.d.ts

@@ -1,6 +1,6 @@
 import { Constructable } from "../action/constructable";
 import { Awaitable } from "../../../util/data";
-import { Background, EventfulDisplayable, ImageColor, ImageSrc } from "../types";
+import { color, EventfulDisplayable, ImageColor, ImageSrc, StaticImageData } from "../types";
 import { LogicAction } from "../action/logicAction";
 import { Transform } from "../elements/transform/transform";
 import { IImageTransition, ITransition } from "../elements/transition/type";
@@ -38,7 +38,7 @@ type ChainedScene = Proxied<Scene, Chained<LogicAction.Actions>>;
 export type SceneDataRaw = {
     state: {
         backgroundMusic?: SoundDataRaw | null;
-        background?: Background["background"];
+        background?: color | StaticImageData | null;
     };
     backgroundImageState?: ImageDataRaw | null;
 };

package/dist/game/nlcore/gameTypes.d.ts

@@ -22,6 +22,9 @@ export interface SavedGame {
 }
 export type GameConfig = {
     player: {
+        /**
+         * The id of the container element for the game
+         */
         contentContainerId: string;
         /**
          * The aspect ratio of the game
@@ -38,10 +41,14 @@ export type GameConfig = {
         minHeight: number;
         /**
          * Base width of the player in pixels, Image scale will be calculated based on this value
+         *
+         * For 16/9, recommended value is 1920
          */
         width: number;
         /**
          * Base height of the player in pixels, Image scale will be calculated based on this value
+         *
+         * For 16/9, recommended value is 1080
          */
         height: number;
         /**
@@ -89,25 +96,47 @@ export type GameConfig = {
              */
             slowLoadWarning: boolean;
             slowLoadThreshold: number;
+            /**
+             * If true, when you press [GameConfig.player.skipKey], the game will skip the image transform
+             */
             allowSkipTransform: boolean;
+            /**
+             * If true, when you press [GameConfig.player.skipKey], the game will skip the image transition
+             */
             allowSkipTransition: boolean;
         };
         menu: {
             use: MenuComponent;
         };
         background: {
+            /**
+             * If true, when you press [GameConfig.player.skipKey], the game will skip the background transform
+             */
             allowSkipTransform: boolean;
+            /**
+             * If true, when you press [GameConfig.player.skipKey], the game will skip the background transition
+             */
             allowSkipTransition: boolean;
         };
         text: {
+            /**
+             * If true, when you press [GameConfig.player.skipKey], the game will skip the text transform
+             */
             allowSkipTransform: boolean;
+            /**
+             * If true, when you press [GameConfig.player.skipKey], the game will skip the text transition
+             */
             allowSkipTransition: boolean;
             /**
              * Base width of the dialog in pixels
+             *
+             * For 16/9, recommended value is 1920
              */
             width: number;
             /**
              * Base height of the dialog in pixels
+             *
+             * For 16/9, recommended value is 1080 * 0.2
              */
             height: number;
         };
@@ -157,6 +186,9 @@ export type GameConfig = {
             debug: boolean;
             trace: boolean;
         };
+        /**
+         * If true, the game will show the inspector when you hover over the element
+         */
         inspector: boolean;
     };
 };

package/dist/game/player/elements/player/SizeUpdateAnnouncer.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+export default function SizeUpdateAnnouncer({ containerRef }: Readonly<{
+    containerRef: React.RefObject<HTMLDivElement>;
+}>): null;

package/dist/game/player/gameState.d.ts

@@ -16,7 +16,6 @@ import { Text, TextEventTypes } from "../nlcore/elements/text";
 type PlayerStateElement = {
     texts: Clickable<TextElement>[];
     menus: Clickable<MenuElement, Choice>[];
-    images: Image[];
     displayable: LogicAction.Displayable[];
 };
 export type PlayerState = {
@@ -31,7 +30,7 @@ export type PlayerStateData = {
     scenes: {
         sceneId: string;
         elements: {
-            images: string[];
+            displayable: string[];
         };
     }[];
 };
@@ -65,10 +64,6 @@ export declare class GameState {
         scene: Scene;
         ele: PlayerStateElement;
     } | null;
-    findElementByImage(image: Image): {
-        scene: Scene;
-        ele: PlayerStateElement;
-    } | null;
     findElementByDisplayable(displayable: LogicAction.Displayable): {
         scene: Scene;
         ele: PlayerStateElement;
@@ -87,6 +82,7 @@ export declare class GameState {
     createText(id: string, sentence: Sentence, afterClick?: () => void, scene?: Scene): void;
     createMenu(menu: MenuData, afterChoose?: (choice: Choice) => void, scene?: Scene): void;
     createImage(image: Image, scene?: Scene): this;
+    createWearable(parent: Image, image: Image): Promise<any>;
     disposeImage(image: Image, scene?: Scene): this;
     createDisplayable(displayable: LogicAction.Displayable, scene?: Scene): this;
     disposeDisplayable(displayable: LogicAction.Displayable, scene?: Scene): this;

package/dist/game/player/lib/ErrorBoundary.d.ts

@@ -23,6 +23,6 @@ export declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, E
         errorInfo: null;
     };
     componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
-    render(): string | number | boolean | React.JSX.Element | Iterable<React.ReactNode> | null | undefined;
+    render(): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
 }
 export {};

package/dist/game/player/provider/ratio.d.ts

@@ -12,6 +12,7 @@ type AspectRatioEvents = {
     "event:aspectRatio.update": [width: number, height: number];
     "event:aspectRatio.pause": [];
     "event:aspectRatio.resume": [];
+    "event:aspectRatio.requestUpdate": [];
 };
 declare class AspectRatio {
     static EventTypes: {
@@ -37,6 +38,8 @@ declare class AspectRatio {
     pause(): void;
     resume(): void;
     onUpdate(callback: (width: number, height: number) => void): () => void;
+    requestUpdate(): void;
+    onRequestedUpdate(callback: () => void): () => void;
     private triggerUpdate;
 }
 export declare function RatioProvider({ children }: {