@keyframe-engine/three 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/index.d.ts

@@ -0,0 +1,45 @@
+export interface RegisterSceneOptions {
+    defaultFastDirty?: boolean;
+}
+export interface RegisterObjectOptions {
+    fastDirty?: boolean;
+}
+export interface ApplyOptions {
+    fastDirty?: boolean;
+}
+export interface AdapterObjectOptions {
+    fastDirty?: boolean;
+}
+export declare class AdapterContext {
+    readonly scene: any;
+    readonly engine: any;
+    readonly defaultFastDirty: boolean;
+    readonly registeredObjects: Set<any>;
+    readonly objectOptions: Map<any, AdapterObjectOptions>;
+    constructor(scene: any, engine: any, options?: RegisterSceneOptions);
+    registerObject(object: any, options?: RegisterObjectOptions): void;
+    unregisterObject(object: any, restoreControl?: boolean): void;
+}
+export declare class ThreeAdapter {
+    /**
+     * Register scene and get unique AdapterContext credential handle.
+     */
+    registerScene(scene: any, engine: any, options?: RegisterSceneOptions): AdapterContext;
+    /**
+     * Unbind scene context.
+     * @param ctx AdapterContext handle
+     * @param restoreControl true (default): restore matrixAutoUpdate=true and updateMatrix().
+     *                       false: clear internal references directly, skip matrix restore.
+     *                       WARNING: If false is used on non-disposed scene, objects remain locked.
+     */
+    unregisterScene(ctx: AdapterContext, restoreControl?: boolean): void;
+    /**
+     * Apply matrices to all registered objects in Context credential.
+     * Atomic execution order:
+     * 1. object.matrixAutoUpdate = false
+     * 2. object.matrix.copy(rawMatrix) / elements assignment
+     * 3. if (!fastDirty) matrix.decompose(position, quaternion, scale)
+     */
+    applyToScene(ctx: AdapterContext, time: number, options?: ApplyOptions): void;
+}
+export declare const threeAdapter: ThreeAdapter;

package/dist/index.js

@@ -0,0 +1,117 @@
+export class AdapterContext {
+    scene;
+    engine;
+    defaultFastDirty;
+    registeredObjects = new Set();
+    objectOptions = new Map();
+    constructor(scene, engine, options) {
+        this.scene = scene;
+        this.engine = engine;
+        this.defaultFastDirty = options?.defaultFastDirty ?? false;
+    }
+    registerObject(object, options) {
+        if (!object)
+            return;
+        this.registeredObjects.add(object);
+        if (options) {
+            this.objectOptions.set(object, { fastDirty: options.fastDirty });
+        }
+        object.matrixAutoUpdate = false;
+    }
+    unregisterObject(object, restoreControl = true) {
+        if (!object)
+            return;
+        this.registeredObjects.delete(object);
+        this.objectOptions.delete(object);
+        if (restoreControl) {
+            object.matrixAutoUpdate = true;
+            if (typeof object.updateMatrix === "function") {
+                object.updateMatrix();
+            }
+        }
+    }
+}
+export class ThreeAdapter {
+    /**
+     * Register scene and get unique AdapterContext credential handle.
+     */
+    registerScene(scene, engine, options) {
+        return new AdapterContext(scene, engine, options);
+    }
+    /**
+     * Unbind scene context.
+     * @param ctx AdapterContext handle
+     * @param restoreControl true (default): restore matrixAutoUpdate=true and updateMatrix().
+     *                       false: clear internal references directly, skip matrix restore.
+     *                       WARNING: If false is used on non-disposed scene, objects remain locked.
+     */
+    unregisterScene(ctx, restoreControl = true) {
+        if (!ctx)
+            return;
+        if (restoreControl) {
+            for (const obj of ctx.registeredObjects) {
+                obj.matrixAutoUpdate = true;
+                if (typeof obj.updateMatrix === "function") {
+                    obj.updateMatrix();
+                }
+            }
+        }
+        ctx.registeredObjects.clear();
+        ctx.objectOptions.clear();
+    }
+    /**
+     * Apply matrices to all registered objects in Context credential.
+     * Atomic execution order:
+     * 1. object.matrixAutoUpdate = false
+     * 2. object.matrix.copy(rawMatrix) / elements assignment
+     * 3. if (!fastDirty) matrix.decompose(position, quaternion, scale)
+     */
+    applyToScene(ctx, time, options) {
+        if (!ctx || !ctx.engine)
+            return;
+        const evaluated = ctx.engine.getEvaluatedInstances(time);
+        const objectsArray = Array.from(ctx.registeredObjects);
+        const sceneDefaultFastDirty = ctx.defaultFastDirty;
+        const globalFastDirty = options?.fastDirty;
+        for (let i = 0; i < objectsArray.length; i++) {
+            const obj = objectsArray[i];
+            const instData = evaluated[i];
+            if (!obj || !instData)
+                continue;
+            // 1. Lock control
+            obj.matrixAutoUpdate = false;
+            // 2. Write native column-major matrix
+            const rawMatrix = instData.transformMatrix;
+            if (obj.matrix) {
+                if (typeof obj.matrix.fromArray === "function") {
+                    obj.matrix.fromArray(rawMatrix);
+                }
+                else if (typeof obj.matrix.copy === "function" && rawMatrix.elements) {
+                    obj.matrix.copy(rawMatrix);
+                }
+                else if (obj.matrix.elements) {
+                    obj.matrix.elements.set(rawMatrix);
+                }
+                else {
+                    obj.matrix.elements = new Float32Array(rawMatrix);
+                }
+            }
+            // Determine fastDirty strategy
+            const objSpecificFastDirty = ctx.objectOptions.get(obj)?.fastDirty;
+            const isFastDirty = globalFastDirty ?? objSpecificFastDirty ?? sceneDefaultFastDirty;
+            // 3. Decompose if fastDirty is false
+            if (!isFastDirty && obj.matrix) {
+                if (typeof obj.matrix.decompose === "function") {
+                    if (!obj.position)
+                        obj.position = { x: 0, y: 0, z: 0 };
+                    if (!obj.quaternion)
+                        obj.quaternion = { x: 0, y: 0, z: 0, w: 1 };
+                    if (!obj.scale)
+                        obj.scale = { x: 1, y: 1, z: 1 };
+                    obj.matrix.decompose(obj.position, obj.quaternion, obj.scale);
+                }
+            }
+        }
+    }
+}
+export const threeAdapter = new ThreeAdapter();

