ecspresso 0.13.4 → 0.14.0

package/dist/plugins/spatial/transform3D.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 3D Transform Plugin for ECSpresso
+ *
+ * Provides hierarchical 3D transform propagation following Bevy's Transform/GlobalTransform pattern.
+ * LocalTransform3D is modified by user code; WorldTransform3D is computed automatically.
+ *
+ * Rotation is stored as Euler angles (radians, XYZ intrinsic order matching Three.js defaults).
+ * Hierarchical composition converts to quaternions internally for correct rotation composition,
+ * then converts back to Euler for storage.
+ */
+import { type BasePluginOptions } from 'ecspresso';
+import type { WorldConfigFrom } from '../../type-utils';
+/**
+ * 3D local transform relative to parent (or world if no parent).
+ * This is the transform you modify directly.
+ *
+ * Rotation is in radians, using XYZ intrinsic Euler order (Three.js default).
+ */
+export interface LocalTransform3D {
+    x: number;
+    y: number;
+    z: number;
+    rx: number;
+    ry: number;
+    rz: number;
+    sx: number;
+    sy: number;
+    sz: number;
+}
+/**
+ * Computed 3D world transform (accumulated from parent chain).
+ * Read-only — managed by the transform propagation system.
+ */
+export interface WorldTransform3D {
+    x: number;
+    y: number;
+    z: number;
+    rx: number;
+    ry: number;
+    rz: number;
+    sx: number;
+    sy: number;
+    sz: number;
+}
+/**
+ * Component types provided by the 3D transform plugin.
+ * Included automatically via `.withPlugin(createTransform3DPlugin())`.
+ */
+export interface Transform3DComponentTypes {
+    localTransform3D: LocalTransform3D;
+    worldTransform3D: WorldTransform3D;
+}
+/**
+ * WorldConfig representing the 3D transform plugin's provided components.
+ * Used as the `Requires` type parameter by plugins that depend on transform3D.
+ */
+export type Transform3DWorldConfig = WorldConfigFrom<Transform3DComponentTypes>;
+/**
+ * Configuration options for the 3D transform plugin.
+ */
+export interface Transform3DPluginOptions<G extends string = 'transform3d'> extends BasePluginOptions<G> {
+}
+/**
+ * Default local 3D transform values.
+ */
+export declare const DEFAULT_LOCAL_TRANSFORM_3D: Readonly<LocalTransform3D>;
+/**
+ * Default world 3D transform values.
+ */
+export declare const DEFAULT_WORLD_TRANSFORM_3D: Readonly<WorldTransform3D>;
+/**
+ * Create a local 3D transform component with position only.
+ * Uses default rotation (0, 0, 0) and scale (1, 1, 1).
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createLocalTransform3D(10, 5, -20),
+ *   mesh: myMesh,
+ * });
+ * ```
+ */
+export declare function createLocalTransform3D(x: number, y: number, z: number): Pick<Transform3DComponentTypes, 'localTransform3D'>;
+/**
+ * Create a world 3D transform component with position only.
+ * Typically used alongside createLocalTransform3D for initial state.
+ */
+export declare function createWorldTransform3D(x: number, y: number, z: number): Pick<Transform3DComponentTypes, 'worldTransform3D'>;
+/**
+ * Options for creating a full 3D transform.
+ */
+export interface Transform3DOptions {
+    rotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    scaleX?: number;
+    scaleY?: number;
+    scaleZ?: number;
+    /** Uniform scale (overrides scaleX/scaleY/scaleZ if provided) */
+    scale?: number;
+}
+/**
+ * Create both local and world 3D transform components.
+ * World transform is initialized to match local transform.
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createTransform3D(10, 5, -20),
+ *   mesh: myMesh,
+ * });
+ *
+ * // With rotation and scale
+ * ecs.spawn({
+ *   ...createTransform3D(10, 5, -20, {
+ *     rotation: { y: Math.PI / 4 },
+ *     scale: 2,
+ *   }),
+ *   mesh: myMesh,
+ * });
+ * ```
+ */
+export declare function createTransform3D(x: number, y: number, z: number, options?: Transform3DOptions): Transform3DComponentTypes;
+/**
+ * Create a 3D transform plugin for ECSpresso.
+ *
+ * This plugin provides:
+ * - 3D transform propagation system that computes world transforms from local transforms
+ * - Parent-first traversal ensures parents are processed before children
+ * - Supports full 3D transform hierarchy (position, rotation, scale)
+ * - Rotation composed via quaternions internally for correctness
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createTransform3DPlugin())
+ *   .withComponentTypes<{ velocity: { x: number; y: number; z: number } }>()
+ *   .build();
+ *
+ * ecs.spawn({
+ *   ...createTransform3D(10, 5, -20),
+ *   velocity: { x: 1, y: 0, z: 0 },
+ * });
+ * ```
+ */
+export declare function createTransform3DPlugin<G extends string = 'transform3d'>(options?: Transform3DPluginOptions<G>): import("ecspresso").Plugin<import("ecspresso").WithComponents<import("ecspresso").EmptyConfig, Transform3DComponentTypes>, import("ecspresso").EmptyConfig, "transform3d-propagation", G, never, never>;

package/dist/plugins/spatial/transform3D.js

