@thi.ng/timestep 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-04-28T17:22:36Z
+- **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,16 @@ 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

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.
@@ -94,7 +94,7 @@ 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 IUpdatable.integrate} iterations.
+ * {@link ITimeStep.integrate} iterations.
  */
 export declare const EVENT_INTEGRATE = "integrate";
 /**

package/api.js

@@ -1,6 +1,6 @@
 /**
  * Event ID for {@link TimeStep.addListener} to be notified of individual
- * {@link IUpdatable.integrate} iterations.
+ * {@link ITimeStep.integrate} iterations.
  */
 export const EVENT_INTEGRATE = "integrate";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/timestep",
-  "version": "0.2.0",
+  "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": "e71e2d061ac0a754ce4899bb59208afb8b3d94b2\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,5 +1,5 @@
 import { type Event, type INotify, type Listener } from "@thi.ng/api";
-import { type IUpdatable, type ReadonlyTimeStep, type TimeStepOpts } from "./api.js";
+import { type ITimeStep, type ReadonlyTimeStep, type TimeStepOpts } from "./api.js";
 export declare class TimeStep implements INotify {
     start: number;
     dt: number;
@@ -17,37 +17,40 @@ export declare class TimeStep implements INotify {
     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 IUpdatable.integrate} for all given items (in given order).
+ * 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: IUpdatable[]) => void;
+export declare const integrateAll: (dt: number, ctx: ReadonlyTimeStep, ...items: ITimeStep[]) => void;
 /**
- * Calls {@link IUpdatable.interpolate} for all given items (in given order).
+ * 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: IUpdatable[]) => void;
+export declare const interpolateAll: (alpha: number, ctx: ReadonlyTimeStep, ...items: ITimeStep[]) => void;
 //# sourceMappingURL=timestep.d.ts.map

package/timestep.js

@@ -32,15 +32,18 @@ let TimeStep = class TimeStep {
     // @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
@@ -75,7 +78,7 @@ TimeStep = __decorate([
 export { TimeStep };
 export const defTimeStep = (opts) => new TimeStep(opts);
 /**
- * Calls {@link IUpdatable.integrate} for all given items (in given order).
+ * Calls {@link ITimeStep.integrate} for all given items (in given order).
  *
  * @param dt
  * @param ctx
@@ -86,7 +89,7 @@ export const integrateAll = (dt, ctx, ...items) => {
         items[i].integrate(dt, ctx);
 };
 /**
- * Calls {@link IUpdatable.interpolate} for all given items (in given order).
+ * Calls {@link ITimeStep.interpolate} for all given items (in given order).
  *
  * @param dt
  * @param ctx