@iwsdk/core 0.1.0

package/dist/physics/physicsManipulation.js

@@ -0,0 +1,46 @@
+import '../index.js';
+import { createComponent, Types } from 'elics';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Component for applying one‑time physics manipulations to an entity.
+ *
+ * @remarks
+ * - This component is automatically removed after the manipulations are applied.
+ * - Force is applied as an impulse at the entity's center of mass.
+ * - Setting linear or angular velocity overrides the current velocity.
+ * - All manipulations are applied in a single frame, then the component is removed.
+ * - Requires the entity to have {@link PhysicsBody}.
+ *
+ * @example Apply an upward force to make an object jump
+ * ```ts
+ * entity.addComponent(PhysicsManipulation, {
+ *   force: [0, 10, 0]
+ * })
+ * ```
+ *
+ * @example Set specific velocity for controlled movement
+ * ```ts
+ * entity.addComponent(PhysicsManipulation, {
+ *   linearVelocity: [5, 0, 0],
+ *   angularVelocity: [0, 2, 0]
+ * })
+ * ```
+ *
+ * @category Physics
+ * @see {@link PhysicsSystem}
+ * @see {@link PhysicsBody}
+ */
+const PhysicsManipulation = createComponent('PhysicsManipulation', {
+    force: { type: Types.Vec3, default: [0.0, 0.0, 0.0] },
+    linearVelocity: { type: Types.Vec3, default: [0.0, 0.0, 0.0] },
+    angularVelocity: { type: Types.Vec3, default: [0.0, 0.0, 0.0] },
+}, 'Component to apply physics manipulations to an entity.');
+
+export { PhysicsManipulation };
+//# sourceMappingURL=physicsManipulation.js.map

package/dist/physics/physicsManipulation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physicsManipulation.js","sources":["../../src/physics/physicsManipulation.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;;;;;AAKG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;AAEI,MAAM,mBAAmB,GAAG,eAAe,CAChD,qBAAqB,EACrB;AACE,IAAA,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE;AACrD,IAAA,cAAc,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE;AAC9D,IAAA,eAAe,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE;CAChE,EACD,wDAAwD;;;;"}