@@ -0,0 +1,4 @@
+var O=Object.defineProperty;var D=(j)=>j;function T(j,k){this[j]=D.bind(null,k)}var z=(j,k)=>{for(var F in k)O(j,F,{get:k[F],enumerable:!0,configurable:!0,set:T.bind(k,F)})};var u=(j,k)=>()=>(j&&(k=j(j=0)),k);var w=((j)=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(j,{get:(k,F)=>(typeof require<"u"?require:k)[F]}):j)(function(j){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+j+'" is not supported')});import{definePlugin as v}from"ecspresso";var y={x:0,y:0,z:0,rx:0,ry:0,rz:0,sx:1,sy:1,sz:1},p={x:0,y:0,z:0,rx:0,ry:0,rz:0,sx:1,sy:1,sz:1};function c(j,k,F){return{localTransform3D:{x:j,y:k,z:F,rx:0,ry:0,rz:0,sx:1,sy:1,sz:1}}}function d(j,k,F){return{worldTransform3D:{x:j,y:k,z:F,rx:0,ry:0,rz:0,sx:1,sy:1,sz:1}}}function n(j,k,F,H){let J=H?.scale??H?.scaleX??1,N=H?.scale??H?.scaleY??1,U=H?.scale??H?.scaleZ??1,K=H?.rotation?.x??0,_=H?.rotation?.y??0,$=H?.rotation?.z??0,A={x:j,y:k,z:F,rx:K,ry:_,rz:$,sx:J,sy:N,sz:U};return{localTransform3D:{...A},worldTransform3D:{...A}}}var G={x:0,y:0,z:0,w:1},g={x:0,y:0,z:0,w:1},L={x:0,y:0,z:0,w:1};function Q(j,k,F,H){let J=Math.cos(j*0.5),N=Math.sin(j*0.5),U=Math.cos(k*0.5),K=Math.sin(k*0.5),_=Math.cos(F*0.5),$=Math.sin(F*0.5);H.x=N*U*_+J*K*$,H.y=J*K*_-N*U*$,H.z=J*U*$+N*K*_,H.w=J*U*_-N*K*$}function h(j,k,F){F.x=j.w*k.x+j.x*k.w+j.y*k.z-j.z*k.y,F.y=j.w*k.y-j.x*k.z+j.y*k.w+j.z*k.x,F.z=j.w*k.z+j.x*k.y-j.y*k.x+j.z*k.w,F.w=j.w*k.w-j.x*k.x-j.y*k.y-j.z*k.z}var E={x:0,y:0,z:0},C={rx:0,ry:0,rz:0};function m(j,k,F,H){let J=2*(j.y*H-j.z*F),N=2*(j.z*k-j.x*H),U=2*(j.x*F-j.y*k);return E.x=k+j.w*J+(j.y*U-j.z*N),E.y=F+j.w*N+(j.z*J-j.x*U),E.z=H+j.w*U+(j.x*N-j.y*J),E}function b(j){let k=j.x+j.x,F=j.y+j.y,H=j.z+j.z,J=j.x*k,N=j.x*F,U=j.x*H,K=j.y*F,_=j.y*H,$=j.z*H,A=j.w*k,X=j.w*F,R=j.w*H,Z=1-(K+$),Y=N-R,P=U+X,W=1-(J+$),S=_-A,V=1-(J+K);C.ry=Math.asin(Math.max(-1,Math.min(1,P)));let B=Math.cos(C.ry);if(Math.abs(B)>0.000001)C.rx=Math.atan2(-S,V),C.rz=Math.atan2(-Y,Z);else{let I=N+R;C.rx=Math.atan2(I,W),C.rz=0}return C}function l(j){let{systemGroup:k="transform3d",priority:F=500,phase:H="postUpdate"}=j??{};return v("transform3d").withComponentTypes().withLabels().withGroups().install((J)=>{J.registerRequired("localTransform3D","worldTransform3D",(K)=>({x:K.x,y:K.y,z:K.z,rx:K.rx,ry:K.ry,rz:K.rz,sx:K.sx,sy:K.sy,sz:K.sz}));let N=[],U=new Set;J.addSystem("transform3d-propagation").setPriority(F).inPhase(H).inGroup(k).setProcess(({ecs:K})=>{f(K,N,U)})})}function f(j,k,F){let H=j.entityManager;if(!H.hasHierarchy){H.getEntitiesWithQueryInto(k,["localTransform3D","worldTransform3D"]);for(let J of k){let{localTransform3D:N,worldTransform3D:U}=J.components;if(M(N,U))j.markChanged(J.id,"worldTransform3D")}return}F.clear(),j.forEachInHierarchy((J,N)=>{F.add(J);let U=H.getComponent(J,"localTransform3D"),K=H.getComponent(J,"worldTransform3D");if(!U||!K)return;let _=N!==null?H.getComponent(N,"worldTransform3D"):null;if(_?x(_,U,K):M(U,K))j.markChanged(J,"worldTransform3D")}),H.getEntitiesWithQueryInto(k,["localTransform3D","worldTransform3D"]);for(let J of k){if(F.has(J.id))continue;let{localTransform3D:N,worldTransform3D:U}=J.components;if(M(N,U))j.markChanged(J.id,"worldTransform3D")}}function M(j,k){if(k.x===j.x&&k.y===j.y&&k.z===j.z&&k.rx===j.rx&&k.ry===j.ry&&k.rz===j.rz&&k.sx===j.sx&&k.sy===j.sy&&k.sz===j.sz)return!1;return k.x=j.x,k.y=j.y,k.z=j.z,k.rx=j.rx,k.ry=j.ry,k.rz=j.rz,k.sx=j.sx,k.sy=j.sy,k.sz=j.sz,!0}function x(j,k,F){Q(j.rx,j.ry,j.rz,G),Q(k.rx,k.ry,k.rz,g),h(G,g,L);let H=b(L),J=m(G,k.x*j.sx,k.y*j.sy,k.z*j.sz),N=j.x+J.x,U=j.y+J.y,K=j.z+J.z,_=j.sx*k.sx,$=j.sy*k.sy,A=j.sz*k.sz;if(F.x===N&&F.y===U&&F.z===K&&F.rx===H.rx&&F.ry===H.ry&&F.rz===H.rz&&F.sx===_&&F.sy===$&&F.sz===A)return!1;return F.x=N,F.y=U,F.z=K,F.rx=H.rx,F.ry=H.ry,F.rz=H.rz,F.sx=_,F.sy=$,F.sz=A,!0}export{d as createWorldTransform3D,l as createTransform3DPlugin,n as createTransform3D,c as createLocalTransform3D,p as DEFAULT_WORLD_TRANSFORM_3D,y as DEFAULT_LOCAL_TRANSFORM_3D};
+
+//# debugId=CB864A7BB0F7E5CA64756E2164756E21
+//# sourceMappingURL=transform3D.js.map