package/dist/js/adapters/three_adapter.d.ts

@@ -0,0 +1,31 @@
+export interface RegisterSceneOptions {
+    defaultRasterized?: boolean;
+}
+export interface RegisterObjectOptions {
+    rasterized?: boolean;
+}
+export interface ApplyOptions {
+    rasterized?: boolean;
+}
+export interface UnregisterSceneOptions {
+    abandoned?: boolean;
+}
+export interface AdapterObjectOptions {
+    rasterized?: boolean;
+}
+export declare class AdapterContext {
+    readonly scene: any;
+    readonly engine: any;
+    readonly defaultRasterized: boolean;
+    readonly registeredObjects: Set<any>;
+    readonly objectOptions: Map<any, AdapterObjectOptions>;
+    constructor(scene: any, engine: any, options?: RegisterSceneOptions);
+    registerObject(object: any, options?: RegisterObjectOptions): void;
+    unregisterObject(object: any, options?: UnregisterSceneOptions): void;
+}
+export declare class ThreeAdapter {
+    registerScene(scene: any, engine: any, options?: RegisterSceneOptions): AdapterContext;
+    unregisterScene(ctx: AdapterContext, options?: UnregisterSceneOptions): void;
+    applyToScene(ctx: AdapterContext, time: number, options?: ApplyOptions): void;
+}
+export declare const threeAdapter: ThreeAdapter;

package/dist/js/adapters/three_adapter.js

