@lute-lang/player-web 0.40.0 → 0.41.1

package/README.md

@@ -1,12 +1,12 @@
 # @lute-lang/player-web
 
-The Lute 0.40 browser visual-novel player. It supplies PixiJS 8 rendering, Web Audio, screens, and keyboard/mouse/touch/gamepad input for the renderer-free `@lute-lang/player` core.
+The Lute 0.41 browser visual-novel player. It supplies PixiJS 8 rendering, Web Audio, screens, and keyboard/mouse/touch/gamepad input for the renderer-free `@lute-lang/player` core.
 
 ## Install
 
 ```sh
-bun add @lute-lang/player-web@0.40.0 @lute-lang/player@0.40.0 @lute-lang/runtime@0.40.0 effect@4.0.2 @effect/platform-browser@4.0.2 pixi.js@8.22.0 @pixi/sound@6.0.1
-# npm install @lute-lang/player-web@0.40.0 @lute-lang/player@0.40.0 @lute-lang/runtime@0.40.0 effect@4.0.2 @effect/platform-browser@4.0.2 pixi.js@8.22.0 @pixi/sound@6.0.1
+bun add @lute-lang/player-web@0.41.1 @lute-lang/player@0.41.1 @lute-lang/runtime@0.41.1 effect@4.0.2 @effect/platform-browser@4.0.2 pixi.js@8.22.0 @pixi/sound@6.0.1
+# npm install @lute-lang/player-web@0.41.1 @lute-lang/player@0.41.1 @lute-lang/runtime@0.41.1 effect@4.0.2 @effect/platform-browser@4.0.2 pixi.js@8.22.0 @pixi/sound@6.0.1
 ```
 
 The package requires exact `effect@4.0.2` and `@effect/platform-browser@4.0.2` peers. Runtime and player packages are released in lockstep.