package/dist/plugins/spatial/transform3D.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/plugins/spatial/transform3D.ts"],
+  "sourcesContent": [
+    "/**\n * 3D Transform Plugin for ECSpresso\n *\n * Provides hierarchical 3D transform propagation following Bevy's Transform/GlobalTransform pattern.\n * LocalTransform3D is modified by user code; WorldTransform3D is computed automatically.\n *\n * Rotation is stored as Euler angles (radians, XYZ intrinsic order matching Three.js defaults).\n * Hierarchical composition converts to quaternions internally for correct rotation composition,\n * then converts back to Euler for storage.\n */\n\nimport { definePlugin, type BasePluginOptions } from 'ecspresso';\nimport type ECSpresso from 'ecspresso';\nimport type { WorldConfigFrom } from '../../type-utils';\n\n// ==================== Component Types ====================\n\n/**\n * 3D local transform relative to parent (or world if no parent).\n * This is the transform you modify directly.\n *\n * Rotation is in radians, using XYZ intrinsic Euler order (Three.js default).\n */\nexport interface LocalTransform3D {\n\tx: number;\n\ty: number;\n\tz: number;\n\trx: number;\n\try: number;\n\trz: number;\n\tsx: number;\n\tsy: number;\n\tsz: number;\n}\n\n/**\n * Computed 3D world transform (accumulated from parent chain).\n * Read-only — managed by the transform propagation system.\n */\nexport interface WorldTransform3D {\n\tx: number;\n\ty: number;\n\tz: number;\n\trx: number;\n\try: number;\n\trz: number;\n\tsx: number;\n\tsy: number;\n\tsz: number;\n}\n\n/**\n * Component types provided by the 3D transform plugin.\n * Included automatically via `.withPlugin(createTransform3DPlugin())`.\n */\nexport interface Transform3DComponentTypes {\n\tlocalTransform3D: LocalTransform3D;\n\tworldTransform3D: WorldTransform3D;\n}\n\n/**\n * WorldConfig representing the 3D transform plugin's provided components.\n * Used as the `Requires` type parameter by plugins that depend on transform3D.\n */\nexport type Transform3DWorldConfig = WorldConfigFrom<Transform3DComponentTypes>;\n\n// ==================== Plugin Options ====================\n\n/**\n * Configuration options for the 3D transform plugin.\n */\nexport interface Transform3DPluginOptions<G extends string = 'transform3d'> extends BasePluginOptions<G> {}\n\n// ==================== Default Values ====================\n\n/**\n * Default local 3D transform values.\n */\nexport const DEFAULT_LOCAL_TRANSFORM_3D: Readonly<LocalTransform3D> = {\n\tx: 0, y: 0, z: 0,\n\trx: 0, ry: 0, rz: 0,\n\tsx: 1, sy: 1, sz: 1,\n};\n\n/**\n * Default world 3D transform values.\n */\nexport const DEFAULT_WORLD_TRANSFORM_3D: Readonly<WorldTransform3D> = {\n\tx: 0, y: 0, z: 0,\n\trx: 0, ry: 0, rz: 0,\n\tsx: 1, sy: 1, sz: 1,\n};\n\n// ==================== Helper Functions ====================\n\n/**\n * Create a local 3D transform component with position only.\n * Uses default rotation (0, 0, 0) and scale (1, 1, 1).\n *\n * @example\n * ```typescript\n * ecs.spawn({\n *   ...createLocalTransform3D(10, 5, -20),\n *   mesh: myMesh,\n * });\n * ```\n */\nexport function createLocalTransform3D(\n\tx: number,\n\ty: number,\n\tz: number,\n): Pick<Transform3DComponentTypes, 'localTransform3D'> {\n\treturn {\n\t\tlocalTransform3D: { x, y, z, rx: 0, ry: 0, rz: 0, sx: 1, sy: 1, sz: 1 },\n\t};\n}\n\n/**\n * Create a world 3D transform component with position only.\n * Typically used alongside createLocalTransform3D for initial state.\n */\nexport function createWorldTransform3D(\n\tx: number,\n\ty: number,\n\tz: number,\n): Pick<Transform3DComponentTypes, 'worldTransform3D'> {\n\treturn {\n\t\tworldTransform3D: { x, y, z, rx: 0, ry: 0, rz: 0, sx: 1, sy: 1, sz: 1 },\n\t};\n}\n\n/**\n * Options for creating a full 3D transform.\n */\nexport interface Transform3DOptions {\n\trotation?: { x?: number; y?: number; z?: number };\n\tscaleX?: number;\n\tscaleY?: number;\n\tscaleZ?: number;\n\t/** Uniform scale (overrides scaleX/scaleY/scaleZ if provided) */\n\tscale?: number;\n}\n\n/**\n * Create both local and world 3D transform components.\n * World transform is initialized to match local transform.\n *\n * @example\n * ```typescript\n * ecs.spawn({\n *   ...createTransform3D(10, 5, -20),\n *   mesh: myMesh,\n * });\n *\n * // With rotation and scale\n * ecs.spawn({\n *   ...createTransform3D(10, 5, -20, {\n *     rotation: { y: Math.PI / 4 },\n *     scale: 2,\n *   }),\n *   mesh: myMesh,\n * });\n * ```\n */\nexport function createTransform3D(\n\tx: number,\n\ty: number,\n\tz: number,\n\toptions?: Transform3DOptions,\n): Transform3DComponentTypes {\n\tconst sx = options?.scale ?? options?.scaleX ?? 1;\n\tconst sy = options?.scale ?? options?.scaleY ?? 1;\n\tconst sz = options?.scale ?? options?.scaleZ ?? 1;\n\tconst rx = options?.rotation?.x ?? 0;\n\tconst ry = options?.rotation?.y ?? 0;\n\tconst rz = options?.rotation?.z ?? 0;\n\n\tconst transform = { x, y, z, rx, ry, rz, sx, sy, sz };\n\n\treturn {\n\t\tlocalTransform3D: { ...transform },\n\t\tworldTransform3D: { ...transform },\n\t};\n}\n\n// ==================== Quaternion Math (Internal) ====================\n// Inlined quaternion operations to avoid Three.js dependency in the transform plugin.\n// Uses XYZ intrinsic Euler order to match Three.js Object3D.rotation defaults.\n// Pre-allocated scratch arrays avoid GC pressure in the hot path.\n\n// Scratch quaternion struct to avoid allocation in hot path\ninterface Quat { x: number; y: number; z: number; w: number }\nconst qP: Quat = { x: 0, y: 0, z: 0, w: 1 }; // parent\nconst qL: Quat = { x: 0, y: 0, z: 0, w: 1 }; // local\nconst qW: Quat = { x: 0, y: 0, z: 0, w: 1 }; // world (result)\n\n/**\n * Convert Euler angles (XYZ intrinsic order) to quaternion.\n * Writes result into the `out` object.\n */\nfunction eulerToQuat(rx: number, ry: number, rz: number, out: Quat): void {\n\tconst cx = Math.cos(rx * 0.5);\n\tconst srx = Math.sin(rx * 0.5);\n\tconst cy = Math.cos(ry * 0.5);\n\tconst sy = Math.sin(ry * 0.5);\n\tconst cz = Math.cos(rz * 0.5);\n\tconst sz = Math.sin(rz * 0.5);\n\n\t// XYZ intrinsic = ZYX extrinsic\n\tout.x = srx * cy * cz + cx * sy * sz;\n\tout.y = cx * sy * cz - srx * cy * sz;\n\tout.z = cx * cy * sz + srx * sy * cz;\n\tout.w = cx * cy * cz - srx * sy * sz;\n}\n\n/**\n * Multiply two quaternions: out = a * b\n */\nfunction quatMultiply(a: Quat, b: Quat, out: Quat): void {\n\tout.x = a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y;\n\tout.y = a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x;\n\tout.z = a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w;\n\tout.w = a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z;\n}\n\n// Scratch vec3 for quatRotateVec to avoid per-call allocation\ninterface Vec3 { x: number; y: number; z: number }\nconst vecOut: Vec3 = { x: 0, y: 0, z: 0 };\n\n// Scratch euler for quatToEuler to avoid per-call allocation\ninterface Euler3 { rx: number; ry: number; rz: number }\nconst eulerOut: Euler3 = { rx: 0, ry: 0, rz: 0 };\n\n/**\n * Rotate a vector by quaternion q. Writes result into module-scoped `vecOut`.\n */\nfunction quatRotateVec(\n\tq: Quat,\n\tvx: number,\n\tvy: number,\n\tvz: number,\n): Vec3 {\n\tconst tx = 2 * (q.y * vz - q.z * vy);\n\tconst ty = 2 * (q.z * vx - q.x * vz);\n\tconst tz = 2 * (q.x * vy - q.y * vx);\n\n\tvecOut.x = vx + q.w * tx + (q.y * tz - q.z * ty);\n\tvecOut.y = vy + q.w * ty + (q.z * tx - q.x * tz);\n\tvecOut.z = vz + q.w * tz + (q.x * ty - q.y * tx);\n\treturn vecOut;\n}\n\n/**\n * Convert quaternion to Euler angles (XYZ intrinsic order).\n * Writes result into module-scoped `eulerOut`.\n */\nfunction quatToEuler(q: Quat): Euler3 {\n\tconst x2 = q.x + q.x, y2 = q.y + q.y, z2 = q.z + q.z;\n\tconst xx = q.x * x2, xy = q.x * y2, xz = q.x * z2;\n\tconst yy = q.y * y2, yz = q.y * z2, zz = q.z * z2;\n\tconst wx = q.w * x2, wy = q.w * y2, wz = q.w * z2;\n\n\tconst m11 = 1 - (yy + zz);\n\tconst m12 = xy - wz;\n\tconst m13 = xz + wy;\n\tconst m22 = 1 - (xx + zz);\n\tconst m23 = yz - wx;\n\tconst m33 = 1 - (xx + yy);\n\n\teulerOut.ry = Math.asin(Math.max(-1, Math.min(1, m13)));\n\tconst cosY = Math.cos(eulerOut.ry);\n\n\tif (Math.abs(cosY) > 1e-6) {\n\t\teulerOut.rx = Math.atan2(-m23, m33);\n\t\teulerOut.rz = Math.atan2(-m12, m11);\n\t} else {\n\t\t// Gimbal lock fallback\n\t\tconst m21 = xy + wz;\n\t\teulerOut.rx = Math.atan2(m21, m22);\n\t\teulerOut.rz = 0;\n\t}\n\treturn eulerOut;\n}\n\n// ==================== Plugin Factory ====================\n\n/**\n * Create a 3D transform plugin for ECSpresso.\n *\n * This plugin provides:\n * - 3D transform propagation system that computes world transforms from local transforms\n * - Parent-first traversal ensures parents are processed before children\n * - Supports full 3D transform hierarchy (position, rotation, scale)\n * - Rotation composed via quaternions internally for correctness\n *\n * @example\n * ```typescript\n * const ecs = ECSpresso.create()\n *   .withPlugin(createTransform3DPlugin())\n *   .withComponentTypes<{ velocity: { x: number; y: number; z: number } }>()\n *   .build();\n *\n * ecs.spawn({\n *   ...createTransform3D(10, 5, -20),\n *   velocity: { x: 1, y: 0, z: 0 },\n * });\n * ```\n */\nexport function createTransform3DPlugin<G extends string = 'transform3d'>(\n\toptions?: Transform3DPluginOptions<G>,\n) {\n\tconst {\n\t\tsystemGroup = 'transform3d',\n\t\tpriority = 500,\n\t\tphase = 'postUpdate',\n\t} = options ?? {};\n\n\treturn definePlugin('transform3d')\n\t\t.withComponentTypes<Transform3DComponentTypes>()\n\t\t.withLabels<'transform3d-propagation'>()\n\t\t.withGroups<G>()\n\t\t.install((world) => {\n\t\t\t// localTransform3D requires worldTransform3D — initialize from localTransform3D values\n\t\t\tworld.registerRequired('localTransform3D', 'worldTransform3D', (lt) => ({\n\t\t\t\tx: lt.x, y: lt.y, z: lt.z,\n\t\t\t\trx: lt.rx, ry: lt.ry, rz: lt.rz,\n\t\t\t\tsx: lt.sx, sy: lt.sy, sz: lt.sz,\n\t\t\t}));\n\n\t\t\tconst orphanBuffer: Array<import('../../types').FilteredEntity<Transform3DComponentTypes, 'localTransform3D' | 'worldTransform3D'>> = [];\n\t\t\tconst hierarchyVisited = new Set<number>();\n\n\t\t\tworld\n\t\t\t\t.addSystem('transform3d-propagation')\n\t\t\t\t.setPriority(priority)\n\t\t\t\t.inPhase(phase)\n\t\t\t\t.inGroup(systemGroup)\n\t\t\t\t.setProcess(({ ecs }) => {\n\t\t\t\t\tpropagateTransforms3D(ecs, orphanBuffer, hierarchyVisited);\n\t\t\t\t});\n\t\t});\n}\n\n// ==================== Propagation ====================\n\n/**\n * Propagate 3D transforms through the hierarchy.\n * Parent-first traversal ensures parents are computed before children.\n */\nfunction propagateTransforms3D(\n\tecs: ECSpresso<WorldConfigFrom<Transform3DComponentTypes>>,\n\torphanBuffer: Array<import('../../types').FilteredEntity<Transform3DComponentTypes, 'localTransform3D' | 'worldTransform3D'>>,\n\thierarchyVisited: Set<number>,\n): void {\n\tconst em = ecs.entityManager;\n\n\t// Fast path: no hierarchy relationships exist — all entities are flat\n\tif (!em.hasHierarchy) {\n\t\tem.getEntitiesWithQueryInto(orphanBuffer, ['localTransform3D', 'worldTransform3D']);\n\t\tfor (const entity of orphanBuffer) {\n\t\t\tconst { localTransform3D, worldTransform3D } = entity.components;\n\t\t\tif (copyTransform3D(localTransform3D, worldTransform3D)) {\n\t\t\t\tecs.markChanged(entity.id, 'worldTransform3D');\n\t\t\t}\n\t\t}\n\t\treturn;\n\t}\n\n\t// Hierarchy exists — use parent-first traversal then process remaining orphans\n\thierarchyVisited.clear();\n\n\tecs.forEachInHierarchy((entityId, parentId) => {\n\t\thierarchyVisited.add(entityId);\n\t\tconst localTransform3D = em.getComponent(entityId, 'localTransform3D');\n\t\tconst worldTransform3D = em.getComponent(entityId, 'worldTransform3D');\n\n\t\tif (!localTransform3D || !worldTransform3D) return;\n\n\t\tconst parentWorld = parentId !== null\n\t\t\t? em.getComponent(parentId, 'worldTransform3D')\n\t\t\t: null;\n\n\t\tconst changed = parentWorld\n\t\t\t? combineTransforms3D(parentWorld, localTransform3D, worldTransform3D)\n\t\t\t: copyTransform3D(localTransform3D, worldTransform3D);\n\n\t\tif (changed) ecs.markChanged(entityId, 'worldTransform3D');\n\t});\n\n\tem.getEntitiesWithQueryInto(orphanBuffer, ['localTransform3D', 'worldTransform3D']);\n\tfor (const entity of orphanBuffer) {\n\t\tif (hierarchyVisited.has(entity.id)) continue;\n\t\tconst { localTransform3D, worldTransform3D } = entity.components;\n\t\tif (copyTransform3D(localTransform3D, worldTransform3D)) {\n\t\t\tecs.markChanged(entity.id, 'worldTransform3D');\n\t\t}\n\t}\n}\n\n/**\n * Copy 3D transform values from source to destination.\n * Returns true if the destination was actually modified.\n */\nfunction copyTransform3D(src: LocalTransform3D, dest: WorldTransform3D): boolean {\n\tif (\n\t\tdest.x === src.x && dest.y === src.y && dest.z === src.z &&\n\t\tdest.rx === src.rx && dest.ry === src.ry && dest.rz === src.rz &&\n\t\tdest.sx === src.sx && dest.sy === src.sy && dest.sz === src.sz\n\t) {\n\t\treturn false;\n\t}\n\tdest.x = src.x;\n\tdest.y = src.y;\n\tdest.z = src.z;\n\tdest.rx = src.rx;\n\tdest.ry = src.ry;\n\tdest.rz = src.rz;\n\tdest.sx = src.sx;\n\tdest.sy = src.sy;\n\tdest.sz = src.sz;\n\treturn true;\n}\n\n/**\n * Combine parent world transform with child local transform into child world transform.\n * Uses quaternion math internally for correct rotation composition.\n * Returns true if the destination was actually modified.\n */\nfunction combineTransforms3D(\n\tparent: WorldTransform3D,\n\tlocal: LocalTransform3D,\n\tworld: WorldTransform3D,\n): boolean {\n\t// Convert parent and local rotations to quaternions\n\teulerToQuat(parent.rx, parent.ry, parent.rz, qP);\n\teulerToQuat(local.rx, local.ry, local.rz, qL);\n\n\t// Compose rotations: worldQuat = parentQuat * localQuat\n\tquatMultiply(qP, qL, qW);\n\n\t// Convert back to Euler (writes into eulerOut scratch)\n\tconst euler = quatToEuler(qW);\n\n\t// Apply parent scale to local position, rotate by parent rotation (writes into vecOut scratch)\n\tconst rotated = quatRotateVec(qP, local.x * parent.sx, local.y * parent.sy, local.z * parent.sz);\n\n\t// Compute final world values\n\tconst newX = parent.x + rotated.x;\n\tconst newY = parent.y + rotated.y;\n\tconst newZ = parent.z + rotated.z;\n\tconst newSx = parent.sx * local.sx;\n\tconst newSy = parent.sy * local.sy;\n\tconst newSz = parent.sz * local.sz;\n\n\tif (\n\t\tworld.x === newX && world.y === newY && world.z === newZ &&\n\t\tworld.rx === euler.rx && world.ry === euler.ry && world.rz === euler.rz &&\n\t\tworld.sx === newSx && world.sy === newSy && world.sz === newSz\n\t) {\n\t\treturn false;\n\t}\n\n\tworld.x = newX;\n\tworld.y = newY;\n\tworld.z = newZ;\n\tworld.rx = euler.rx;\n\tworld.ry = euler.ry;\n\tworld.rz = euler.rz;\n\tworld.sx = newSx;\n\tworld.sy = newSy;\n\tworld.sz = newSz;\n\treturn true;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "CB864A7BB0F7E5CA64756E2164756E21",
+  "names": []
+}