@@ -0,0 +1,98 @@
+export class AdapterContext {
+    scene;
+    engine;
+    defaultRasterized;
+    registeredObjects = new Set();
+    objectOptions = new Map();
+    constructor(scene, engine, options) {
+        this.scene = scene;
+        this.engine = engine;
+        this.defaultRasterized = options?.defaultRasterized ?? false;
+    }
+    registerObject(object, options) {
+        if (!object)
+            return;
+        this.registeredObjects.add(object);
+        if (options?.rasterized !== undefined) {
+            this.objectOptions.set(object, { rasterized: options.rasterized });
+        }
+        object.matrixAutoUpdate = false;
+    }
+    unregisterObject(object, options) {
+        if (!object)
+            return;
+        this.registeredObjects.delete(object);
+        this.objectOptions.delete(object);
+        const isAbandoned = options?.abandoned ?? false;
+        if (!isAbandoned) {
+            object.matrixAutoUpdate = true;
+            if (typeof object.updateMatrix === "function") {
+                object.updateMatrix();
+            }
+        }
+    }
+}
+export class ThreeAdapter {
+    registerScene(scene, engine, options) {
+        return new AdapterContext(scene, engine, options);
+    }
+    unregisterScene(ctx, options) {
+        if (!ctx)
+            return;
+        const isAbandoned = options?.abandoned ?? false;
+        if (!isAbandoned) {
+            for (const obj of ctx.registeredObjects) {
+                obj.matrixAutoUpdate = true;
+                if (typeof obj.updateMatrix === "function") {
+                    obj.updateMatrix();
+                }
+            }
+        }
+        ctx.registeredObjects.clear();
+        ctx.objectOptions.clear();
+    }
+    applyToScene(ctx, time, options) {
+        if (!ctx || !ctx.engine)
+            return;
+        const evaluated = ctx.engine.getEvaluatedInstances(time);
+        const objectsArray = Array.from(ctx.registeredObjects);
+        const sceneDefaultRasterized = ctx.defaultRasterized;
+        const globalRasterized = options?.rasterized;
+        for (let i = 0; i < objectsArray.length; i++) {
+            const obj = objectsArray[i];
+            const instData = evaluated[i];
+            if (!obj || !instData)
+                continue;
+            obj.matrixAutoUpdate = false;
+            const rawMatrix = instData.transformMatrix;
+            if (obj.matrix) {
+                if (typeof obj.matrix.fromArray === "function") {
+                    obj.matrix.fromArray(rawMatrix);
+                }
+                else if (typeof obj.matrix.copy === "function" && rawMatrix.elements) {
+                    obj.matrix.copy(rawMatrix);
+                }
+                else if (obj.matrix.elements) {
+                    obj.matrix.elements.set(rawMatrix);
+                }
+                else {
+                    obj.matrix.elements = new Float32Array(rawMatrix);
+                }
+            }
+            const objSpecificRasterized = ctx.objectOptions.get(obj)?.rasterized;
+            const isRasterized = globalRasterized ?? objSpecificRasterized ?? sceneDefaultRasterized;
+            if (!isRasterized && obj.matrix) {
+                if (typeof obj.matrix.decompose === "function") {
+                    if (!obj.position)
+                        obj.position = { x: 0, y: 0, z: 0 };
+                    if (!obj.quaternion)
+                        obj.quaternion = { x: 0, y: 0, z: 0, w: 1 };
+                    if (!obj.scale)
+                        obj.scale = { x: 1, y: 1, z: 1 };
+                    obj.matrix.decompose(obj.position, obj.quaternion, obj.scale);
+                }
+            }
+        }
+    }
+}
+export const threeAdapter = new ThreeAdapter();

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

@@ -0,0 +1 @@
+export * from "../../../js/adapters/three_adapter.js";

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

@@ -0,0 +1 @@
+export * from "../../../js/adapters/three_adapter.js";

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@keyframe-engine/three",
+  "version": "1.0.0",
+  "description": "@keyframe-engine/three — Three.js Binding Adapter",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "three": "^0.150.0",
+    "@keyframe-engine/core": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,45 @@
+export interface RegisterSceneOptions {
+    defaultFastDirty?: boolean;
+}
+export interface RegisterObjectOptions {
+    fastDirty?: boolean;
+}
+export interface ApplyOptions {
+    fastDirty?: boolean;
+}
+export interface AdapterObjectOptions {
+    fastDirty?: boolean;
+}
+export declare class AdapterContext {
+    readonly scene: any;
+    readonly engine: any;
+    readonly defaultFastDirty: boolean;
+    readonly registeredObjects: Set<any>;
+    readonly objectOptions: Map<any, AdapterObjectOptions>;
+    constructor(scene: any, engine: any, options?: RegisterSceneOptions);
+    registerObject(object: any, options?: RegisterObjectOptions): void;
+    unregisterObject(object: any, restoreControl?: boolean): void;
+}
+export declare class ThreeAdapter {
+    /**
+     * Register scene and get unique AdapterContext credential handle.
+     */
+    registerScene(scene: any, engine: any, options?: RegisterSceneOptions): AdapterContext;
+    /**
+     * Unbind scene context.
+     * @param ctx AdapterContext handle
+     * @param restoreControl true (default): restore matrixAutoUpdate=true and updateMatrix().
+     *                       false: clear internal references directly, skip matrix restore.
+     *                       WARNING: If false is used on non-disposed scene, objects remain locked.
+     */
+    unregisterScene(ctx: AdapterContext, restoreControl?: boolean): void;
+    /**
+     * Apply matrices to all registered objects in Context credential.
+     * Atomic execution order:
+     * 1. object.matrixAutoUpdate = false
+     * 2. object.matrix.copy(rawMatrix) / elements assignment
+     * 3. if (!fastDirty) matrix.decompose(position, quaternion, scale)
+     */
+    applyToScene(ctx: AdapterContext, time: number, options?: ApplyOptions): void;
+}
+export declare const threeAdapter: ThreeAdapter;

