@keyframe-engine/physics 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InitialXKO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/RealTimeSpring.d.ts

@@ -0,0 +1,36 @@
+export interface RealTimeSpringConfig {
+    mass?: number;
+    damping?: number;
+    stiffness?: number;
+    initialValue?: number;
+    initialVelocity?: number;
+}
+export declare class RealTimeSpring {
+    private static activeInstanceCount;
+    private mass;
+    private damping;
+    private stiffness;
+    private value;
+    private velocity;
+    constructor(config?: RealTimeSpringConfig);
+    static getActiveInstanceCount(): number;
+    static resetInstanceCount(): void;
+    /**
+     * Advances the spring simulation state towards target by deltaTime.
+     * Automatically handles deltaTime passed in seconds (e.g. 0.016) or milliseconds (e.g. 16.66).
+     * @returns current value after step
+     */
+    step(target: number, deltaTime: number): number;
+    /**
+     * Resets spring position and velocity state.
+     */
+    reset(value?: number, velocity?: number): void;
+    /**
+     * Returns current spring velocity.
+     */
+    getVelocity(): number;
+    /**
+     * Returns current spring value.
+     */
+    getValue(): number;
+}

package/dist/RealTimeSpring.js

@@ -0,0 +1,69 @@
+export class RealTimeSpring {
+    static activeInstanceCount = 0;
+    mass;
+    damping;
+    stiffness;
+    value;
+    velocity;
+    constructor(config = {}) {
+        this.mass = config.mass ?? 1.0;
+        this.damping = config.damping ?? 10;
+        this.stiffness = config.stiffness ?? 100;
+        this.value = config.initialValue ?? 0;
+        this.velocity = config.initialVelocity ?? 0;
+        RealTimeSpring.activeInstanceCount++;
+        if (RealTimeSpring.activeInstanceCount > 200) {
+            console.warn("[@keyframe-engine/physics] Large number of live springs (>200). Consider using baked physics or reducing update frequency.");
+        }
+    }
+    static getActiveInstanceCount() {
+        return RealTimeSpring.activeInstanceCount;
+    }
+    static resetInstanceCount() {
+        RealTimeSpring.activeInstanceCount = 0;
+    }
+    /**
+     * Advances the spring simulation state towards target by deltaTime.
+     * Automatically handles deltaTime passed in seconds (e.g. 0.016) or milliseconds (e.g. 16.66).
+     * @returns current value after step
+     */
+    step(target, deltaTime) {
+        if (deltaTime <= 0) {
+            return this.value;
+        }
+        // Convert milliseconds to seconds if deltaTime is > 1.0
+        let dt = deltaTime > 1.0 ? deltaTime / 1000 : deltaTime;
+        // Sub-stepping for numerical stability (max sub-step = 1ms = 0.001s)
+        const subStep = 0.001;
+        while (dt > 0) {
+            const currentDt = Math.min(dt, subStep);
+            // Spring force equation: F = -stiffness * (x - target) - damping * v
+            const force = -this.stiffness * (this.value - target) - this.damping * this.velocity;
+            const accel = force / (this.mass || 1.0);
+            // Semi-implicit Euler step
+            this.velocity += accel * currentDt;
+            this.value += this.velocity * currentDt;
+            dt -= currentDt;
+        }
+        return this.value;
+    }
+    /**
+     * Resets spring position and velocity state.
+     */
+    reset(value, velocity) {
+        this.value = value ?? 0;
+        this.velocity = velocity ?? 0;
+    }
+    /**
+     * Returns current spring velocity.
+     */
+    getVelocity() {
+        return this.velocity;
+    }
+    /**
+     * Returns current spring value.
+     */
+    getValue() {
+        return this.value;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './RealTimeSpring.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './RealTimeSpring.js';

package/dist/js/physics/RealTimeSpring.d.ts

@@ -0,0 +1,36 @@
+export interface RealTimeSpringConfig {
+    mass?: number;
+    damping?: number;
+    stiffness?: number;
+    initialValue?: number;
+    initialVelocity?: number;
+}
+export declare class RealTimeSpring {
+    private static activeInstanceCount;
+    private mass;
+    private damping;
+    private stiffness;
+    private value;
+    private velocity;
+    constructor(config?: RealTimeSpringConfig);
+    static getActiveInstanceCount(): number;
+    static resetInstanceCount(): void;
+    /**
+     * Advances the spring simulation state towards target by deltaTime.
+     * Automatically handles deltaTime passed in seconds (e.g. 0.016) or milliseconds (e.g. 16.66).
+     * @returns current value after step
+     */
+    step(target: number, deltaTime: number): number;
+    /**
+     * Resets spring position and velocity state.
+     */
+    reset(value?: number, velocity?: number): void;
+    /**
+     * Returns current spring velocity.
+     */
+    getVelocity(): number;
+    /**
+     * Returns current spring value.
+     */
+    getValue(): number;
+}

package/dist/js/physics/RealTimeSpring.js

@@ -0,0 +1,69 @@
+export class RealTimeSpring {
+    static activeInstanceCount = 0;
+    mass;
+    damping;
+    stiffness;
+    value;
+    velocity;
+    constructor(config = {}) {
+        this.mass = config.mass ?? 1.0;
+        this.damping = config.damping ?? 10;
+        this.stiffness = config.stiffness ?? 100;
+        this.value = config.initialValue ?? 0;
+        this.velocity = config.initialVelocity ?? 0;
+        RealTimeSpring.activeInstanceCount++;
+        if (RealTimeSpring.activeInstanceCount > 200) {
+            console.warn("[@keyframe-engine/physics] Large number of live springs (>200). Consider using baked physics or reducing update frequency.");
+        }
+    }
+    static getActiveInstanceCount() {
+        return RealTimeSpring.activeInstanceCount;
+    }
+    static resetInstanceCount() {
+        RealTimeSpring.activeInstanceCount = 0;
+    }
+    /**
+     * Advances the spring simulation state towards target by deltaTime.
+     * Automatically handles deltaTime passed in seconds (e.g. 0.016) or milliseconds (e.g. 16.66).
+     * @returns current value after step
+     */
+    step(target, deltaTime) {
+        if (deltaTime <= 0) {
+            return this.value;
+        }
+        // Convert milliseconds to seconds if deltaTime is > 1.0
+        let dt = deltaTime > 1.0 ? deltaTime / 1000 : deltaTime;
+        // Sub-stepping for numerical stability (max sub-step = 1ms = 0.001s)
+        const subStep = 0.001;
+        while (dt > 0) {
+            const currentDt = Math.min(dt, subStep);
+            // Spring force equation: F = -stiffness * (x - target) - damping * v
+            const force = -this.stiffness * (this.value - target) - this.damping * this.velocity;
+            const accel = force / (this.mass || 1.0);
+            // Semi-implicit Euler step
+            this.velocity += accel * currentDt;
+            this.value += this.velocity * currentDt;
+            dt -= currentDt;
+        }
+        return this.value;
+    }
+    /**
+     * Resets spring position and velocity state.
+     */
+    reset(value, velocity) {
+        this.value = value ?? 0;
+        this.velocity = velocity ?? 0;
+    }
+    /**
+     * Returns current spring velocity.
+     */
+    getVelocity() {
+        return this.velocity;
+    }
+    /**
+     * Returns current spring value.
+     */
+    getValue() {
+        return this.value;
+    }
+}

package/dist/packages/physics/src/RealTimeSpring.d.ts

@@ -0,0 +1 @@
+export * from "../../../js/physics/RealTimeSpring.js";

package/dist/packages/physics/src/RealTimeSpring.js

@@ -0,0 +1 @@
+export * from "../../../js/physics/RealTimeSpring.js";

package/dist/packages/physics/src/index.d.ts

@@ -0,0 +1 @@
+export * from "../../../js/physics/RealTimeSpring.js";

package/dist/packages/physics/src/index.js

@@ -0,0 +1 @@
+export * from "../../../js/physics/RealTimeSpring.js";

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@keyframe-engine/physics",
+  "version": "1.0.0",
+  "description": "@keyframe-engine/physics — Real-time Physics & Spring Engine Adapter",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@keyframe-engine/core": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/RealTimeSpring.d.ts

@@ -0,0 +1,36 @@
+export interface RealTimeSpringConfig {
+    mass?: number;
+    damping?: number;
+    stiffness?: number;
+    initialValue?: number;
+    initialVelocity?: number;
+}
+export declare class RealTimeSpring {
+    private static activeInstanceCount;
+    private mass;
+    private damping;
+    private stiffness;
+    private value;
+    private velocity;
+    constructor(config?: RealTimeSpringConfig);
+    static getActiveInstanceCount(): number;
+    static resetInstanceCount(): void;
+    /**
+     * Advances the spring simulation state towards target by deltaTime.
+     * Automatically handles deltaTime passed in seconds (e.g. 0.016) or milliseconds (e.g. 16.66).
+     * @returns current value after step
+     */
+    step(target: number, deltaTime: number): number;
+    /**
+     * Resets spring position and velocity state.
+     */
+    reset(value?: number, velocity?: number): void;
+    /**
+     * Returns current spring velocity.
+     */
+    getVelocity(): number;
+    /**
+     * Returns current spring value.
+     */
+    getValue(): number;
+}

package/src/RealTimeSpring.js

@@ -0,0 +1,69 @@
+export class RealTimeSpring {
+    static activeInstanceCount = 0;
+    mass;
+    damping;
+    stiffness;
+    value;
+    velocity;
+    constructor(config = {}) {
+        this.mass = config.mass ?? 1.0;
+        this.damping = config.damping ?? 10;
+        this.stiffness = config.stiffness ?? 100;
+        this.value = config.initialValue ?? 0;
+        this.velocity = config.initialVelocity ?? 0;
+        RealTimeSpring.activeInstanceCount++;
+        if (RealTimeSpring.activeInstanceCount > 200) {
+            console.warn("[@keyframe-engine/physics] Large number of live springs (>200). Consider using baked physics or reducing update frequency.");
+        }
+    }
+    static getActiveInstanceCount() {
+        return RealTimeSpring.activeInstanceCount;
+    }
+    static resetInstanceCount() {
+        RealTimeSpring.activeInstanceCount = 0;
+    }
+    /**
+     * Advances the spring simulation state towards target by deltaTime.
+     * Automatically handles deltaTime passed in seconds (e.g. 0.016) or milliseconds (e.g. 16.66).
+     * @returns current value after step
+     */
+    step(target, deltaTime) {
+        if (deltaTime <= 0) {
+            return this.value;
+        }
+        // Convert milliseconds to seconds if deltaTime is > 1.0
+        let dt = deltaTime > 1.0 ? deltaTime / 1000 : deltaTime;
+        // Sub-stepping for numerical stability (max sub-step = 1ms = 0.001s)
+        const subStep = 0.001;
+        while (dt > 0) {
+            const currentDt = Math.min(dt, subStep);
+            // Spring force equation: F = -stiffness * (x - target) - damping * v
+            const force = -this.stiffness * (this.value - target) - this.damping * this.velocity;
+            const accel = force / (this.mass || 1.0);
+            // Semi-implicit Euler step
+            this.velocity += accel * currentDt;
+            this.value += this.velocity * currentDt;
+            dt -= currentDt;
+        }
+        return this.value;
+    }
+    /**
+     * Resets spring position and velocity state.
+     */
+    reset(value, velocity) {
+        this.value = value ?? 0;
+        this.velocity = velocity ?? 0;
+    }
+    /**
+     * Returns current spring velocity.
+     */
+    getVelocity() {
+        return this.velocity;
+    }
+    /**
+     * Returns current spring value.
+     */
+    getValue() {
+        return this.value;
+    }
+}

package/src/RealTimeSpring.ts

@@ -0,0 +1,94 @@
+export interface RealTimeSpringConfig {
+  mass?: number;        // Default 1.0
+  damping?: number;     // Default 10
+  stiffness?: number;   // Default 100
+  initialValue?: number; // Default 0
+  initialVelocity?: number; // Default 0
+}
+
+export class RealTimeSpring {
+  private static activeInstanceCount = 0;
+
+  private mass: number;
+  private damping: number;
+  private stiffness: number;
+  private value: number;
+  private velocity: number;
+
+  constructor(config: RealTimeSpringConfig = {}) {
+    this.mass = config.mass ?? 1.0;
+    this.damping = config.damping ?? 10;
+    this.stiffness = config.stiffness ?? 100;
+    this.value = config.initialValue ?? 0;
+    this.velocity = config.initialVelocity ?? 0;
+
+    RealTimeSpring.activeInstanceCount++;
+    if (RealTimeSpring.activeInstanceCount > 200) {
+      console.warn(
+        "[@keyframe-engine/physics] Large number of live springs (>200). Consider using baked physics or reducing update frequency."
+      );
+    }
+  }
+
+  public static getActiveInstanceCount(): number {
+    return RealTimeSpring.activeInstanceCount;
+  }
+
+  public static resetInstanceCount(): void {
+    RealTimeSpring.activeInstanceCount = 0;
+  }
+
+  /**
+   * Advances the spring simulation state towards target by deltaTime.
+   * Automatically handles deltaTime passed in seconds (e.g. 0.016) or milliseconds (e.g. 16.66).
+   * @returns current value after step
+   */
+  public step(target: number, deltaTime: number): number {
+    if (deltaTime <= 0) {
+      return this.value;
+    }
+
+    // Convert milliseconds to seconds if deltaTime is > 1.0
+    let dt = deltaTime > 1.0 ? deltaTime / 1000 : deltaTime;
+
+    // Sub-stepping for numerical stability (max sub-step = 1ms = 0.001s)
+    const subStep = 0.001;
+    while (dt > 0) {
+      const currentDt = Math.min(dt, subStep);
+
+      // Spring force equation: F = -stiffness * (x - target) - damping * v
+      const force = -this.stiffness * (this.value - target) - this.damping * this.velocity;
+      const accel = force / (this.mass || 1.0);
+
+      // Semi-implicit Euler step
+      this.velocity += accel * currentDt;
+      this.value += this.velocity * currentDt;
+
+      dt -= currentDt;
+    }
+
+    return this.value;
+  }
+
+  /**
+   * Resets spring position and velocity state.
+   */
+  public reset(value?: number, velocity?: number): void {
+    this.value = value ?? 0;
+    this.velocity = velocity ?? 0;
+  }
+
+  /**
+   * Returns current spring velocity.
+   */
+  public getVelocity(): number {
+    return this.velocity;
+  }
+
+  /**
+   * Returns current spring value.
+   */
+  public getValue(): number {
+    return this.value;
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './RealTimeSpring.js';

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}