package/dist/physics/physicsShape.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Types } from '.././index.js';
+/** Available physics shape types for {@link PhysicsShape}. @category Physics */
+export declare const PhysicsShapeType: {
+    /** The sphere is described by just the radius in dimensions[0]. Efficient for round objects. */
+    readonly Sphere: "Sphere";
+    /** A box shape is described by the `dimensions` as [width, height, depth]. Good for rectangular objects. */
+    readonly Box: "Box";
+    /** A cylinder shape is defined by the radius in dimensions[0] and height in dimensions[1]. */
+    readonly Cylinder: "Cylinder";
+    /** Capsules are similar to cylinders, but have two half-spheres on each end.
+     * A Capsules shape is defined by the radius in dimensions[0] and height in dimensions[1]. */
+    readonly Capsules: "Capsules";
+    /** A convex is a shape that, if two points are part of the shape, then the segment between these two points is
+     * also part of the shape. The physics engine would creates a convex wrapper around the mesh. This is a great
+     * approximation for most objects since it's more accurate than primitives and much more efficient than TriMesh. */
+    readonly ConvexHull: "ConvexHull";
+    /** Uses exact mesh geometry in the physics engine. This will give the closest match to your render geometry but
+     * may cause expensive compute load when two complex mesh shapes collide with each other. Typically used for static objects. */
+    readonly TriMesh: "TriMesh";
+    /** Automatically detects the best shape from the entity's Three.js geometry. The shape type mapping is
+     * SphereGeometry -> PhysicsShapeType.Sphere,
+     * BoxGeometry | PlaneGeometry -> PhysicsShapeType.Box,
+     * CylinderGeometry -> PhysicsShapeType.Cylinder,
+     * default -> PhysicsShapeType.ConvexHull,
+     * When this type is selected, the dimensions field in PhysicsShape will be overridden by the size of the Three.js geometry.
+     */
+    readonly Auto: "Auto";
+};
+export declare const DEFAULT_DENSITY = 1;
+export declare const DEFAULT_RESTITUTION = 0;
+export declare const DEFAULT_FRICTION = 0.5;
+/**
+ * Component for defining the collision shape and material properties of a physics entity.
+ *
+ * @remarks
+ * - Material properties (density, restitution, friction) affect physics behavior.
+ * - Higher density increases mass, affecting how the object responds to forces.
+ *
+ * @example Auto‑detect shape from geometry
+ * ```ts
+ * entity.addComponent(PhysicsShape, {
+ *   shape: PhysicsShapeType.Auto
+ * })
+ * ```
+ *
+ * @example Create a bouncy sphere
+ * ```ts
+ * entity.addComponent(PhysicsShape, {
+ *   shape: PhysicsShapeType.Sphere,
+ *   dimensions: [0.5, 0, 0], // radius = 0.5
+ *   restitution: 0.8, // bouncy
+ *   friction: 0.1 // low friction
+ * })
+ * ```
+ *
+ * @example Create a heavy box
+ * ```ts
+ * entity.addComponent(PhysicsShape, {
+ *   shape: PhysicsShapeType.Box,
+ *   dimensions: [2, 1, 1], // 2x1x1 meters
+ *   density: 5.0, // high density
+ *   friction: 0.9 // high friction
+ * })
+ * ```
+ *
+ * @category Physics
+ * @see {@link PhysicsSystem}
+ * @see {@link PhysicsBody}
+ */
+export declare const PhysicsShape: import("elics").Component<{
+    /** The type of the shape defined in the Physics engine. {@link PhysicsShapeType} */
+    shape: {
+        type: Types.Enum;
+        enum: {
+            /** The sphere is described by just the radius in dimensions[0]. Efficient for round objects. */
+            readonly Sphere: "Sphere";
+            /** A box shape is described by the `dimensions` as [width, height, depth]. Good for rectangular objects. */
+            readonly Box: "Box";
+            /** A cylinder shape is defined by the radius in dimensions[0] and height in dimensions[1]. */
+            readonly Cylinder: "Cylinder";
+            /** Capsules are similar to cylinders, but have two half-spheres on each end.
+             * A Capsules shape is defined by the radius in dimensions[0] and height in dimensions[1]. */
+            readonly Capsules: "Capsules";
+            /** A convex is a shape that, if two points are part of the shape, then the segment between these two points is
+             * also part of the shape. The physics engine would creates a convex wrapper around the mesh. This is a great
+             * approximation for most objects since it's more accurate than primitives and much more efficient than TriMesh. */
+            readonly ConvexHull: "ConvexHull";
+            /** Uses exact mesh geometry in the physics engine. This will give the closest match to your render geometry but
+             * may cause expensive compute load when two complex mesh shapes collide with each other. Typically used for static objects. */
+            readonly TriMesh: "TriMesh";
+            /** Automatically detects the best shape from the entity's Three.js geometry. The shape type mapping is
+             * SphereGeometry -> PhysicsShapeType.Sphere,
+             * BoxGeometry | PlaneGeometry -> PhysicsShapeType.Box,
+             * CylinderGeometry -> PhysicsShapeType.Cylinder,
+             * default -> PhysicsShapeType.ConvexHull,
+             * When this type is selected, the dimensions field in PhysicsShape will be overridden by the size of the Three.js geometry.
+             */
+            readonly Auto: "Auto";
+        };
+        default: "Auto";
+    };
+    /** The dimension of the physics shape. The definition of it is based on the selection of {@link PhysicsShapeType}. */
+    dimensions: {
+        type: Types.Vec3;
+        default: [number, number, number];
+    };
+    /** The density of the physics shape. It is used to calculate the mass. */
+    density: {
+        type: Types.Float32;
+        default: number;
+    };
+    /** Restitution controls bounciness (0 = no bounce, 1 = perfect bounce). */
+    restitution: {
+        type: Types.Float32;
+        default: number;
+    };
+    /** Friction to define the sliding behavior on surfaces. */
+    friction: {
+        type: Types.Float32;
+        default: number;
+    };
+    _engineShape: {
+        type: Types.Float64;
+        default: number;
+    };
+}>;
+//# sourceMappingURL=physicsShape.d.ts.map

