@3driseai/3drise-viewer 0.1.27 → 0.1.29

package/dist/operations/objectEffects.d.ts

@@ -1,21 +1,81 @@
 import type { Object3D } from 'three';
-import type { ObjectEffect } from '@3driseai/3drise-core';
+import type { EffectPlayback, EffectSpread, EffectStep, EffectSteps, ObjectEffect } from '@3driseai/3drise-core';
 import type { OperationDefinition, OperationParams } from './types';
-/** An operation can be an object effect. */
+/** An operation can be an object effect (one-shots too: they have no way back, and play with loop). */
 export declare const isObjectOperation: (def: OperationDefinition | undefined) => def is OperationDefinition;
 /**
  * The effects that actually run: on, known, usable on objects, one per operation,
  * and one of each stack (the first wins).
  */
 export declare function runningObjectEffects(effects: ObjectEffect[] | undefined): ObjectEffect[];
-/** An object effect's parameters: defaults, its overrides, then what object effects force. */
-export declare const objectEffectParams: (def: OperationDefinition, effect: Pick<ObjectEffect, "params">) => OperationParams;
+/** How an effect that follows visibility brings the object in and out (see the header). */
+export type EffectPresence = 'paint' | 'vanish' | 'decorate';
+export declare function effectPresence(def: OperationDefinition, effect: Pick<ObjectEffect, 'params'>, follows: boolean, inStep?: boolean): EffectPresence;
+/** An object effect's parameters: the operation's defaults, the object defaults, then its own values. */
+export declare const objectEffectParams: (def: OperationDefinition, effect: Pick<ObjectEffect, "params">, follows?: boolean, inStep?: boolean) => OperationParams;
+/** An effect's playback with the defaults filled in. */
+export declare const playbackOf: (effect: Pick<ObjectEffect, "playback">) => Required<EffectPlayback>;
+/** An object's effects controller; `create` makes one for an object that has no effects of its own yet. */
+export declare function objectEffectsControllerFor(root: Object3D, create?: boolean): ObjectEffectsController | undefined;
+/** The step of an object's effect steps that is on now (-1: none) — for the editor. */
+export declare function currentEffectStep(root: Object3D | null | undefined): number;
+/** An object's own effect clip follows its visibility (`visible`) and has an effect that is on. */
+export declare const clipFollowsVisibility: (clip: {
+    visible?: boolean;
+    effects?: ObjectEffect[];
+    steps?: EffectStep[];
+} | null | undefined) => boolean;
+/**
+ * The object was shown or hidden: its visibility effects play in, or play out.
+ * Returns a promise (null = nothing to wait for) that resolves
+ *   shown   when the effects are ready and the object is drawn (its entrance is starting)
+ *   hidden  when they have played out and the object is no longer drawn
+ * The controller sets the group's `visible` itself at those two moments.
+ */
+export declare function setObjectEffectsVisible(root: Object3D | null | undefined, visible: boolean): Promise<unknown> | null;
+/**
+ * Play one of an object's effects from its start, with its playback settings
+ * (the editor's ▶; an effect with autoplay off starts this way). False when the
+ * object or the effect is not there.
+ */
+export declare function playObjectEffect(root: Object3D | null | undefined, effectId: string): boolean;
+export declare const STEP_IN = 1;
+export declare const STEP_HOLD = 1;
+/** An effect clip as it is handed to a controller: always-on effects, steps, and how the steps repeat. No target inside. */
+export interface EffectClipData {
+    effects?: ObjectEffect[];
+    steps?: EffectStep[];
+    loop?: boolean;
+    yoyo?: boolean;
+}
 export declare class ObjectEffectsController {
     private root;
     private running;
+    /** Effects playing out (removed / switched off): their op → when they are gone. */
+    private leaving;
     private effects;
     private refreshing;
     private disposed;
+    /** The object is shown — visibility effects wait while it is not. */
+    private shown;
+    /** The object is on screen: it stays drawn while its effects play out, and is not yet drawn while they get ready. */
+    private drawn;
+    private visRun;
+    /** The object's own list (always on) and its steps; `effects` is what runs: the two laid together. */
+    private own;
+    /** Clips applied from outside (key → run), in the order they were applied. */
+    private clips;
+    /** The object's own steps wait while an applied clip has steps. */
+    private ownPaused;
+    /** Effects added by interactions / actions (key → row; disabled while it plays out). */
+    private added;
+    /** The object's own rows (Base and steps) as last composed: id → it is a step's. */
+    private ownRows;
+    /** A group: its visual effects and physical 'each' effects go to the children (see ./groupFanout.ts). */
+    private fan;
+    private spread;
+    /** Added effects that follow visibility: a group's effects on this child, when the group's follow it. */
+    private addedFollows;
     constructor(root: Object3D);
     /** The object's targets for an effect: the object, or its named nodes. */
     private targetsOf;
@@ -25,15 +85,110 @@ export declare class ObjectEffectsController {
      * Bring what runs in line with `effects`.
      *   animate  switching an effect on / off plays its transition (studio, actions)
      *   instant  everything lands in its end state at once (scene load)
-     * A changed parameter always lands at once.
+     * A changed parameter always lands at once. A row switched to another
+     * operation clears the old one at once, then plays the new one in from the
+     * original object.
+     */
+    sync(effects: ObjectEffect[] | undefined, mode: 'animate' | 'instant', steps?: EffectSteps | null, parts?: string[] | null, follows?: boolean, group?: EffectSpread | null): void;
+    /** A clip's rows: the step that is on, its always-on effects, and the steps that wait (listed, off). */
+    private rowsOf;
+    /** A row follows the object's visibility (one of its own, with `visible` on) · it is a step's. */
+    private visOf;
+    /**
+     * The running list, top first (the first of two that clash wins): added effects, applied clips
+     * (newest first; in each, the step that is on, then its always-on effects), the object's own clip,
+     * then everything that waits or is playing out.
+     */
+    private compose;
+    /**
+     * Put an effect on the object on top of its own (an interaction, an action). `key` names it for
+     * removeEffect. Already on: a one-shot plays again, anything else is left as it is.
+     */
+    addEffect(key: string, effect: Pick<ObjectEffect, 'operation' | 'params' | 'playback' | 'meshNames' | 'scope'>, opts?: {
+        instant?: boolean;
+        follows?: boolean;
+    }): boolean;
+    /** Take an added effect off: it plays out (or what is below it takes over again). */
+    removeEffect(key: string): boolean;
+    hasEffect(key: string): boolean;
+    /** The object's own steps wait while an applied clip has steps; afterwards they start again from the first. */
+    private refreshPause;
+    /**
+     * Apply a whole effect clip over the object's own (an interaction, an action). `key` names this
+     * application for removeClip; `parts` narrows it to nodes of the model. Already on: left as it is.
+     */
+    applyClip(key: string, clip: EffectClipData, parts?: string[]): boolean;
+    /** Take an applied clip off: its effects play out, and what it had taken over comes back. */
+    removeClip(key: string): boolean;
+    hasClip(key: string): boolean;
+    /**
+     * A clip's current step's clock: its hold starts when its looks have really played in (they first
+     * wait for the outgoing step, and the first time for their shaders), so a slow start never eats a step.
+     */
+    private scheduleStep;
+    private nextStep;
+    /** The step of the object's own clip that is on (-1: no steps, or they wait for an applied clip). */
+    get step(): number;
+    private syncList;
+    /** Take a row that left the list off: at once (`gone`), or with its out transition — then it is tracked until it has gone. */
+    private playOut;
+    /**
+     * A direct handover: `r` (a held take-over) stays on while `inc` plays in, and is wiped by
+     * inc's front — its field takes inc's direction / scale / sweep, its `clear` follows inc's
+     * progress every frame. When inc is fully on, r is taken off at once (nothing of it shows any more).
+     */
+    private wipe;
+    /** Whether the object is shown when the controller starts (before the first sync). */
+    setShown(shown: boolean): void;
+    /** See setObjectEffectsVisible. */
+    setVisible(visible: boolean): Promise<unknown> | null;
+    private addedRows;
+    /** The group is being hidden: this child plays the group's effects out, then is no longer drawn. */
+    fanLeave(keys: string[]): Promise<unknown>;
+    /** The group is about to be shown: this child starts from nothing (undrawn, the group's effects at their start). */
+    fanPark(keys: string[]): void;
+    /** Its turn after the group was shown: the group's effects get ready, the child is drawn, they play in. */
+    fanEnter(keys: string[]): Promise<unknown>;
+    private cancelCycle;
+    /** Take an effect off at once and leave its row waiting. */
+    private clear;
+    /** The object is shown: get every effect ready while it is still undrawn, draw it, play them in. */
+    private enterAll;
+    /** Before the object is drawn: compile the effect and put its start state on. */
+    private prepare;
+    private enter;
+    /** A paint / vanish effect's entrance on an object that is already drawn (added, switched on, ▶). */
+    private entrance;
+    /** A vanish effect plays back from gone (or from part-way); then the object is at rest, with nothing on it. */
+    private comeBack;
+    /** The object is hidden: play every effect out, then stop drawing it. */
+    /** `hide`: stop drawing the object at the end (a group hides itself after its children instead). */
+    private leaveAll;
+    private leave;
+    /** `force`: play it even with autoplay off (it was asked for). */
+    private start;
+    private done;
+    /**
+     * A periodic motion (float, sway…): on for one pass, then it settles — or on for good with Loop.
+     * Reverse runs its clock backwards; yoyo turns the clock round after each pass.
      */
-    sync(effects: ObjectEffect[] | undefined, mode: 'animate' | 'instant'): void;
+    private periodic;
+    /** Loop / yoyo / reverse, sequenced from apply (forward) and revert (backward). Reads r.params each pass. */
+    private cycle;
+    /** Play an effect out and leave it waiting (it stays in the list, ready to play again). */
+    stop(effectId: string): boolean;
+    /** Play an effect from its start (see playObjectEffect). */
+    play(effectId: string): boolean;
     /**
      * The object's meshes or materials were replaced: take every effect off the
      * old ones and put it straight back on the new ones (no transition).
      */
     refresh(): Promise<void>;
     /** Take everything off at once (the object is going away). */
+    /** A group: children joined or left (the effects hook checks every few frames). */
+    checkFanout(): void;
+    /** Ids of a group's children in cascade order (tests / studio). */
+    get fanChildren(): string[];
     dispose(): void;
     /** Ids of the effects running now (tests / studio). */
     get runningIds(): string[];

package/dist/operations/objectEffects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"objectEffects.d.ts","sourceRoot":"","sources":["../../src/operations/objectEffects.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,uBAAuB,CAAC;AAGzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEpE,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,GAAI,KAAK,mBAAmB,GAAG,SAAS,KAAG,GAAG,IAAI,mBACpB,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,SAAS,GAAG,YAAY,EAAE,CAgBxF;AAED,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,GAAI,KAAK,mBAAmB,EAAE,QAAQ,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,KAAG,eACzB,CAAC;AAY5E,qBAAa,uBAAuB;IAMpB,OAAO,CAAC,IAAI;IALxB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAS;gBAEL,IAAI,EAAE,QAAQ;IAElC,0EAA0E;IAC1E,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,EAAE;IAIV,OAAO,CAAC,GAAG;IAQX;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS;IAwBrE;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAaxB,8DAA8D;IAC9D,OAAO;IAMP,uDAAuD;IACvD,IAAI,UAAU,IAAI,MAAM,EAAE,CAAqC;CAClE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAQvD"}
+{"version":3,"file":"objectEffects.d.ts","sourceRoot":"","sources":["../../src/operations/objectEffects.ts"],"names":[],"mappings":"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"}