package/src/index.js

@@ -0,0 +1,117 @@
+export class AdapterContext {
+    scene;
+    engine;
+    defaultFastDirty;
+    registeredObjects = new Set();
+    objectOptions = new Map();
+    constructor(scene, engine, options) {
+        this.scene = scene;
+        this.engine = engine;
+        this.defaultFastDirty = options?.defaultFastDirty ?? false;
+    }
+    registerObject(object, options) {
+        if (!object)
+            return;
+        this.registeredObjects.add(object);
+        if (options) {
+            this.objectOptions.set(object, { fastDirty: options.fastDirty });
+        }
+        object.matrixAutoUpdate = false;
+    }
+    unregisterObject(object, restoreControl = true) {
+        if (!object)
+            return;
+        this.registeredObjects.delete(object);
+        this.objectOptions.delete(object);
+        if (restoreControl) {
+            object.matrixAutoUpdate = true;
+            if (typeof object.updateMatrix === "function") {
+                object.updateMatrix();
+            }
+        }
+    }
+}
+export class ThreeAdapter {
+    /**
+     * Register scene and get unique AdapterContext credential handle.
+     */
+    registerScene(scene, engine, options) {
+        return new AdapterContext(scene, engine, options);
+    }
+    /**
+     * Unbind scene context.
+     * @param ctx AdapterContext handle
+     * @param restoreControl true (default): restore matrixAutoUpdate=true and updateMatrix().
+     *                       false: clear internal references directly, skip matrix restore.
+     *                       WARNING: If false is used on non-disposed scene, objects remain locked.
+     */
+    unregisterScene(ctx, restoreControl = true) {
+        if (!ctx)
+            return;
+        if (restoreControl) {
+            for (const obj of ctx.registeredObjects) {
+                obj.matrixAutoUpdate = true;
+                if (typeof obj.updateMatrix === "function") {
+                    obj.updateMatrix();
+                }
+            }
+        }
+        ctx.registeredObjects.clear();
+        ctx.objectOptions.clear();
+    }
+    /**
+     * Apply matrices to all registered objects in Context credential.
+     * Atomic execution order:
+     * 1. object.matrixAutoUpdate = false
+     * 2. object.matrix.copy(rawMatrix) / elements assignment
+     * 3. if (!fastDirty) matrix.decompose(position, quaternion, scale)
+     */
+    applyToScene(ctx, time, options) {
+        if (!ctx || !ctx.engine)
+            return;
+        const evaluated = ctx.engine.getEvaluatedInstances(time);
+        const objectsArray = Array.from(ctx.registeredObjects);
+        const sceneDefaultFastDirty = ctx.defaultFastDirty;
+        const globalFastDirty = options?.fastDirty;
+        for (let i = 0; i < objectsArray.length; i++) {
+            const obj = objectsArray[i];
+            const instData = evaluated[i];
+            if (!obj || !instData)
+                continue;
+            // 1. Lock control
+            obj.matrixAutoUpdate = false;
+            // 2. Write native column-major matrix
+            const rawMatrix = instData.transformMatrix;
+            if (obj.matrix) {
+                if (typeof obj.matrix.fromArray === "function") {
+                    obj.matrix.fromArray(rawMatrix);
+                }
+                else if (typeof obj.matrix.copy === "function" && rawMatrix.elements) {
+                    obj.matrix.copy(rawMatrix);
+                }
+                else if (obj.matrix.elements) {
+                    obj.matrix.elements.set(rawMatrix);
+                }
+                else {
+                    obj.matrix.elements = new Float32Array(rawMatrix);
+                }
+            }
+            // Determine fastDirty strategy
+            const objSpecificFastDirty = ctx.objectOptions.get(obj)?.fastDirty;
+            const isFastDirty = globalFastDirty ?? objSpecificFastDirty ?? sceneDefaultFastDirty;
+            // 3. Decompose if fastDirty is false
+            if (!isFastDirty && obj.matrix) {
+                if (typeof obj.matrix.decompose === "function") {
+                    if (!obj.position)
+                        obj.position = { x: 0, y: 0, z: 0 };
+                    if (!obj.quaternion)
+                        obj.quaternion = { x: 0, y: 0, z: 0, w: 1 };
+                    if (!obj.scale)
+                        obj.scale = { x: 1, y: 1, z: 1 };
+                    obj.matrix.decompose(obj.position, obj.quaternion, obj.scale);
+                }
+            }
+        }
+    }
+}
+export const threeAdapter = new ThreeAdapter();

package/src/index.ts

@@ -0,0 +1 @@
+export * from "../../../js/adapters/three_adapter.js";

package/tsconfig.json

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