package/dist/physics/physicsShape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physicsShape.d.ts","sourceRoot":"","sources":["../../src/physics/physicsShape.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAmB,MAAM,eAAe,CAAC;AAEvD,gFAAgF;AAChF,eAAO,MAAM,gBAAgB;IAC3B,gGAAgG;;IAEhG,4GAA4G;;IAE5G,8FAA8F;;IAE9F;iGAC6F;;IAE7F;;uHAEmH;;IAEnH;mIAC+H;;IAE/H;;;;;;OAMG;;CAEK,CAAC;AAEX,eAAO,MAAM,eAAe,IAAM,CAAC;AACnC,eAAO,MAAM,mBAAmB,IAAM,CAAC;AACvC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,YAAY;IAGrB,oFAAoF;;;;YAvEtF,gGAAgG;;YAEhG,4GAA4G;;YAE5G,8FAA8F;;YAE9F;yGAC6F;;YAE7F;;+HAEmH;;YAEnH;2IAC+H;;YAE/H;;;;;;eAMG;;;;;IAuDD,sHAAsH;;;;;IAEtH,0EAA0E;;;;;IAE1E,2EAA2E;;;;;IAE3E,2DAA2D;;;;;;;;;EAK9D,CAAC"}

package/dist/physics/physicsShape.js

@@ -0,0 +1,97 @@
+import '../index.js';
+import { createComponent, Types } from 'elics';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/** Available physics shape types for {@link PhysicsShape}. @category Physics */
+const PhysicsShapeType = {
+    /** The sphere is described by just the radius in dimensions[0]. Efficient for round objects. */
+    Sphere: 'Sphere',
+    /** A box shape is described by the `dimensions` as [width, height, depth]. Good for rectangular objects. */
+    Box: 'Box',
+    /** A cylinder shape is defined by the radius in dimensions[0] and height in dimensions[1]. */
+    Cylinder: 'Cylinder',
+    /** Capsules are similar to cylinders, but have two half-spheres on each end.
+     * A Capsules shape is defined by the radius in dimensions[0] and height in dimensions[1]. */
+    Capsules: 'Capsules',
+    /** A convex is a shape that, if two points are part of the shape, then the segment between these two points is
+     * also part of the shape. The physics engine would creates a convex wrapper around the mesh. This is a great
+     * approximation for most objects since it's more accurate than primitives and much more efficient than TriMesh. */
+    ConvexHull: 'ConvexHull',
+    /** Uses exact mesh geometry in the physics engine. This will give the closest match to your render geometry but
+     * may cause expensive compute load when two complex mesh shapes collide with each other. Typically used for static objects. */
+    TriMesh: 'TriMesh',
+    /** Automatically detects the best shape from the entity's Three.js geometry. The shape type mapping is
+     * SphereGeometry -> PhysicsShapeType.Sphere,
+     * BoxGeometry | PlaneGeometry -> PhysicsShapeType.Box,
+     * CylinderGeometry -> PhysicsShapeType.Cylinder,
+     * default -> PhysicsShapeType.ConvexHull,
+     * When this type is selected, the dimensions field in PhysicsShape will be overridden by the size of the Three.js geometry.
+     */
+    Auto: 'Auto',
+};
+const DEFAULT_DENSITY = 1.0;
+const DEFAULT_RESTITUTION = 0.0;
+const DEFAULT_FRICTION = 0.5;
+/**
+ * Component for defining the collision shape and material properties of a physics entity.
+ *
+ * @remarks
+ * - Material properties (density, restitution, friction) affect physics behavior.
+ * - Higher density increases mass, affecting how the object responds to forces.
+ *
+ * @example Auto‑detect shape from geometry
+ * ```ts
+ * entity.addComponent(PhysicsShape, {
+ *   shape: PhysicsShapeType.Auto
+ * })
+ * ```
+ *
+ * @example Create a bouncy sphere
+ * ```ts
+ * entity.addComponent(PhysicsShape, {
+ *   shape: PhysicsShapeType.Sphere,
+ *   dimensions: [0.5, 0, 0], // radius = 0.5
+ *   restitution: 0.8, // bouncy
+ *   friction: 0.1 // low friction
+ * })
+ * ```
+ *
+ * @example Create a heavy box
+ * ```ts
+ * entity.addComponent(PhysicsShape, {
+ *   shape: PhysicsShapeType.Box,
+ *   dimensions: [2, 1, 1], // 2x1x1 meters
+ *   density: 5.0, // high density
+ *   friction: 0.9 // high friction
+ * })
+ * ```
+ *
+ * @category Physics
+ * @see {@link PhysicsSystem}
+ * @see {@link PhysicsBody}
+ */
+const PhysicsShape = createComponent('PhysicsShape', {
+    /** The type of the shape defined in the Physics engine. {@link PhysicsShapeType} */
+    shape: {
+        type: Types.Enum,
+        enum: PhysicsShapeType,
+        default: PhysicsShapeType.Auto,
+    },
+    /** The dimension of the physics shape. The definition of it is based on the selection of {@link PhysicsShapeType}. */
+    dimensions: { type: Types.Vec3, default: [0.0, 0.0, 0.0] },
+    /** The density of the physics shape. It is used to calculate the mass. */
+    density: { type: Types.Float32, default: 1.0 },
+    /** Restitution controls bounciness (0 = no bounce, 1 = perfect bounce). */
+    restitution: { type: Types.Float32, default: 0.0 },
+    /** Friction to define the sliding behavior on surfaces. */
+    friction: { type: Types.Float32, default: 0.5 },
+    _engineShape: { type: Types.Float64, default: 0 },
+}, 'Component to define physics shape of an entity.');
+
+export { DEFAULT_DENSITY, DEFAULT_FRICTION, DEFAULT_RESTITUTION, PhysicsShape, PhysicsShapeType };
+//# sourceMappingURL=physicsShape.js.map