@@ -32,7 +32,13 @@ const view = await player.view()
 await player.unmount()
 ```
 
-`bindings` accepts a decoded `Bindings` object, YAML text, or `{ url }`. `assetsUrl` overrides the file's `assetsBase`; `host` supplies custom bridge/idle behavior. `mountPlayer` returns Promise methods `act`, `view`, and `unmount`. The Effect-native `LuteWeb.mount` is available when the application already manages an Effect scope.
+`bindings` accepts a decoded `Bindings` object, YAML text, or `{ url }`. `assetsUrl` overrides the file's `assetsBase`; `host` is the core's `PlayerHost`: `bridge` handlers return a `BridgeAnswer` (`{ fields, writes? }`), `plugin` handlers run as waiting cues, and `idle` answers idle waits. `mountPlayer` returns Promise methods `act`, `view`, and `unmount`. The Effect-native `LuteWeb.mount` is available when the application already manages an Effect scope; its handle is the core's `LutePlayerHandle` (`actions`, `view`, `send`, `restore`, `shutdown`, plus the runtime `session` and its `program`).
+
+## Cue handling
+
+- **Names.** The dialogue name plate and backlog rows show `speakerName`, the cast display name from the bundle index (`cast: { id: name }`); name colours stay keyed by the speaker id.
+- **Music.** `PixiAudio` honours `AudioPlay.restart`: `restart: true` plays the file from its start; without it, the music file already playing only changes volume, fading over `fade`, and a different file crossfades.
+- **Custom vfx.** A `StageCue.Vfx` whose `effect.effect` is `"custom"` (a project vfx bound as `{ effect: custom }`, or a vfx type with no binding) has no Pixi effect: the presenter plays nothing and logs `effect.name` once at debug level (`PresenterOptions.debug`, default `console.debug`). Render project effects with your own `Presenter`.
 
 ## API and guides
 

package/dist/audio/pixiAudio.d.ts

@@ -43,7 +43,11 @@ export declare class PixiAudio implements AudioPort {
     private currentVolumes;
     private readonly gate;
     constructor(options: PixiAudioOptions);
-    /** Play a channel sound, waiting for finite sounds to end. */
+    /**
+     * Play a channel sound, waiting for finite sounds to end. Music without
+     * `restart` whose file is the one already playing only changes its volume,
+     * fading over `fade`, without restarting it (spec 0.41.0 §7.7).
+     */
     readonly play: (channel: AudioChannel, soundToPlay: AudioPlay) => Effect.Effect<void>;
     /** Fade and stop every playback currently in a channel. */
     readonly stop: (channel: AudioChannel, fade: number) => Effect.Effect<void>;
@@ -52,7 +56,19 @@ export declare class PixiAudio implements AudioPort {
     private effectiveVolume;
     private removeRecord;
     private readonly interruptFade;
+    private applyVolume;
+    /** Fade `record`'s live factor to `to` over `duration` seconds, starting from wherever it is now. */
     private readonly startFade;
+    /**
+     * Step `record` through `advance(progress)` over `duration` seconds on a
+     * detached fiber, applying its volume after each step.
+     */
+    private readonly ramp;
+    /**
+     * Move a playing record to a new input volume, fading over `fade` seconds
+     * from its current level (finishing an interrupted fade-in); it keeps playing.
+     */
+    private readonly changeVolume;
     private readonly fadeOutAndStop;
     private readonly stopVoiceImmediately;
     private readonly replaceMusic;

package/dist/effects/catalogue.d.ts

@@ -1,7 +1,10 @@
 import { Effect, Schema } from "effect";
 import { Container } from "pixi.js";
 import type { Behaviour } from "../engine/types.js";
-/** Names accepted by the 0.40 player effect catalogue. */
+/**
+ * Names in the player effect catalogue. `custom` (a project vfx, spec 0.41.0
+ * §7.7) is not one: the presenter handles it before reaching the catalogue.
+ */
 export type EffectName = "fade" | "dissolve" | "wipeLeft" | "wipeRight" | "wipeUp" | "wipeDown" | "slideLeft" | "slideRight" | "cut" | "fadeIn" | "fadeOut" | "slideIn" | "slideOut" | "hop" | "shake" | "none" | "zoom" | "pan" | "flash" | "blur" | "tint";
 /** Values accepted in a binding effect parameter object. */
 export type EffectParams = Readonly<Record<string, number | string | boolean>>;

package/dist/index.js

@@ -1328,6 +1328,13 @@ class PixiAudio {
     if (!SubscriptionRef2.getUnsafe(self.unlocked)) {
       yield* Deferred2.await(self.gate);
     }
+    if (channel === "music" && !soundToPlay.restart) {
+      const playing = self.active.music.filter((record2) => !record2.stopping).at(-1);
+      if (playing !== undefined && playing.file === soundToPlay.file) {
+        yield* self.changeVolume(playing, clamp2(soundToPlay.volume), soundToPlay.fade);
+        return;
+      }
+    }
     const loaded = yield* self.backend.load(soundToPlay.file).pipe(Effect6.catch((error) => {
       self.logger(`Audio file missing or undecodable: ${soundToPlay.file}`, error);
       return Effect6.fail(error);
@@ -1350,14 +1357,17 @@ class PixiAudio {
       yield* self.replaceMusic(soundToPlay.fade);
     const record = {
       channel,
+      file: soundToPlay.file,
       inputVolume,
+      factor: positive(soundToPlay.fade) > 0 ? 0 : 1,
       playback: playback.value,
-      fade: undefined
+      fade: undefined,
+      stopping: false
     };
     self.active[channel].push(record);
-    record.playback.setVolume(soundToPlay.fade > 0 ? 0 : self.effectiveVolume(channel, inputVolume));
+    self.applyVolume(record);
     if (positive(soundToPlay.fade) > 0) {
-      record.fade = yield* self.startFade(record, 0, 1, soundToPlay.fade, false);
+      record.fade = yield* self.startFade(record, 1, soundToPlay.fade, false);
     }
     if (!soundToPlay.loop) {
       yield* record.playback.ended;
@@ -1369,8 +1379,10 @@ class PixiAudio {
     const records = self.active[channel].slice();
     if (records.length === 0)
       return;
-    for (const record of records)
+    for (const record of records) {
+      record.stopping = true;
       yield* self.interruptFade(record);
+    }
     const duration = positive(fade);
     if (duration === 0) {
       for (const record of records) {
@@ -1389,9 +1401,8 @@ class PixiAudio {
       voice: clamp2(volumes.voice)
     };
     for (const channel of ["music", "sfx", "voice"]) {
-      for (const record of this.active[channel]) {
-        record.playback.setVolume(this.effectiveVolume(channel, record.inputVolume));
-      }
+      for (const record of this.active[channel])
+        this.applyVolume(record);
     }
   });
   effectiveVolume(channel, inputVolume) {
@@ -1406,22 +1417,49 @@ class PixiAudio {
   interruptFade = (record) => record.fade === undefined ? Effect6.void : Fiber2.interrupt(record.fade).pipe(Effect6.asVoid, Effect6.tap(() => Effect6.sync(() => {
     record.fade = undefined;
   })));
-  startFade = (record, from, to, duration, stopAtEnd) => {
+  applyVolume(record) {
+    record.playback.setVolume(this.effectiveVolume(record.channel, record.inputVolume) * record.factor);
+  }
+  startFade = (record, to, duration, stopAtEnd) => {
+    const from = record.factor;
+    return this.ramp(record, duration, (progress) => {
+      record.factor = from + (to - from) * progress;
+    }, stopAtEnd);
+  };
+  ramp = (record, duration, advance, stopAtEnd) => {
     const steps = Math.max(1, Math.ceil(duration * 20));
     const interval = duration / steps;
     const fade = Effect6.forEach(Array.from({ length: steps }, (_, index) => index + 1), (step) => Effect6.sleep(interval).pipe(Effect6.flatMap(() => Effect6.sync(() => {
-      const factor = from + (to - from) * (step / steps);
-      record.playback.setVolume(this.effectiveVolume(record.channel, record.inputVolume) * factor);
+      advance(step / steps);
+      this.applyVolume(record);
     }))), { discard: true }).pipe(Effect6.flatMap(() => Effect6.sync(() => {
-      record.playback.setVolume(this.effectiveVolume(record.channel, record.inputVolume) * to);
+      advance(1);
+      this.applyVolume(record);
       if (stopAtEnd)
         record.playback.stop();
     })));
     return Effect6.forkDetach(fade);
   };
+  changeVolume = (record, inputVolume, fade) => Effect6.gen({ self: this }, function* () {
+    const self = this;
+    yield* self.interruptFade(record);
+    const duration = positive(fade);
+    if (duration === 0) {
+      record.inputVolume = inputVolume;
+      record.factor = 1;
+      self.applyVolume(record);
+      return;
+    }
+    const fromVolume = record.inputVolume;
+    const fromFactor = record.factor;
+    record.fade = yield* self.ramp(record, duration, (progress) => {
+      record.inputVolume = fromVolume + (inputVolume - fromVolume) * progress;
+      record.factor = fromFactor + (1 - fromFactor) * progress;
+    }, false);
+  });
   fadeOutAndStop = (record, duration) => Effect6.gen({ self: this }, function* () {
     const self = this;
-    const fiber = yield* self.startFade(record, 1, 0, duration, true);
+    const fiber = yield* self.startFade(record, 0, duration, true);
     yield* Fiber2.join(fiber);
     self.removeRecord(record);
   });
@@ -1438,12 +1476,13 @@ class PixiAudio {
     const self = this;
     const old = self.active.music.slice();
     for (const record of old) {
+      record.stopping = true;
       yield* self.interruptFade(record);
       if (positive(fade) === 0) {
         record.playback.stop();
         self.removeRecord(record);
       } else {
-        const fiber = yield* self.startFade(record, 1, 0, fade, true);
+        const fiber = yield* self.startFade(record, 0, fade, true);
         record.fade = fiber;
         yield* Effect6.forkDetach(Fiber2.join(fiber).pipe(Effect6.flatMap(() => Effect6.sync(() => self.removeRecord(record)))));
       }
@@ -2875,6 +2914,7 @@ class PixiPresenter {
   bindings;
   theme;
   logger;
+  debug;
   actors = new Map;
   background;
   cg;
@@ -2885,6 +2925,7 @@ class PixiPresenter {
   choice;
   choiceActions;
   missing = new Set;
+  customVfx = new Set;
   uiHidden = false;
   constructor(options) {
     this.pixi = options.pixi;
@@ -2894,6 +2935,7 @@ class PixiPresenter {
     this.bindings = options.bindings;
     this.theme = options.theme;
     this.logger = options.logger ?? ((message, error) => console.warn(message, error));
+    this.debug = options.debug ?? ((message) => console.debug(message));
     const design = this.pixi.design;
     this.background = new Background(this.pixi.layers.background, this.world, this.bindings, this.assets, design, this.theme, (message) => this.logMissing(message));
     this.cg = new CgLayer(this.pixi.layers.cg, this.world, this.bindings, this.assets, design, this.theme, (message) => this.logMissing(message));
@@ -2971,7 +3013,7 @@ class PixiPresenter {
         return Effect17.sync(() => this.camera.apply(cue.framing, cue.focus)).pipe(Effect17.flatMap(() => this.camera.move(cue.move ?? cue.transition, cue.duration, instant)));
       }
       case "Vfx":
-        return this.vfx.play(cue.effect, cue.duration, instant);
+        return cue.effect.effect === "custom" ? this.logCustomVfx(cue.effect.name ?? "") : this.vfx.play(cue.effect, cue.duration, instant);
     }
   };
   upsertActor = (actor, action, instant, duration) => {
@@ -3008,6 +3050,12 @@ class PixiPresenter {
     this.missing.add(message);
     this.logger(message);
   };
+  logCustomVfx = (name) => Effect17.sync(() => {
+    if (this.customVfx.has(name))
+      return;
+    this.customVfx.add(name);
+    this.debug(`Custom vfx "${name}" has no Pixi effect; nothing is played`);
+  });
 }
 
 // src/input/map.ts
@@ -3319,7 +3367,7 @@ var runMount = (element, options, bindings, assetsBase) => {
     })));
     if (title !== undefined && title !== null) {
       const file = resolveAsset(bindings, assetsBase, title.music);
-      yield* Effect19.forkScoped(audio.play("music", { file, loop: true, volume: 1, fade: 0 }).pipe(Effect19.catch(() => Effect19.void)));
+      yield* Effect19.forkScoped(audio.play("music", { file, loop: true, volume: 1, fade: 0, restart: true }).pipe(Effect19.catch(() => Effect19.void)));
     }
     return player;
   });

package/dist/presenter/pixiPresenter.d.ts

@@ -16,6 +16,8 @@ export interface PresenterOptions {
     readonly theme: Theme;
     readonly titleBackground?: string;
     readonly logger?: (message: string, error?: unknown) => void;
+    /** Debug-level log; defaults to `console.debug`. Receives one line per custom vfx name. */
+    readonly debug?: (message: string) => void;
 }
 /** Pixi implementation of the renderer-free player Presenter port. */
 /** Presenter service key. */
@@ -43,6 +45,7 @@ export declare class PixiPresenter implements Presenter {
     private readonly bindings;
     private readonly theme;
     private readonly logger;
+    private readonly debug;
     private readonly actors;
     private readonly background;
     private readonly cg;
@@ -53,6 +56,7 @@ export declare class PixiPresenter implements Presenter {
     private readonly choice;
     private readonly choiceActions;
     private readonly missing;
+    private readonly customVfx;
     private uiHidden;
     constructor(options: PresenterOptions);
     private defaultSettings;
@@ -62,5 +66,10 @@ export declare class PixiPresenter implements Presenter {
     private readonly restoreStage;
     private readonly showChoiceInternal;
     private readonly logMissing;
+    /**
+     * A custom vfx (spec 0.41.0 §7.7) has no catalogue effect here: the Pixi
+     * presenter plays nothing and logs each name once at debug level.
+     */
+    private readonly logCustomVfx;
 }
 export declare const presenterLayer: (bindings: Bindings, theme: Theme, assets: TextureAssets) => Layer.Layer<PixiPresenter, never, PixiApp | UiShape | World>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lute-lang/player-web",
-  "version": "0.40.0",
+  "version": "0.41.1",
   "description": "The Lute web visual-novel player: PixiJS 8 renderer, Web Audio, screens and input over @lute-lang/player.",
   "license": "MIT",
   "type": "module",
@@ -28,8 +28,8 @@
     "demo": "bun scripts/demo.ts"
   },
   "dependencies": {
-    "@lute-lang/player": "0.40.0",
-    "@lute-lang/runtime": "0.40.0",
+    "@lute-lang/player": "0.41.1",
+    "@lute-lang/runtime": "0.41.1",
     "pixi.js": "8.22.0",
     "@pixi/sound": "6.0.1"
   },