Merge pull request #79 from NarraLeaf/dev_nomen

narraleaf-react-0.5.0

Author: helloyork

CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.5.0]
+
+### _Incompatible Changes_
+
+- `game.config.cps` is deprecated, use `GamePreference.cps` instead
+- Menu GameElementHistory.`selected` may be null
+
+### _Feature_
+
+- New image transition: `Darkness`
+- Added method image.`darken`
+- Added method layer.`setZIndex`
+- Added `voiceVolume`, `bgmVolume`, `soundVolume`, and `globalVolume` to the game preferences
+- Using raw text for narrator instead of using Character instance
+- Added `waitForRouterExit` to wait for the page exit animation to complete
+
+### Update
+
+- The skip action will now listen to the window events instead of the player element by default
+- Added `isNarrator` to the dialog state
+
+### Fixed
+
+- Background music is not playing
+- Visual errors after applying transitions and before the elements are painted
+- Transform state is not updated correctly when the transform is skipped
+- Abort Events are not propagated correctly
+- Incorrect behavior of `router.back`
+- The game state is not flushed correctly
+- Different behavior between autoForward and user clicking
+- Incorrect transform repeat behavior
+- Unexpected NaN when converting align to percentage
+
 ## [0.4.4] - 2025/5/9
 
 ### Fixed

README.md

@@ -1,7 +1,7 @@
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-transparent.png">
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
-  <img alt="Fallback image description" src="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
+  <img alt="NarraLeaf Logo" src="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
 </picture>
 
 <h1 align="center">NarraLeaf-React</h1>
@@ -31,49 +31,36 @@ NarraLeaf-React uses TypeScript for all scripting, so you don't have to learn a
 It also has a highly abstracted and easy-to-use API, for example:
 
 ```typescript
-import {Character, Menu, Scene, Word, c, b} from "narraleaf-react";
+import {Character, Menu, Scene, c, b} from "narraleaf-react";
 ```
 
 ```typescript
-const scene1 = new Scene("scene1_hello_world", {
-  background: "/background/scene1_hello_world.jpg",
+const scene1 = new Scene("Scene1: Hello World", {
+  background: "/link/to/background.jpg",
 });
 
-const johnSmith = new Character("John Smith");
-const johnDoe = new Character("John Doe");
+const jS = new Character("John Smith");
+const jD = new Character("John Doe");
 
 scene1.action([
-  /**
-   * John Smith: Hello, world!
-   * John Smith: This is my first **NarraLeaf** story.
-   * John Smith: Start editing src/story.js and enjoy the journey!
-   */
-  johnSmith
-    .say("Hello, world!")
-    .say`This is my first ${b("NarraLeaf")} story.`
-    .say`Start editing ${c("src/story.js", "#00f")} and enjoy the journey!`,
-
-  /**
-   * John Doe: Also, don't forget to check out the documentation!
-   */
-  johnDoe.say("Also, don't forget to check out the documentation!"),
-    
-  /**
-   * Menu: Start the journey
-   *   > Yes I will!
-   *     - John Smith: Great! Let's start the journey!
-   *     - John Smith: You can open issues on GitHub if you have any questions.
-   *   > No, I'm going to check the documentation
-   *     - John Smith: Sure! Take your time!
-   */
+  jS`Hello, world!`,
+  jS`This is my first ${b("NarraLeaf")} story.`,
+  jS`Start editing ${c("src/story.js", "#00f")} and enjoy the journey!`,
+
+  jD`Also, don't forget to check out the ${c("documentation", "#00f")}!`,
+
+  "By the way, the documentation is available on https://react.narraleaf.com/documentation",
+  "You can also visit the website for demo and more information.",
+
   Menu.prompt("Start the journey")
+
     .choose("Yes I will!", [
-      johnSmith
-        .say("Great! Let's start the journey!")
-        .say("You can open issues on GitHub if you have any questions.")
+      jS`Great! Let's start the journey!`,
+      jS`You can open issues on GitHub if you have any questions.`
     ])