package/dist/utils/math.d.ts

@@ -1,5 +1,5 @@
 /**
- * Shared 2D vector math utilities for ECSpresso bundles.
+ * Shared vector math utilities for ECSpresso bundles.
  * All functions are pure — they return new vectors, never mutate inputs.
  */
 /**
@@ -65,3 +65,67 @@ export declare function vec2Distance(a: Vector2D, b: Vector2D): number;
  * Check if two vectors are approximately equal within an epsilon tolerance.
  */
 export declare function vec2Equals(a: Vector2D, b: Vector2D, epsilon?: number): boolean;
+/**
+ * A 3D vector with x, y, and z components.
+ */
+export interface Vector3D {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Create a Vector3D from x, y, and z components.
+ */
+export declare function vec3(x: number, y: number, z: number): Vector3D;
+/**
+ * Return a zero vector {x: 0, y: 0, z: 0}.
+ */
+export declare function vec3Zero(): Vector3D;
+/**
+ * Add two vectors component-wise.
+ */
+export declare function vec3Add(a: Vector3D, b: Vector3D): Vector3D;
+/**
+ * Subtract b from a component-wise.
+ */
+export declare function vec3Sub(a: Vector3D, b: Vector3D): Vector3D;
+/**
+ * Scale a vector by a scalar.
+ */
+export declare function vec3Scale(v: Vector3D, scalar: number): Vector3D;
+/**
+ * Negate a vector (flip all components).
+ */
+export declare function vec3Negate(v: Vector3D): Vector3D;
+/**
+ * Compute the dot product of two vectors.
+ */
+export declare function vec3Dot(a: Vector3D, b: Vector3D): number;
+/**
+ * Compute the cross product of two vectors.
+ */
+export declare function vec3Cross(a: Vector3D, b: Vector3D): Vector3D;
+/**
+ * Compute the squared length of a vector. Avoids sqrt when only comparing magnitudes.
+ */
+export declare function vec3LengthSq(v: Vector3D): number;
+/**
+ * Compute the length (magnitude) of a vector.
+ */
+export declare function vec3Length(v: Vector3D): number;
+/**
+ * Return a unit vector in the same direction. Returns zero vector if input is zero-length.
+ */
+export declare function vec3Normalize(v: Vector3D): Vector3D;
+/**
+ * Compute the squared distance between two points. Avoids sqrt when only comparing.
+ */
+export declare function vec3DistanceSq(a: Vector3D, b: Vector3D): number;
+/**
+ * Compute the distance between two points.
+ */
+export declare function vec3Distance(a: Vector3D, b: Vector3D): number;
+/**
+ * Check if two vectors are approximately equal within an epsilon tolerance.
+ */
+export declare function vec3Equals(a: Vector3D, b: Vector3D, epsilon?: number): boolean;

package/dist/utils/narrowphase3D.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared Narrowphase Module — 3D
+ *
+ * Provides contact-computing narrowphase tests and a generic collision
+ * iteration pipeline for 3D collider pairs (AABB3D + Sphere).
+ *
+ * Mirrors the 2D narrowphase (`narrowphase.ts`) with an added Z axis.
+ */
+import type { SpatialIndex3D } from './spatial-hash3D';
+/**
+ * Contact result from a 3D narrowphase test. Normal points from A toward B.
+ *
+ * Narrowphase functions use this as an out-parameter: the caller owns the
+ * struct, the function writes fields in place and returns `true` on hit.
+ * The `onContact` callback in `detectCollisions3D` receives a shared module-
+ * level instance — **subscribers must consume it synchronously and must not
+ * retain the reference across frames**.
+ */
+export interface Contact3D {
+    normalX: number;
+    normalY: number;
+    normalZ: number;
+    /** Penetration depth (positive = overlapping) */
+    depth: number;
+}
+/** Collider shape discriminator for the flattened BaseColliderInfo3D layout. */
+export declare const AABB3D_SHAPE = 0;
+export declare const SPHERE_SHAPE = 1;
+export type ColliderShape3D = typeof AABB3D_SHAPE | typeof SPHERE_SHAPE;
+/**
+ * Minimum collider data shared by 3D collision and physics bundles.
+ *
+ * Flat layout (no nested sub-objects): the `shape` discriminator tells you
+ * whether to read `halfWidth`/`halfHeight`/`halfDepth` (AABB3D) or `radius`
+ * (Sphere). Unused fields are set to 0.
+ *
+ * Pool-friendly — all fields are assigned in place each frame.
+ */
+export interface BaseColliderInfo3D<L extends string = string> {
+    entityId: number;
+    x: number;
+    y: number;
+    z: number;
+    layer: L;
+    collidesWith: readonly L[];
+    shape: ColliderShape3D;
+    halfWidth: number;
+    halfHeight: number;
+    halfDepth: number;
+    radius: number;
+}
+/**
+ * Populate a `BaseColliderInfo3D` slot in place from raw component data.
+ * Returns `true` if the slot was filled, `false` if the entity has no
+ * collider (caller should skip it).
+ *
+ * If an entity has both AABB3D and sphere colliders, AABB3D wins and only
+ * the AABB3D offset is applied.
+ */
+export declare function fillBaseColliderInfo3D<L extends string>(info: BaseColliderInfo3D<L>, entityId: number, x: number, y: number, z: number, layer: L, collidesWith: readonly L[], aabb3D: {
+    width: number;
+    height: number;
+    depth: number;
+    offsetX?: number;
+    offsetY?: number;
+    offsetZ?: number;
+} | undefined, sphere: {
+    radius: number;
+    offsetX?: number;
+    offsetY?: number;
+    offsetZ?: number;
+} | undefined): boolean;
+/**
+ * Retrieve the optional spatialIndex3D resource, returning undefined when absent.
+ * Centralizes the cross-plugin typed lookup so individual plugins don't each
+ * need to import SpatialIndex3D or repeat the tryGetResource pattern.
+ */
+export declare function tryGetSpatialIndex3D(tryGetResource: <T>(key: string) => T | undefined): SpatialIndex3D | undefined;
+/**
+ * Write an AABB3D-vs-AABB3D contact into `out`. Returns `true` if the
+ * shapes overlap (out was filled), `false` otherwise.
+ *
+ * Resolves along the axis with minimum penetration depth.
+ */
+export declare function computeAABB3DvsAABB3D(ax: number, ay: number, az: number, ahw: number, ahh: number, ahd: number, bx: number, by: number, bz: number, bhw: number, bhh: number, bhd: number, out: Contact3D): boolean;
+/**
+ * Write a sphere-vs-sphere contact into `out`. Returns `true` if the
+ * spheres overlap.
+ */
+export declare function computeSphereVsSphere(ax: number, ay: number, az: number, ar: number, bx: number, by: number, bz: number, br: number, out: Contact3D): boolean;
+/**
+ * Write an AABB3D-vs-sphere contact into `out`. Returns `true` if the
+ * shapes overlap.
+ *
+ * Uses closest-point-on-AABB to sphere center. When the sphere center
+ * is inside the AABB, resolves along the axis with minimum push distance.
+ */
+export declare function computeAABB3DvsSphere(aabbX: number, aabbY: number, aabbZ: number, ahw: number, ahh: number, ahd: number, sphereX: number, sphereY: number, sphereZ: number, radius: number, out: Contact3D): boolean;
+/**
+ * Dispatch to the correct narrowphase function for the given pair and
+ * write the contact into `out`. Returns `true` if the pair overlaps.
+ */
+export declare function computeContact3D(a: BaseColliderInfo3D, b: BaseColliderInfo3D, out: Contact3D): boolean;
+/**
+ * Generic 3D collision detection pipeline: brute-force or broadphase,
+ * with layer filtering and contact computation.
+ *
+ * `count` is the number of live entries at the front of `colliders`.
+ * The array itself may be a grow-only pool — only indices `[0, count)`
+ * are iterated, so trailing pool slots are ignored.
+ *
+ * `workingMap` is a caller-owned `Map<number, I>` used by the broadphase
+ * path as an entityId → collider lookup. It is cleared and repopulated on
+ * each call; callers should allocate it once and pass the same instance
+ * every frame.
+ *
+ * Uses a context parameter forwarded to the callback to avoid
+ * per-frame closure allocation.
+ */
+export declare function detectCollisions3D<I extends BaseColliderInfo3D, C>(colliders: I[], count: number, workingMap: Map<number, I>, spatialIndex: SpatialIndex3D | undefined, onContact: (a: I, b: I, contact: Contact3D, context: C) => void, context: C): void;

package/dist/utils/spatial-hash3D.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Spatial Hash Grid 3D
+ *
+ * Uniform-grid spatial hash for broadphase collision detection and
+ * proximity queries in 3D. Pure data structure, no ECS dependencies.
+ */
+export interface SpatialEntry3D {
+    entityId: number;
+    x: number;
+    y: number;
+    z: number;
+    halfW: number;
+    halfH: number;
+    halfD: number;
+}
+export interface SpatialHashGrid3D {
+    cellSize: number;
+    invCellSize: number;
+    cells: Map<number, number[]>;
+    entries: Map<number, SpatialEntry3D>;
+    /** Previous-frame entries held for in-place reuse during rebuild. Internal. */
+    _entriesPrev: Map<number, SpatialEntry3D>;
+}
+/**
+ * Hash a cell coordinate triple to a single integer key.
+ * Uses large-prime XOR to distribute values.
+ */
+export declare function hashCell3D(cx: number, cy: number, cz: number): number;
+/**
+ * Create a new empty 3D spatial hash grid.
+ */
+export declare function createGrid3D(cellSize: number): SpatialHashGrid3D;
+/**
+ * Prepare the grid for a rebuild.
+ *
+ * Swaps `entries` with `_entriesPrev` so `insertEntity3D` can reuse existing
+ * `SpatialEntry3D` objects in place (steady-state rebuilds allocate zero
+ * entries). Any stale entries left in `_entriesPrev` from the previous
+ * rebuild are dropped here.
+ *
+ * Cell buckets are cleared in place — keys are retained so subsequent
+ * inserts hit the existing array rather than allocating a fresh one.
+ */
+export declare function clearGrid3D(grid: SpatialHashGrid3D): void;
+/**
+ * Insert an entity into all overlapping cells of the grid.
+ */
+export declare function insertEntity3D(grid: SpatialHashGrid3D, entityId: number, x: number, y: number, z: number, halfW: number, halfH: number, halfD: number): void;
+/**
+ * Collect entity IDs from all cells overlapping the given 3D box.
+ */
+export declare function gridQueryBox3D(grid: SpatialHashGrid3D, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, result: Set<number>): void;
+/**
+ * Collect entity IDs within a sphere. Uses box broadphase then
+ * 3D AABB-to-point distance filter.
+ */
+export declare function gridQueryRadius3D(grid: SpatialHashGrid3D, cx: number, cy: number, cz: number, radius: number, result: Set<number>): void;
+/**
+ * High-level spatial index API for 3D broadphase queries.
+ *
+ * Defined here (the utility layer) so that narrowphase3D can accept it
+ * without importing the ECS plugin. The spatial-index3D plugin creates
+ * an object that implements this interface and registers it as a resource.
+ */
+export interface SpatialIndex3D {
+    readonly grid: SpatialHashGrid3D;
+    queryBox(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number[];
+    queryBoxInto(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, result: Set<number>): void;
+    queryRadius(cx: number, cy: number, cz: number, radius: number): number[];
+    queryRadiusInto(cx: number, cy: number, cz: number, radius: number, result: Set<number>): void;
+    getEntry(entityId: number): SpatialEntry3D | undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ecspresso",
-	"version": "0.13.4",
+	"version": "0.14.0",
 	"main": "dist/index.js",
 	"module": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -24,6 +24,14 @@
 			"import": "./dist/plugins/spatial/camera.js",
 			"types": "./dist/plugins/spatial/camera.d.ts"
 		},
+		"./plugins/spatial/camera3D": {
+			"import": "./dist/plugins/spatial/camera3D.js",
+			"types": "./dist/plugins/spatial/camera3D.d.ts"
+		},
+		"./plugins/spatial/transform3D": {
+			"import": "./dist/plugins/spatial/transform3D.js",
+			"types": "./dist/plugins/spatial/transform3D.d.ts"
+		},
 		"./plugins/isometric/projection": {
 			"import": "./dist/plugins/isometric/projection.js",
 			"types": "./dist/plugins/isometric/projection.d.ts"
@@ -36,6 +44,10 @@
 			"import": "./dist/plugins/spatial/spatial-index.js",
 			"types": "./dist/plugins/spatial/spatial-index.d.ts"
 		},
+		"./plugins/spatial/spatial-index3D": {
+			"import": "./dist/plugins/spatial/spatial-index3D.js",
+			"types": "./dist/plugins/spatial/spatial-index3D.d.ts"
+		},
 		"./plugins/physics/physics2D": {
 			"import": "./dist/plugins/physics/physics2D.js",
 			"types": "./dist/plugins/physics/physics2D.d.ts"
@@ -44,6 +56,14 @@
 			"import": "./dist/plugins/physics/collision.js",
 			"types": "./dist/plugins/physics/collision.d.ts"
 		},
+		"./plugins/physics/collision3D": {
+			"import": "./dist/plugins/physics/collision3D.js",
+			"types": "./dist/plugins/physics/collision3D.d.ts"
+		},
+		"./plugins/physics/physics3D": {
+			"import": "./dist/plugins/physics/physics3D.js",
+			"types": "./dist/plugins/physics/physics3D.d.ts"
+		},
 		"./plugins/physics/steering": {
 			"import": "./dist/plugins/physics/steering.js",
 			"types": "./dist/plugins/physics/steering.d.ts"
@@ -52,6 +72,10 @@
 			"import": "./dist/plugins/rendering/renderer2D.js",
 			"types": "./dist/plugins/rendering/renderer2D.d.ts"
 		},
+		"./plugins/rendering/renderer3D": {
+			"import": "./dist/plugins/rendering/renderer3D.js",
+			"types": "./dist/plugins/rendering/renderer3D.d.ts"
+		},
 		"./plugins/rendering/particles": {
 			"import": "./dist/plugins/rendering/particles.js",
 			"types": "./dist/plugins/rendering/particles.d.ts"
@@ -100,6 +124,10 @@
 			"import": "./dist/plugins/ai/flocking.js",
 			"types": "./dist/plugins/ai/flocking.d.ts"
 		},
+		"./plugins/ai/behavior-tree": {
+			"import": "./dist/plugins/ai/behavior-tree.js",
+			"types": "./dist/plugins/ai/behavior-tree.d.ts"
+		},
 		"./plugins/combat/health": {
 			"import": "./dist/plugins/combat/health.js",
 			"types": "./dist/plugins/combat/health.d.ts"