package/dist/physics/physicsShape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physicsShape.js","sources":["../../src/physics/physicsShape.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;;;;;AAKG;AAIH;AACO,MAAM,gBAAgB,GAAG;;AAE9B,IAAA,MAAM,EAAE,QAAQ;;AAEhB,IAAA,GAAG,EAAE,KAAK;;AAEV,IAAA,QAAQ,EAAE,UAAU;AACpB;AAC6F;AAC7F,IAAA,QAAQ,EAAE,UAAU;AACpB;;AAEmH;AACnH,IAAA,UAAU,EAAE,YAAY;AACxB;AAC+H;AAC/H,IAAA,OAAO,EAAE,SAAS;AAClB;;;;;;AAMG;AACH,IAAA,IAAI,EAAE,MAAM;;AAGP,MAAM,eAAe,GAAG;AACxB,MAAM,mBAAmB,GAAG;AAC5B,MAAM,gBAAgB,GAAG;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCG;AACI,MAAM,YAAY,GAAG,eAAe,CACzC,cAAc,EACd;;AAEE,IAAA,KAAK,EAAE;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;AAChB,QAAA,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,gBAAgB,CAAC,IAAI;AAC/B,KAAA;;AAED,IAAA,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE;;IAE1D,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE;;IAE9C,WAAW,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE;;IAElD,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE;IAC/C,YAAY,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE;CAClD,EACD,iDAAiD;;;;"}

package/dist/physics/utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { BufferGeometry, Object3D } from '../runtime/index.js';
+export interface ShapeDetectionResult {
+    shapeType: string;
+    dimensions: [number, number, number] | null;
+}
+/**
+ * Automatically detects the best physics shape type and calculates dimensions based on the entity's Three.js geometry
+ */
+export declare function detectShapeFromGeometry(object3D: Object3D): ShapeDetectionResult;
+/**
+ * Calculates bounding box dimensions from Object3D for fallback cases
+ */
+export declare function calculateObject3DBounds(object3D: Object3D): [number, number, number];
+export declare function generateMergedGeometry(object3D: Object3D): BufferGeometry;
+//# sourceMappingURL=utils.d.ts.map