+
     .choose("No, I'm going to check the documentation", [
-      johnSmith.say("Sure! Take your time!")
+      jS`Sure! Take your time!`
     ])
 ]);
 ```
@@ -133,6 +120,17 @@ npm install narraleaf-react
   - [Plugin](https://react.narraleaf.com/documentation/core/plugin)
   - [Utils](https://react.narraleaf.com/documentation/core/utils)
 - [Player](https://react.narraleaf.com/documentation/player)
+  - [Player](https://react.narraleaf.com/documentation/player/player)
+  - [GameProviders](https://react.narraleaf.com/documentation/player/game-providers)
+  - Hooks
+    - [useGame](https://react.narraleaf.com/documentation/player/hooks/useGame)
+    - [usePreferences](https://react.narraleaf.com/documentation/player/hooks/usePreferences)
+    - [useRouter](https://react.narraleaf.com/documentation/player/hooks/useRouter)
+    - [useDialog](https://react.narraleaf.com/documentation/player/hooks/useDialog)
+  - [Page Router](https://react.narraleaf.com/documentation/player/page-router)
+  - [Dialog](https://react.narraleaf.com/documentation/player/dialog)
+  - [Notification](https://react.narraleaf.com/documentation/player/notification)
+  - [Menu](https://react.narraleaf.com/documentation/player/menu)
 - About
   - [License](https://react.narraleaf.com/documentation/info/license)
   - [Incompatible Changes](https://react.narraleaf.com/documentation/info/incompatible-changes)

docs/README.zh-CN.md

@@ -1,7 +1,7 @@
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-transparent.png">
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
-  <img alt="Fallback image description" src="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
+  <img alt="NarraLeaf Logo" src="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
 </picture>
 
 <h1 align="center">NarraLeaf-React</h1>
@@ -35,46 +35,33 @@ import {Character, Menu, Scene, Word, c, b} from "narraleaf-react";
 ```
 
 ```typescript
-const scene1 = new Scene("场景1_你好_世界", {
-    background: "/background/scene1_hello_world.jpg",
+const scene1 = new Scene("场景1: 你好，世界", {
+  background: "/link/to/background.jpg",
 });
 
-const johnSmith = new Character("约翰·史密斯");
-const johnDoe = new Character("约翰·多");
+const jS = new Character("John Smith");
+const jD = new Character("John Doe");
 
 scene1.action([
-    /**
-     * 约翰·史密斯: 你好世界！
-     * 约翰·史密斯: 这是我的第一个 **NarraLeaf** 视觉小说
-     * 约翰·史密斯: 开始编辑 src/story.js 并享受旅程！
-     */
-    johnSmith
-        .say("你好世界！")
-        .say`这是我的第一个 ${b("NarraLeaf")} 视觉小说`
-        .say`开始编辑 ${c("src/story.js", "#00f")} 并享受旅程！`,
-
-    /**
-     * 约翰·多: 对了，别忘了查看文档！
-     */
-    johnDoe.say("对了，别忘了查看文档！"),
-
-    /**
-     * Menu: 开始旅程
-     *   > 是的，我会！
-     *     - 约翰·史密斯: 太好了！让我们开始旅程！
-     *     - 约翰·史密斯: 如果您有任何问题，可以在GitHub上提出问题。
-     *   > 不，我要查看文档
-     *     - 约翰·史密斯: 当然！慢慢来！
-     */
-    Menu.promp("开始旅程")
-        .choose("是的，我会！", [
-            johnSmith
-                .say("太好了！让我们开始旅程！")
-                .say("如果您有任何问题，可以在GitHub上提出问题。")
-        ])
-        .choose("不，我要查看文档", [
-            johnSmith.say("当然！慢慢来！")
-        ])
+  jS`你好，世界！`,
+  jS`这是我的第一个 ${b("NarraLeaf")} 故事。`,
+  jS`开始编辑 ${c("src/story.js", "#00f")} 并享受旅程！`,
+
+  jD`别忘了检查 ${c("文档", "#00f")}!`,
+
+  "顺便说一句，文档在 https://react.narraleaf.com/documentation",
+  "你也可以访问网站获取更多信息。",
+
+  Menu.prompt("开始旅程")
+
+    .choose("是的，我愿意！", [
+      jS`太好了！让我们开始旅程！`,
+      jS`如果你有任何问题，可以在 GitHub 上提出问题。`
+    ])
+
+    .choose("不，我要检查文档", [
+      jS`好的，请慢慢来！`
+    ])
 ]);
 ```
 
