@thi.ng/timestep 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-04-25T15:38:18Z
+- **Last updated**: 2023-05-05T21:29:28Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,23 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/timestep@0.3.0) (2023-05-05)
+
+#### 🚀 Features
+
+- add AState.reset() & impls ([a2c4946](https://github.com/thi-ng/umbrella/commit/a2c4946))
+
+#### ♻️ Refactoring
+
+- rename IUpdatable => ITimeStep ([2cc3951](https://github.com/thi-ng/umbrella/commit/2cc3951))
+
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/timestep@0.2.0) (2023-04-28)
+
+#### 🚀 Features
+
+- add INotify support, add fixed time field ([b68c0c6](https://github.com/thi-ng/umbrella/commit/b68c0c6))
+- add integrateAll/interpolateAll() helpers ([71087cf](https://github.com/thi-ng/umbrella/commit/71087cf))
+
 ### [0.1.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/timestep@0.1.1) (2023-04-25)
 
 #### ♻️ Refactoring

package/README.md

@@ -31,8 +31,8 @@ upon which this implementation is principally based on.
 The package provides a configurable [`TimeStep`
 class](https://docs.thi.ng/umbrella/timestep/classes/TimeStep.html) to manage
 the update logic. To participate in these managed updates, the user must provide
-state values/wrappers implementing the [`IUpdatable`
-interface](https://docs.thi.ng/umbrella/timestep/interfaces/IUpdatable.html) for
+state values/wrappers implementing the [`ITimeStep`
+interface](https://docs.thi.ng/umbrella/timestep/interfaces/ITimeStep.html) for
 the two main phases of the frame update:
 
 - `integrate(dt: number, ctx: ReadonlyTimeStep): void`: Depending on actual
@@ -75,7 +75,7 @@ const b = defVector([0, 0], (x, dt) => [x[0] - 10 * dt, x[1] + 20 * dt]);
 // the simulated render frame rate here is only 25 fps...
 setInterval(() => {
     // provide current time and an array of state values to update
-    // (any IUpdatable impl can be given here, incl. custom types)
+    // (any ITimeStep impl can be given here, incl. custom types)
     sim.update(Date.now(), [a, b]);
     // show current frame, num updates, time (relative to start) and interpolated state values
     console.log(sim.frame, sim.updates, sim.current, a.value, b.value);
@@ -148,7 +148,7 @@ For Node.js REPL:
 const timestep = await import("@thi.ng/timestep");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 518 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 758 bytes
 
 ## Dependencies
 

package/api.d.ts

@@ -1,7 +1,7 @@
 /**
  * Interface for participating in the {@link TimeStep.update} logic.
  */
-export interface IUpdatable {
+export interface ITimeStep {
     /**
      * 1st phase of the update cycle and main update function for this
      * simulation state. Receives timestep (in seconds) and a `ctx` object.
@@ -36,6 +36,10 @@ export interface IUpdatable {
     interpolate(alpha: number, ctx: ReadonlyTimeStep): void;
 }
 export interface ReadonlyTimeStep {
+    /**
+     * Simulation time since start (resolution {@link ReadonlyTimeStep.dt}).
+     */
+    readonly t: number;
     /**
      * Configured timestep (in seconds)
      */
@@ -88,4 +92,14 @@ export interface TimeStepOpts {
 }
 export type StateUpdate<T> = (curr: T, dt: number, ctx: ReadonlyTimeStep) => T;
 export type StateInterpolation<T> = (prev: T, curr: T, alpha: number, ctx: ReadonlyTimeStep) => T;
+/**
+ * Event ID for {@link TimeStep.addListener} to be notified of individual
+ * {@link ITimeStep.integrate} iterations.
+ */
+export declare const EVENT_INTEGRATE = "integrate";
+/**
+ * Event ID for {@link TimeStep.addListener} to be notified of calls to
+ * {@link TimeStep.update} (triggered at the very end of a frame update).
+ */
+export declare const EVENT_FRAME = "frame";
 //# sourceMappingURL=api.d.ts.map

package/api.js

@@ -1 +1,10 @@
-export {};
+/**
+ * Event ID for {@link TimeStep.addListener} to be notified of individual
+ * {@link ITimeStep.integrate} iterations.
+ */
+export const EVENT_INTEGRATE = "integrate";
+/**
+ * Event ID for {@link TimeStep.addListener} to be notified of calls to
+ * {@link TimeStep.update} (triggered at the very end of a frame update).
+ */
+export const EVENT_FRAME = "frame";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/timestep",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Deterministic fixed timestep simulation updates with state interpolation",
   "type": "module",
   "module": "./index.js",
@@ -88,5 +88,5 @@
     "status": "alpha",
     "year": 2023
   },
-  "gitHead": "ca22f02a137c0a4e3a38ef81e82e2bc7e3c43849\n"
+  "gitHead": "81dcbba93e7230c2f400bee87878145d902e975b\n"
 }

package/state.d.ts

@@ -1,13 +1,13 @@
 import type { IDeref } from "@thi.ng/api";
 import type { ReadonlyVec } from "@thi.ng/vectors";
-import type { IUpdatable, ReadonlyTimeStep, StateInterpolation, StateUpdate } from "./api.js";
+import type { ITimeStep, ReadonlyTimeStep, StateInterpolation, StateUpdate } from "./api.js";
 /**
  * Abstract base class for simulation state wrappers.
  *
  * @remarks
  * See {@link defNumeric} and {@link defVector}.
  */
-export declare abstract class AState<T> implements IDeref<T>, IUpdatable {
+export declare abstract class AState<T> implements IDeref<T>, ITimeStep {
     value: T;
     update: StateUpdate<T>;
     mix: StateInterpolation<T>;
@@ -17,12 +17,15 @@ export declare abstract class AState<T> implements IDeref<T>, IUpdatable {
     deref(): T;
     integrate(dt: number, ctx: ReadonlyTimeStep): void;
     interpolate(alpha: number, ctx: ReadonlyTimeStep): void;
+    abstract reset(value: T): void;
 }
 export declare class NumericState extends AState<number> {
     constructor(x: number, update: StateUpdate<number>);
+    reset(value: number): void;
 }
 export declare class VectorState extends AState<ReadonlyVec> {
     constructor(x: ReadonlyVec, update: StateUpdate<ReadonlyVec>);
+    reset(value: ReadonlyVec): void;
 }
 /**
  * Returns a new {@link NumericState} wrapper for given value `x` and its update
@@ -36,6 +39,10 @@ export declare const defNumeric: (x: number, update: StateUpdate<number>) => Num
  * Returns a new {@link VectorState} wrapper for given vector `v` and its update
  * function for use with {@link TimeStep.update}.
  *
+ * @remarks
+ * **IMPORTANT:** The `update` function MUST return a new vector and not mutate
+ * the existing one!
+ *
  * @param x
  * @param update
  */

package/state.js

@@ -1,5 +1,6 @@
 import { mix } from "@thi.ng/math/mix";
 import { mixN } from "@thi.ng/vectors/mixn";
+import { set } from "@thi.ng/vectors/set";
 /**
  * Abstract base class for simulation state wrappers.
  *
@@ -28,11 +29,19 @@ export class NumericState extends AState {
     constructor(x, update) {
         super(x, update, mix);
     }
+    reset(value) {
+        this.prev = this.curr = this.value = value;
+    }
 }
 export class VectorState extends AState {
     constructor(x, update) {
         super(x, update, (a, b, t) => mixN([], a, b, t));
     }
+    reset(value) {
+        set(this.prev, value);
+        set(this.curr, value);
+        set(this.value, value);
+    }
 }
 /**
  * Returns a new {@link NumericState} wrapper for given value `x` and its update
@@ -46,6 +55,10 @@ export const defNumeric = (x, update) => new NumericState(x, update);
  * Returns a new {@link VectorState} wrapper for given vector `v` and its update
  * function for use with {@link TimeStep.update}.
  *
+ * @remarks
+ * **IMPORTANT:** The `update` function MUST return a new vector and not mutate
+ * the existing one!
+ *
  * @param x
  * @param update
  */

package/timestep.d.ts

@@ -1,30 +1,56 @@
-import type { IUpdatable, TimeStepOpts } from "./api.js";
-export declare class TimeStep {
-    current: number;
+import { type Event, type INotify, type Listener } from "@thi.ng/api";
+import { type ITimeStep, type ReadonlyTimeStep, type TimeStepOpts } from "./api.js";
+export declare class TimeStep implements INotify {
     start: number;
     dt: number;
     maxFrameTime: number;
     scale: number;
+    t: number;
+    current: number;
     accumulator: number;
     frame: number;
     updates: number;
+    protected __eventIntegrate: Event;
+    protected __eventFrame: Event;
     constructor(opts?: Partial<TimeStepOpts>);
+    addListener(id: string, fn: Listener, scope?: any): boolean;
+    removeListener(id: string, fn: Listener, scope?: any): boolean;
+    notify(event: Event): boolean;
     /**
-     * Updates internal time to given new time `now` (in seconds) and performs
-     * the required number of fixed timesteps to integrate and interpolate the
-     * given `state` values.
+     * Updates internal time to given new time `now` (given value will be scaled
+     * via {@link TimeStepOpts.scale}) and performs the required number of fixed
+     * timesteps to integrate and interpolate the given `state` values.
      *
      * @remarks
-     * If `interpolate` is false, the {@link IUpdatable.interpolate} phase of
-     * the update cycle is skipped. This is useful when using this setup to
-     * simulate sub-steps (e.g. in XPBD) and only requiring the interpolation
-     * stage for the last step.
+     * If the scaled time difference since the last step is greater than
+     * {@link TimeStepOpts.maxFrameTime}, it will be limited to the latter.
+     *
+     * If `interpolate` is false, the {@link ITimeStep.interpolate} phase of the
+     * update cycle is skipped. This is useful when using this setup to simulate
+     * sub-steps (e.g. in XPBD) and only requiring the interpolation stage for
+     * the last step.
      *
      * @param now
      * @param items
      * @param interpolate
      */
-    update(now: number, items: IUpdatable[], interpolate?: boolean): void;
+    update(now: number, items: ITimeStep[], interpolate?: boolean): void;
 }
 export declare const defTimeStep: (opts?: Partial<TimeStepOpts>) => TimeStep;
+/**
+ * Calls {@link ITimeStep.integrate} for all given items (in given order).
+ *
+ * @param dt
+ * @param ctx
+ * @param items
+ */
+export declare const integrateAll: (dt: number, ctx: ReadonlyTimeStep, ...items: ITimeStep[]) => void;
+/**
+ * Calls {@link ITimeStep.interpolate} for all given items (in given order).
+ *
+ * @param dt
+ * @param ctx
+ * @param items
+ */
+export declare const interpolateAll: (alpha: number, ctx: ReadonlyTimeStep, ...items: ITimeStep[]) => void;
 //# sourceMappingURL=timestep.d.ts.map

package/timestep.js

@@ -1,5 +1,9 @@
-export class TimeStep {
+import { __decorate } from "tslib";
+import { INotifyMixin, } from "@thi.ng/api";
+import { EVENT_FRAME, EVENT_INTEGRATE, } from "./api.js";
+let TimeStep = class TimeStep {
     constructor(opts) {
+        this.t = 0;
         this.current = 0;
         this.accumulator = 0;
         this.frame = 0;
@@ -15,17 +19,31 @@ export class TimeStep {
         this.maxFrameTime = $opts.maxFrameTime;
         this.scale = $opts.scale;
         this.start = $opts.startTime * this.scale;
+        this.__eventIntegrate = Object.freeze({
+            id: EVENT_INTEGRATE,
+            target: this,
+        });
+        this.__eventFrame = Object.freeze({ id: EVENT_FRAME, target: this });
     }
+    // @ts-ignore mixin
+    addListener(id, fn, scope) { }
+    // @ts-ignore mixin
+    removeListener(id, fn, scope) { }
+    // @ts-ignore mixin
+    notify(event) { }
     /**
-     * Updates internal time to given new time `now` (in seconds) and performs
-     * the required number of fixed timesteps to integrate and interpolate the
-     * given `state` values.
+     * Updates internal time to given new time `now` (given value will be scaled
+     * via {@link TimeStepOpts.scale}) and performs the required number of fixed
+     * timesteps to integrate and interpolate the given `state` values.
      *
      * @remarks
-     * If `interpolate` is false, the {@link IUpdatable.interpolate} phase of
-     * the update cycle is skipped. This is useful when using this setup to
-     * simulate sub-steps (e.g. in XPBD) and only requiring the interpolation
-     * stage for the last step.
+     * If the scaled time difference since the last step is greater than
+     * {@link TimeStepOpts.maxFrameTime}, it will be limited to the latter.
+     *
+     * If `interpolate` is false, the {@link ITimeStep.interpolate} phase of the
+     * update cycle is skipped. This is useful when using this setup to simulate
+     * sub-steps (e.g. in XPBD) and only requiring the interpolation stage for
+     * the last step.
      *
      * @param now
      * @param items
@@ -33,8 +51,6 @@ export class TimeStep {
      */
     update(now, items, interpolate = true) {
         now = now * this.scale - this.start;
-        if (this.current < 0)
-            this.current = now;
         this.accumulator += Math.min(now - this.current, this.maxFrameTime);
         this.current = now;
         const n = items.length;
@@ -42,8 +58,10 @@ export class TimeStep {
         while (this.accumulator >= dt) {
             for (let i = 0; i < n; i++)
                 items[i].integrate(dt, this);
+            this.t += dt;
             this.accumulator -= dt;
             this.updates++;
+            this.notify(this.__eventIntegrate);
         }
         if (interpolate) {
             const alpha = this.accumulator / dt;
@@ -51,6 +69,33 @@ export class TimeStep {
                 items[i].interpolate(alpha, this);
         }
         this.frame++;
+        this.notify(this.__eventFrame);
     }
-}
+};
+TimeStep = __decorate([
+    INotifyMixin
+], TimeStep);
+export { TimeStep };
 export const defTimeStep = (opts) => new TimeStep(opts);
+/**
+ * Calls {@link ITimeStep.integrate} for all given items (in given order).
+ *
+ * @param dt
+ * @param ctx
+ * @param items
+ */
+export const integrateAll = (dt, ctx, ...items) => {
+    for (let i = 0, n = items.length; i < n; i++)
+        items[i].integrate(dt, ctx);
+};
+/**
+ * Calls {@link ITimeStep.interpolate} for all given items (in given order).
+ *
+ * @param dt
+ * @param ctx
+ * @param items
+ */
+export const interpolateAll = (alpha, ctx, ...items) => {
+    for (let i = 0, n = items.length; i < n; i++)
+        items[i].interpolate(alpha, ctx);
+};