package/dist/physics/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/physics/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAOL,cAAc,EAEd,QAAQ,EAGT,MAAM,qBAAqB,CAAC;AAY7B,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,GACjB,oBAAoB,CAsEtB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,GACjB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CA+B1B;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAuBzE"}

package/dist/physics/utils.js

@@ -0,0 +1,130 @@
+import '../runtime/three.js';
+import { PhysicsShapeType } from './physicsShape.js';
+import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+import { Vector3, Quaternion, Matrix4, Mesh, SphereGeometry, BoxGeometry, PlaneGeometry, CylinderGeometry, BufferGeometry, Box3 } from 'three';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const tempVec1 = new Vector3();
+const tempVec2 = new Vector3();
+const tempQuat = new Quaternion();
+const tempMatrix = new Matrix4();
+const tempMatrix2 = new Matrix4();
+const UNIT_SCALE = new Vector3(1, 1, 1);
+/**
+ * Automatically detects the best physics shape type and calculates dimensions based on the entity's Three.js geometry
+ */
+function detectShapeFromGeometry(object3D) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const geometry = object3D instanceof Mesh
+        ? object3D.geometry
+        : generateMergedGeometry(object3D);
+    // Check for specific geometry types and calculate their dimensions
+    if (geometry instanceof SphereGeometry) {
+        const radius = (_a = geometry.parameters.radius) !== null && _a !== void 0 ? _a : 1;
+        return {
+            shapeType: PhysicsShapeType.Sphere,
+            dimensions: [radius, 0, 0], // Only radius is needed for sphere
+        };
+    }
+    if (geometry instanceof BoxGeometry) {
+        const width = (_b = geometry.parameters.width) !== null && _b !== void 0 ? _b : 1;
+        const height = (_c = geometry.parameters.height) !== null && _c !== void 0 ? _c : 1;
+        const depth = (_d = geometry.parameters.depth) !== null && _d !== void 0 ? _d : 1;
+        return {
+            shapeType: PhysicsShapeType.Box,
+            dimensions: [width, height, depth],
+        };
+    }
+    if (geometry instanceof PlaneGeometry) {
+        const width = (_e = geometry.parameters.width) !== null && _e !== void 0 ? _e : 1;
+        const height = (_f = geometry.parameters.height) !== null && _f !== void 0 ? _f : 1;
+        const thickness = 0.01; // Thin plane
+        return {
+            shapeType: PhysicsShapeType.Box,
+            dimensions: [width, height, thickness],
+        };
+    }
+    if (geometry instanceof CylinderGeometry) {
+        const radiusTop = (_g = geometry.parameters.radiusTop) !== null && _g !== void 0 ? _g : 1;
+        const radiusBottom = (_h = geometry.parameters.radiusBottom) !== null && _h !== void 0 ? _h : 1;
+        if (radiusTop !== radiusBottom) {
+            console.warn('PhysicsSystem: detected cylinder with different radiusTop and radiusBottom. Using average radius for the physics shape.');
+        }
+        const height = (_j = geometry.parameters.height) !== null && _j !== void 0 ? _j : 1;
+        const avgRadius = (radiusTop + radiusBottom) / 2;
+        return {
+            shapeType: PhysicsShapeType.Cylinder,
+            dimensions: [avgRadius, height, 0], // Approximate bounding dimensions
+        };
+    }
+    // For generic BufferGeometry, fall back to the default ConvexHull shape type for better perf
+    if (geometry instanceof BufferGeometry) {
+        console.log(`PhysicsSystem: BufferGeometry detected for object ${object3D}, using ConvexHull.`);
+        return {
+            shapeType: PhysicsShapeType.ConvexHull,
+            dimensions: null,
+        };
+    }
+    // Fallback for unknown geometry types
+    console.warn(`PhysicsSystem: Unknown geometry type for object ${object3D}, falling back to Box`);
+    return {
+        shapeType: PhysicsShapeType.Box,
+        dimensions: calculateObject3DBounds(object3D),
+    };
+}
+/**
+ * Calculates bounding box dimensions from Object3D for fallback cases
+ */
+function calculateObject3DBounds(object3D) {
+    try {
+        // Create a bounding box for the object
+        const box = new Box3().setFromObject(object3D);
+        if (!box.isEmpty()) {
+            const size = new Vector3();
+            box.getSize(size);
+            // Convert to half-extents and ensure minimum size
+            const dimensions = [
+                Math.max(size.x, 0.01),
+                Math.max(size.y, 0.01),
+                Math.max(size.z, 0.01),
+            ];
+            console.log(`PhysicsSystem: Calculated Object3D bounds: [${dimensions.join(', ')}]`);
+            return dimensions;
+        }
+        else {
+            console.warn('PhysicsSystem: Object3D bounding box is empty, using default dimensions');
+        }
+    }
+    catch (error) {
+        console.warn('PhysicsSystem: Failed to calculate Object3D bounds:', error);
+    }
+    // Final fallback if bounding box calculation fails
+    return [1, 1, 1];
+}
+function generateMergedGeometry(object3D) {
+    object3D.updateMatrixWorld(true);
+    tempMatrix.copy(object3D.matrixWorld);
+    tempMatrix.decompose(tempVec1, tempQuat, tempVec2);
+    tempMatrix.compose(tempVec1, tempQuat, UNIT_SCALE);
+    const geometries = [];
+    object3D.traverse((child) => {
+        if (child.isMesh && child.geometry) {
+            const geometry = child.geometry.clone();
+            geometry.applyMatrix4(child.matrixWorld);
+            geometries.push(geometry);
+        }
+    });
+    const mergedGeometry = mergeGeometries(geometries);
+    tempMatrix2.copy(tempMatrix).invert();
+    mergedGeometry.applyMatrix4(tempMatrix2);
+    object3D.matrixWorld.copy(tempMatrix);
+    return mergedGeometry;
+}
+
+export { calculateObject3DBounds, detectShapeFromGeometry, generateMergedGeometry };
+//# sourceMappingURL=utils.js.map