@@ -124,7 +111,7 @@ npm install narraleaf-react
         - [文本](https://react.narraleaf.com/documentation/core/elements/text)
         - [持久化](https://react.narraleaf.com/documentation/core/elements/persistent)
         - [故事](https://react.narraleaf.com/documentation/core/elements/story)
-        - [Displayable](https://react.narraleaf.com/documentation/core/elements/displayable)
+        - [可视化组件](https://react.narraleaf.com/documentation/core/elements/displayable)
         - [图层](https://react.narraleaf.com/documentation/core/elements/layer)
         - [服务](https://react.narraleaf.com/documentation/core/elements/service)
         - [视频](https://react.narraleaf.com/documentation/core/elements/video)
@@ -133,6 +120,17 @@ npm install narraleaf-react
     - [插件](https://react.narraleaf.com/documentation/core/plugin)
     - [实用工具](https://react.narraleaf.com/documentation/core/utils)
 - [播放器](https://react.narraleaf.com/documentation/player)
+    - [Player](https://react.narraleaf.com/documentation/player/player)
+    - [GameProviders](https://react.narraleaf.com/documentation/player/game-providers)
+    - 钩子
+        - [useGame](https://react.narraleaf.com/documentation/player/hooks/useGame)
+        - [usePreferences](https://react.narraleaf.com/documentation/player/hooks/usePreferences)
+        - [useRouter](https://react.narraleaf.com/documentation/player/hooks/useRouter)
+        - [useDialog](https://react.narraleaf.com/documentation/player/hooks/useDialog)
+    - [页面路由](https://react.narraleaf.com/documentation/player/page-router)
+    - [对话框](https://react.narraleaf.com/documentation/player/dialog)
+    - [通知](https://react.narraleaf.com/documentation/player/notification)
+    - [选项框](https://react.narraleaf.com/documentation/player/menu)
 - 关于
     - [许可](https://react.narraleaf.com/documentation/info/license)
     - [不兼容的更改](https://react.narraleaf.com/documentation/info/incompatible-changes)

src/game/nlcore/action/actionHistory.ts

@@ -3,6 +3,7 @@ import { Action } from "./action";
 import { randId } from "@lib/util/data";
 import { LiveGameEventToken } from "../types";
 import { LogicAction } from "../game";
+import { GameHistory, GameHistoryManager } from "./gameHistory";
 
 export type ActionHistory<T extends Array<unknown> = any> = {
     action: Action;
@@ -32,7 +33,7 @@ export class ActionHistoryManager {
      */
     public push<T extends Array<any> = Array<any>>(action: Action, onUndo?: (...args: T) => void, args?: T, timeline?: Timeline): {id: string} {
         const id = randId(6);
-        this.history.push({action, id, args, undo: onUndo, timeline});
+        this.history.push({action, id, args: args || [], undo: onUndo, timeline});
 
         // Check if the history size exceeds the limit
         if (this.history.length > this.maxHistorySize) {
@@ -63,31 +64,42 @@ export class ActionHistoryManager {
 
         const affected: ActionHistory<any>[] = [];
         for (let i = this.history.length - 1; i >= index; i--) {
-            if (this.history[i].timeline && !this.history[i].timeline!.isSettled) {
+            if (this.history[i].timeline && !this.history[i].timeline!.isSettled()) {
                 this.history[i].timeline!.abort();
             }
+            console.log("NarraLeaf-React [ActionHistory] Undoing", this.history[i].action.type, this.history[i]);
             this.history[i].undo?.(...(this.history[i].args || []));
             affected.push(this.history[i]);
         }
 
-        this.history.splice(index);
+        this.history.length = index;
         this.hooks.onUndo.forEach(cb => cb(affected));
         return (affected[affected.length - 1]?.action || null) as LogicAction.Actions | null;
     }
 
-    public undo(): LogicAction.Actions | null {
-        const last = this.history.pop();
-        if (last) {
-            if (last.timeline && !last.timeline.isSettled) {
-                last.timeline.abort();
+    public undo(gameHistory: GameHistoryManager): LogicAction.Actions | null {
+        if (!this.ableToUndo(gameHistory)) {
+            return null;
+        }
+
+        const history = gameHistory.getHistory();
+        let last: GameHistory | undefined;
+        for (let i = history.length - 1; i >= 0; i--) {
+            if (history[i].isPending !== true) {
+                last = history[i];
+                break;
             }
-            last.undo?.(...last.args);
-            this.hooks.onUndo.forEach(cb => cb([last]));
-            return last.action as LogicAction.Actions;
+        }
+        if (last) {
+            return this.undoUntil(last.token);
         }
         return null;
     }
 
+    public ableToUndo(gameHistory: GameHistoryManager): boolean {
+        return this.history.length > 0 && gameHistory.getHistory().some((h: GameHistory) => h.isPending !== true);
+    }
+
     public onUndo(callback: (affected: ActionHistory<any>[]) => void): LiveGameEventToken {
         this.hooks.onUndo.push(callback);
         return {

src/game/nlcore/action/actionTypes.ts

@@ -79,13 +79,15 @@ export const ImageActionTypes = {
     flush: "image:flush",
     initWearable: "image:initWearable",
     setAppearance: "image:setAppearance",
+    setDarkness: "image:setDarkness",
 } as const;
 export type ImageActionContentType = {
     [K in typeof ImageActionTypes[keyof typeof ImageActionTypes]]:
     K extends "image:setSrc" ? [ImageSrc | Color] :
     K extends "image:flush" ? [] :
     K extends "image:initWearable" ? [Image] :
     K extends "image:setAppearance" ? [FlexibleTuple<SelectElementFromEach<TagGroupDefinition>> | string[], ImageTransition | undefined] :
+    K extends "image:setDarkness" ? [darkness: number, duration?: number, easing?: TransformDefinitions.EasingDefinition] :
     any;
 } & DisplayableActionContentType<ImageTransition>;
 /* Condition */
@@ -187,10 +189,12 @@ export type PersistentActionContentType = {
 /* Layer */
 export const LayerActionTypes = {
     action: "layer:action",
+    setZIndex: "layer:setZIndex",
 } as const;
 export type LayerActionContentType = {
     [K in typeof LayerActionTypes[keyof typeof LayerActionTypes]]:
     K extends "layer:action" ? any :
+    K extends "layer:setZIndex" ? [number] :
     any;
 }
 /* Video */

src/game/nlcore/action/actions/characterAction.ts

@@ -48,12 +48,15 @@ export class CharacterAction<T extends typeof CharacterActionTypes[keyof typeof
             }
 
             // Create dialog
-            const dialog = gameState.createDialog(this.getId(), sentence, () => {
+            const dialogId = gameState.idManager.generateId();
+            const dialog = gameState.createDialog(dialogId, sentence, () => {
                 if (voice) {
                     const task = gameState.audioManager.stop(voice);
                     timeline.attachChild(task);
                 }
 
+                gameState.gameHistory.resolvePending(id); // accessing id is technically dangerous, but I think it is impossible to happen
+
                 awaitable.resolve({
                     type: this.type,
                     node: this.contentNode.getChild()
@@ -69,6 +72,7 @@ export class CharacterAction<T extends typeof CharacterActionTypes[keyof typeof
                     const task = gameState.audioManager.stop(voice);
                     timeline.attachChild(task);
                 }
+                dialog.cancel();
             });
             gameState.gameHistory.push({
                 token: id,
@@ -77,7 +81,9 @@ export class CharacterAction<T extends typeof CharacterActionTypes[keyof typeof
                     type: "say",
                     text: dialog.text,
                     voice: voice ? voice.getSrc() : null,
-                }
+                    character: this.callee.state.name,
+                },
+                isPending: true,
             });
 
             return awaitable;