package/dist/physics/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sources":["../../src/physics/utils.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export * from './three.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC"}

package/dist/runtime/three.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export * from 'three';
+//# sourceMappingURL=three.d.ts.map

package/dist/runtime/three.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"three.d.ts","sourceRoot":"","sources":["../../src/runtime/three.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmBH,cAAc,OAAO,CAAC"}

package/dist/runtime/three.js

@@ -0,0 +1,18 @@
+import * as THREE from 'three';
+export * from 'three';
+import { computeBoundsTree, disposeBoundsTree, acceleratedRaycast, computeBatchedBoundsTree, disposeBatchedBoundsTree } from 'three-mesh-bvh';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+THREE.BufferGeometry.prototype.computeBoundsTree = computeBoundsTree;
+THREE.BufferGeometry.prototype.disposeBoundsTree = disposeBoundsTree;
+THREE.Mesh.prototype.raycast = acceleratedRaycast;
+THREE.BatchedMesh.prototype.computeBoundsTree = computeBatchedBoundsTree;
+THREE.BatchedMesh.prototype.disposeBoundsTree = disposeBatchedBoundsTree;
+THREE.BatchedMesh.prototype.raycast = acceleratedRaycast;
+// export * as Addons from 'three/examples/jsm/Addons.js';
+//# sourceMappingURL=three.js.map

package/dist/runtime/three.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"three.js","sources":["../../src/runtime/three.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAAA;;;;;AAKG;AAWH,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,iBAAiB,GAAG,iBAAiB;AACpE,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,iBAAiB,GAAG,iBAAiB;AACpE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,kBAAkB;AAEjD,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,iBAAiB,GAAG,wBAAwB;AACxE,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,iBAAiB,GAAG,wBAAwB;AACxE,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,OAAO,GAAG,kBAAkB;AAIxD"}

package/dist/scene-understanding/anchor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Types } from '../ecs/index.js';
+/**
+ * Component for anchoring entities to stable real‑world positions in AR/VR.
+ *
+ * @remarks
+ * - Anchors provide persistent, stable positioning relative to the real world.
+ * - Entities with this component are automatically managed by {@link SceneUnderstandingSystem}.
+ * - The entity's `object3D` will be attached to a world‑anchored group for stable tracking.
+ * - Requires WebXR session with 'anchor' feature enabled.
+ * - Anchors persist across tracking loss and help maintain consistent positioning.
+ * - Once attached, the entity's transform is managed relative to the anchor's reference frame.
+ * - Internal `attached` property tracks whether the entity has been processed by the system.
+ *
+ * @example Create an anchored object
+ * ```ts
+ * const marker = world.createEntity()
+ * marker.addComponent(XRAnchor) // Will be anchored to current world position
+ * ```
+ *
+ * @example Place content at a specific anchor point
+ * ```ts
+ * const hologram = world.createTransformEntity(hologramMesh)
+ * hologram.addComponent(XRAnchor)
+ * // The SceneUnderstandingSystem will anchor this at the current reference position
+ * ```
+ *
+ * @category Scene Understanding
+ * @see {@link SceneUnderstandingSystem}
+ */
+export declare const XRAnchor: import("elics").Component<{
+    attached: {
+        type: Types.Boolean;
+        default: false;
+    };
+}>;
+//# sourceMappingURL=anchor.d.ts.map

package/dist/scene-understanding/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../src/scene-understanding/anchor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAmB,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,eAAO,MAAM,QAAQ;;;;;EAMpB,CAAC"}

package/dist/scene-understanding/anchor.js

@@ -0,0 +1,45 @@
+import '@preact/signals-core';
+import '../ecs/world.js';
+import { createComponent, Types } from 'elics';
+import '../ecs/component-registry.js';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Component for anchoring entities to stable real‑world positions in AR/VR.
+ *
+ * @remarks
+ * - Anchors provide persistent, stable positioning relative to the real world.
+ * - Entities with this component are automatically managed by {@link SceneUnderstandingSystem}.
+ * - The entity's `object3D` will be attached to a world‑anchored group for stable tracking.
+ * - Requires WebXR session with 'anchor' feature enabled.
+ * - Anchors persist across tracking loss and help maintain consistent positioning.
+ * - Once attached, the entity's transform is managed relative to the anchor's reference frame.
+ * - Internal `attached` property tracks whether the entity has been processed by the system.
+ *
+ * @example Create an anchored object
+ * ```ts
+ * const marker = world.createEntity()
+ * marker.addComponent(XRAnchor) // Will be anchored to current world position
+ * ```
+ *
+ * @example Place content at a specific anchor point
+ * ```ts
+ * const hologram = world.createTransformEntity(hologramMesh)
+ * hologram.addComponent(XRAnchor)
+ * // The SceneUnderstandingSystem will anchor this at the current reference position
+ * ```
+ *
+ * @category Scene Understanding
+ * @see {@link SceneUnderstandingSystem}
+ */
+const XRAnchor = createComponent('XRAnchor', {
+    attached: { type: Types.Boolean, default: false },
+}, 'Component for anchoring objects in the scene');
+
+export { XRAnchor };
+//# sourceMappingURL=anchor.js.map

package/dist/scene-understanding/anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.js","sources":["../../src/scene-understanding/anchor.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAAA;;;;;AAKG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AAEI,MAAM,QAAQ,GAAG,eAAe,CACrC,UAAU,EACV;IACE,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE;CAClD,EACD,8CAA8C;;;;"}

package/dist/scene-understanding/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export * from './scene-understanding-system.js';
+export * from './anchor.js';
+export * from './plane.js';
+export * from './mesh.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/scene-understanding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scene-understanding/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iCAAiC,CAAC;AAChD,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}