@flighthq/node 0.1.0

package/src/transform2d.test.ts

@@ -0,0 +1,391 @@
+import { getEntityRuntime } from '@flighthq/entity';
+import { cloneMatrix, createMatrix, createVector2, equalsMatrix, multiplyMatrix, setMatrix } from '@flighthq/geometry';
+import { addNodeChild, createNode } from '@flighthq/node';
+import type { HasTransform2D, HasTransform2DRuntime, Matrix, Node, NodeRuntime } from '@flighthq/types';
+
+import { initTransform2DRuntimeTrait, initTransform2DTrait } from './hasTransform2d';
+import { invalidateNodeLocalTransform } from './revision';
+import {
+  convertNodeVector2GlobalToLocal,
+  convertNodeVector2LocalToGlobal,
+  ensureNodeLocalTransformMatrix,
+  ensureNodeWorldTransformMatrix,
+  getNodeLocalTransformMatrix,
+  getNodeWorldTransformMatrix,
+} from './transform2d';
+
+function createTestNode(): TestNode {
+  const node = createNode(TestKind) as TestNode;
+  const runtime = getEntityRuntime(node);
+  initTransform2DTrait(node);
+  initTransform2DRuntimeTrait(runtime as HasTransform2DRuntime);
+  return node;
+}
+
+let node: TestNode;
+beforeEach(() => {
+  node = createTestNode();
+});
+
+describe('convertNodeVector2GlobalToLocal', () => {
+  let obj: TestNode;
+
+  beforeEach(() => {
+    obj = createTestNode();
+    addNodeChild(createTestNode(), obj);
+    obj.x = 10;
+    obj.y = 20;
+    obj.scaleX = 2;
+    obj.scaleY = 2;
+    obj.rotation = 0;
+    invalidateNodeLocalTransform(obj);
+  });
+
+  it('writes into the provided output Vector2', () => {
+    const out = createVector2();
+    const world = createVector2(14, 24);
+
+    convertNodeVector2GlobalToLocal(out, obj, world);
+
+    expect(out.x).toBeCloseTo(2);
+    expect(out.y).toBeCloseTo(2);
+  });
+
+  it('reuses the output object', () => {
+    const out = createVector2(999, 999);
+    convertNodeVector2GlobalToLocal(out, obj, createVector2(10, 20));
+
+    expect(out).toEqual(expect.objectContaining({ x: 0, y: 0 }));
+  });
+
+  it('updates the world transform before conversion', () => {
+    // const spy = vi.spyOn(obj, updateWorldTransform);
+    // globalToLocal(createVector2(), obj, createVector2());
+    // expect(spy).toHaveBeenCalled();
+    // spy.mockRestore();
+  });
+
+  it('allows vector-like objects', () => {
+    const out = { x: 0, y: 0 };
+    const world = { x: 14, y: 24 };
+
+    convertNodeVector2GlobalToLocal(out, obj, world);
+
+    expect(out.x).toBeCloseTo(2);
+    expect(out.y).toBeCloseTo(2);
+  });
+});
+
+describe('convertNodeVector2LocalToGlobal', () => {
+  let obj: TestNode;
+
+  beforeEach(() => {
+    obj = createTestNode();
+  });
+
+  it('writes to out parameter', () => {
+    const local = createVector2(5, 5);
+    const out = createVector2();
+
+    convertNodeVector2LocalToGlobal(out, obj, local);
+
+    expect(out.x).toBe(5);
+    expect(out.y).toBe(5);
+    expect(out).not.toBe(local); // out is a separate object
+  });
+
+  it('respects world transform', () => {
+    obj.x = 50;
+    obj.y = 30;
+    invalidateNodeLocalTransform(obj);
+
+    const local = createVector2(10, 20);
+    const out = createVector2();
+
+    convertNodeVector2LocalToGlobal(out, obj, local);
+
+    expect(out.x).toBe(60); // 50 + 10
+    expect(out.y).toBe(50); // 30 + 20
+  });
+
+  it('produces independent results from multiple points', () => {
+    obj.x = 1;
+    obj.y = 2;
+    invalidateNodeLocalTransform(obj);
+
+    const p1 = createVector2(1, 1);
+    const p2 = createVector2(2, 2);
+
+    const g1 = createVector2();
+    convertNodeVector2LocalToGlobal(g1, obj, p1);
+    const g2 = createVector2();
+    convertNodeVector2LocalToGlobal(g2, obj, p2);
+
+    expect(g1.x).toBe(2);
+    expect(g1.y).toBe(3);
+    expect(g2.x).toBe(3);
+    expect(g2.y).toBe(4);
+  });
+
+  it('allows vector-like objects', () => {
+    const local = { x: 5, y: 5 };
+    const out = { x: 0, y: 0 };
+
+    convertNodeVector2LocalToGlobal(out, obj, local);
+
+    expect(out.x).toBe(5);
+    expect(out.y).toBe(5);
+    expect(out).not.toBe(local); // out is a separate object
+  });
+});
+
+describe('ensureNodeLocalTransformMatrix', () => {
+  it('computes local transform the first time', () => {
+    const runtime = getEntityRuntime(node) as HasTransform2DRuntime;
+    expect(runtime.localTransform2D).toBeNull();
+    ensureNodeLocalTransformMatrix(node);
+    expect(runtime.localTransform2D).not.toBeNull();
+  });
+
+  it('recomputes if the local transform ID has changed', () => {
+    const runtime = getEntityRuntime(node) as NodeRuntime<HasTransform2D> & HasTransform2DRuntime;
+    ensureNodeLocalTransformMatrix(node);
+    const cache = cloneAndInvalidateMatrix(runtime.localTransform2D);
+    runtime.localTransformId++;
+    ensureNodeLocalTransformMatrix(node);
+    expect(equalsMatrix(runtime.localTransform2D, cache)).toBe(true);
+  });
+});
+
+describe('ensureNodeWorldTransformMatrix', () => {
+  it('computes world transform the first time', () => {
+    const runtime = getEntityRuntime(node) as NodeRuntime<HasTransform2D> & HasTransform2DRuntime;
+    expect(runtime.worldTransform2D).toBeNull();
+    ensureNodeWorldTransformMatrix(node);
+    expect(runtime.worldTransform2D).not.toBeNull();
+  });
+
+  it('computes world transform for a parent for the first time', () => {
+    const parent = createTestNode();
+    addNodeChild(parent, node);
+    const parentState = getEntityRuntime(node) as HasTransform2DRuntime;
+    expect(parentState.worldTransform2D).toBeNull();
+    ensureNodeWorldTransformMatrix(node);
+    expect(parentState.worldTransform2D).not.toBeNull();
+  });
+
+  it('recomputes if the local transform ID has changed', () => {
+    const runtime = getEntityRuntime(node) as NodeRuntime<HasTransform2D> & HasTransform2DRuntime;
+    ensureNodeWorldTransformMatrix(node);
+    const cache = cloneAndInvalidateMatrix(runtime.worldTransform2D);
+    runtime.localTransformId++;
+    ensureNodeWorldTransformMatrix(node);
+    expect(equalsMatrix(runtime.worldTransform2D, cache)).toBe(true);
+  });
+
+  it('recomputes if the parent transform ID has changed', () => {
+    const parent = createTestNode();
+    addNodeChild(parent, node);
+    const runtime = getEntityRuntime(node) as HasTransform2DRuntime;
+    const parentState = getEntityRuntime(parent) as NodeRuntime<HasTransform2D> & HasTransform2DRuntime;
+    ensureNodeWorldTransformMatrix(node);
+    const cache = cloneAndInvalidateMatrix(runtime.worldTransform2D);
+    parentState.worldTransformId++;
+    ensureNodeWorldTransformMatrix(node);
+    expect(equalsMatrix(runtime.worldTransform2D, cache)).toBe(true);
+  });
+});
+
+describe('getNodeLocalTransformMatrix', () => {
+  it('ensures local transform', () => {
+    const runtime = getEntityRuntime(node) as HasTransform2DRuntime;
+    expect(runtime.localTransform2D).toBeNull();
+    getNodeLocalTransformMatrix(node);
+    expect(runtime.localTransform2D).not.toBeNull();
+  });
+
+  it('returns local transform', () => {
+    const transform = getNodeLocalTransformMatrix(node);
+    expect(transform).equals((getEntityRuntime(node) as HasTransform2DRuntime).localTransform2D);
+  });
+
+  it('offsets translation by the pivot so the pivot point lands at (x, y)', () => {
+    node.x = 100;
+    node.y = 50;
+    node.pivotX = 10;
+    node.pivotY = 20;
+    const transform = getNodeLocalTransformMatrix(node);
+    expect(transform.tx).toBeCloseTo(90); // 100 - 1 * 10
+    expect(transform.ty).toBeCloseTo(30); // 50 - 1 * 20
+  });
+
+  it('scales the pivot offset with scaleX/scaleY', () => {
+    node.scaleX = 2;
+    node.scaleY = 3;
+    node.pivotX = 10;
+    node.pivotY = 10;
+    const transform = getNodeLocalTransformMatrix(node);
+    expect(transform.tx).toBeCloseTo(-20); // 0 - 2 * 10
+    expect(transform.ty).toBeCloseTo(-30); // 0 - 3 * 10
+  });
+});
+
+describe('getNodeWorldTransformMatrix', () => {
+  it('ensures world transform', () => {
+    const runtime = getEntityRuntime(node) as HasTransform2DRuntime;
+    expect(runtime.worldTransform2D).toBeNull();
+    getNodeWorldTransformMatrix(node);
+    expect(runtime.worldTransform2D).not.toBeNull();
+  });
+
+  it('returns local transform', () => {
+    const transform = getNodeWorldTransformMatrix(node);
+    expect(transform).equals((getEntityRuntime(node) as HasTransform2DRuntime).worldTransform2D);
+  });
+});
+
+describe('skew', () => {
+  const DEG_TO_RAD = Math.PI / 180;
+
+  it('produces the same matrix with skewX=0 and skewY=0 as without skew', () => {
+    const withSkew = createTestNode();
+    withSkew.rotation = 30;
+    withSkew.scaleX = 2;
+    withSkew.scaleY = 3;
+    withSkew.skewX = 0;
+    withSkew.skewY = 0;
+    invalidateNodeLocalTransform(withSkew);
+
+    const withoutSkew = createTestNode();
+    withoutSkew.rotation = 30;
+    withoutSkew.scaleX = 2;
+    withoutSkew.scaleY = 3;
+    invalidateNodeLocalTransform(withoutSkew);
+
+    const mSkew = getNodeLocalTransformMatrix(withSkew);
+    const mNoSkew = getNodeLocalTransformMatrix(withoutSkew);
+    expect(mSkew.a).toBeCloseTo(mNoSkew.a);
+    expect(mSkew.b).toBeCloseTo(mNoSkew.b);
+    expect(mSkew.c).toBeCloseTo(mNoSkew.c);
+    expect(mSkew.d).toBeCloseTo(mNoSkew.d);
+    expect(mSkew.tx).toBeCloseTo(mNoSkew.tx);
+    expect(mSkew.ty).toBeCloseTo(mNoSkew.ty);
+  });
+
+  it('applies isolated skewX to c and d cells without affecting a and b', () => {
+    node.skewX = 45;
+    node.skewY = 0;
+    node.scaleX = 1;
+    node.scaleY = 1;
+    node.rotation = 0;
+    invalidateNodeLocalTransform(node);
+
+    const m = getNodeLocalTransformMatrix(node);
+    const radX = 45 * DEG_TO_RAD;
+    expect(m.a).toBeCloseTo(1);
+    expect(m.b).toBeCloseTo(0);
+    expect(m.c).toBeCloseTo(-Math.sin(radX));
+    expect(m.d).toBeCloseTo(Math.cos(radX));
+  });
+
+  it('applies isolated skewY to a and b cells without affecting c and d', () => {
+    node.skewX = 0;
+    node.skewY = 30;
+    node.scaleX = 1;
+    node.scaleY = 1;
+    node.rotation = 0;
+    invalidateNodeLocalTransform(node);
+
+    const m = getNodeLocalTransformMatrix(node);
+    const radY = 30 * DEG_TO_RAD;
+    expect(m.a).toBeCloseTo(Math.cos(radY));
+    expect(m.b).toBeCloseTo(Math.sin(radY));
+    expect(m.c).toBeCloseTo(0);
+    expect(m.d).toBeCloseTo(1);
+  });
+
+  it('computes all four matrix cells with combined skew and rotation', () => {
+    node.rotation = 45;
+    node.skewX = 15;
+    node.skewY = 20;
+    node.scaleX = 1;
+    node.scaleY = 1;
+    invalidateNodeLocalTransform(node);
+
+    const m = getNodeLocalTransformMatrix(node);
+    const radY = (45 + 20) * DEG_TO_RAD;
+    const radX = (45 + 15) * DEG_TO_RAD;
+    expect(m.a).toBeCloseTo(Math.cos(radY));
+    expect(m.b).toBeCloseTo(Math.sin(radY));
+    expect(m.c).toBeCloseTo(-Math.sin(radX));
+    expect(m.d).toBeCloseTo(Math.cos(radX));
+  });
+
+  it('propagates skew through world transform', () => {
+    const parent = createTestNode();
+    parent.skewX = 10;
+    parent.skewY = 20;
+    parent.scaleX = 2;
+    parent.scaleY = 1;
+    invalidateNodeLocalTransform(parent);
+
+    const child = createTestNode();
+    child.x = 50;
+    child.scaleX = 1;
+    child.scaleY = 1;
+    invalidateNodeLocalTransform(child);
+
+    addNodeChild(parent, child);
+
+    const parentLocal = getNodeLocalTransformMatrix(parent);
+    const childLocal = getNodeLocalTransformMatrix(child);
+    const expected = createMatrix();
+    multiplyMatrix(expected, parentLocal, childLocal);
+
+    const world = getNodeWorldTransformMatrix(child);
+    expect(world.a).toBeCloseTo(expected.a);
+    expect(world.b).toBeCloseTo(expected.b);
+    expect(world.c).toBeCloseTo(expected.c);
+    expect(world.d).toBeCloseTo(expected.d);
+    expect(world.tx).toBeCloseTo(expected.tx);
+    expect(world.ty).toBeCloseTo(expected.ty);
+  });
+
+  it('computes correct tx/ty when both pivot and skew are nonzero', () => {
+    node.skewX = 30;
+    node.skewY = 45;
+    node.scaleX = 2;
+    node.scaleY = 3;
+    node.pivotX = 10;
+    node.pivotY = 20;
+    node.x = 100;
+    node.y = 50;
+    node.rotation = 0;
+    invalidateNodeLocalTransform(node);
+
+    const m = getNodeLocalTransformMatrix(node);
+    const radY = 45 * DEG_TO_RAD;
+    const radX = 30 * DEG_TO_RAD;
+    const a = Math.cos(radY) * 2;
+    const b = Math.sin(radY) * 2;
+    const c = -Math.sin(radX) * 3;
+    const d = Math.cos(radX) * 3;
+    expect(m.a).toBeCloseTo(a);
+    expect(m.b).toBeCloseTo(b);
+    expect(m.c).toBeCloseTo(c);
+    expect(m.d).toBeCloseTo(d);
+    expect(m.tx).toBeCloseTo(100 - (a * 10 + c * 20));
+    expect(m.ty).toBeCloseTo(50 - (b * 10 + d * 20));
+  });
+});
+
+function cloneAndInvalidateMatrix(matrix: Matrix | null): Matrix | null {
+  if (matrix === null) return null;
+  const clone = cloneMatrix(matrix);
+  setMatrix(matrix, -1, -1, -1, -1, -1, -1);
+  return clone;
+}
+
+type TestNode = Node<HasTransform2D> & HasTransform2D;
+
+const TestKind = 'Test';

package/src/transform3d.test.ts

@@ -0,0 +1,202 @@
+import { setMatrix4Identity } from '@flighthq/geometry';
+import type { HasTransform3D, HasTransform3DRuntime, NodeRuntime, Transform3DNode, Vector3Like } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { initTransform3DRuntimeTrait, initTransform3DTrait } from './hasTransform3d';
+import { addNodeChild } from './hierarchy';
+import { createNode, getNodeRuntime } from './node';
+import { invalidateNodeLocalTransform } from './revision';
+import {
+  convertNodeVector3GlobalToLocal,
+  convertNodeVector3LocalToGlobal,
+  ensureNodeWorldTransformMatrix4,
+  getNodeWorldTransformMatrix4,
+} from './transform3d';
+
+const TestNodeKind = 'TestNode';
+
+interface TestTraits extends HasTransform3D {}
+type TestNode = Transform3DNode<TestTraits>;
+
+function createTestNode(): TestNode {
+  const node = createNode<TestTraits>(TestNodeKind);
+  initTransform3DTrait(node);
+  initTransform3DRuntimeTrait(getNodeRuntime(node) as NodeRuntime<TestTraits> & HasTransform3DRuntime);
+  return node as TestNode;
+}
+
+function vec(): Vector3Like {
+  return { x: 0, y: 0, z: 0 } as Vector3Like;
+}
+
+describe('convertNodeVector3GlobalToLocal', () => {
+  it('returns the point unchanged for an identity root node', () => {
+    const node = createTestNode();
+    const out = vec();
+    convertNodeVector3GlobalToLocal(out, node, { x: 4, y: 5, z: 6 } as Vector3Like);
+    expect(out.x).toBeCloseTo(4);
+    expect(out.y).toBeCloseTo(5);
+    expect(out.z).toBeCloseTo(6);
+  });
+
+  it('inverts the node translation', () => {
+    const node = createTestNode();
+    node.localMatrix.m[12] = 10;
+    node.localMatrix.m[13] = 20;
+    node.localMatrix.m[14] = 30;
+    invalidateNodeLocalTransform(node);
+
+    const out = vec();
+    convertNodeVector3GlobalToLocal(out, node, { x: 11, y: 21, z: 31 } as Vector3Like);
+    expect(out.x).toBeCloseTo(1);
+    expect(out.y).toBeCloseTo(1);
+    expect(out.z).toBeCloseTo(1);
+  });
+
+  it('round-trips with convertNodeVector3LocalToGlobal', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    addNodeChild(parent, child);
+
+    parent.localMatrix.m[12] = 7;
+    parent.localMatrix.m[13] = -2;
+    invalidateNodeLocalTransform(parent);
+    child.localMatrix.m[14] = 4;
+    invalidateNodeLocalTransform(child);
+
+    const local = { x: 1.5, y: 2.5, z: 3.5 } as Vector3Like;
+    const world = vec();
+    convertNodeVector3LocalToGlobal(world, child, local);
+
+    const back = vec();
+    convertNodeVector3GlobalToLocal(back, child, world);
+    expect(back.x).toBeCloseTo(local.x);
+    expect(back.y).toBeCloseTo(local.y);
+    expect(back.z).toBeCloseTo(local.z);
+  });
+});
+
+describe('convertNodeVector3LocalToGlobal', () => {
+  it('returns the point unchanged for an identity root node', () => {
+    const node = createTestNode();
+    const out = vec();
+    convertNodeVector3LocalToGlobal(out, node, { x: 1, y: 2, z: 3 } as Vector3Like);
+    expect(out.x).toBeCloseTo(1);
+    expect(out.y).toBeCloseTo(2);
+    expect(out.z).toBeCloseTo(3);
+  });
+
+  it('applies the node translation to a local point', () => {
+    const node = createTestNode();
+    node.localMatrix.m[12] = 10;
+    node.localMatrix.m[13] = 20;
+    node.localMatrix.m[14] = 30;
+    invalidateNodeLocalTransform(node);
+
+    const out = vec();
+    convertNodeVector3LocalToGlobal(out, node, { x: 1, y: 1, z: 1 } as Vector3Like);
+    expect(out.x).toBeCloseTo(11);
+    expect(out.y).toBeCloseTo(21);
+    expect(out.z).toBeCloseTo(31);
+  });
+
+  it('composes parent and child translations', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    addNodeChild(parent, child);
+
+    parent.localMatrix.m[12] = 5;
+    invalidateNodeLocalTransform(parent);
+    child.localMatrix.m[12] = 3;
+    invalidateNodeLocalTransform(child);
+
+    const out = vec();
+    convertNodeVector3LocalToGlobal(out, child, { x: 0, y: 0, z: 0 } as Vector3Like);
+    expect(out.x).toBeCloseTo(8);
+  });
+});
+
+describe('ensureNodeWorldTransformMatrix4', () => {
+  it('computes the world matrix for a root node', () => {
+    const node = createTestNode();
+    node.localMatrix.m[12] = 5;
+    invalidateNodeLocalTransform(node);
+    ensureNodeWorldTransformMatrix4(node);
+    const runtime = getNodeRuntime(node) as NodeRuntime<TestTraits> & HasTransform3DRuntime;
+    expect(runtime.worldMatrix).not.toBeNull();
+    expect(runtime.worldMatrix!.m[12]).toBeCloseTo(5);
+  });
+
+  it('reuses a cached world matrix when no invalidation has occurred', () => {
+    const node = createTestNode();
+    ensureNodeWorldTransformMatrix4(node);
+    const runtime = getNodeRuntime(node) as NodeRuntime<TestTraits> & HasTransform3DRuntime;
+    const first = runtime.worldMatrix;
+    ensureNodeWorldTransformMatrix4(node);
+    expect(runtime.worldMatrix).toBe(first);
+  });
+});
+
+describe('getNodeWorldTransformMatrix4', () => {
+  it('returns the world matrix for a node', () => {
+    const node = createTestNode();
+    node.localMatrix.m[12] = 3;
+    invalidateNodeLocalTransform(node);
+    const m = getNodeWorldTransformMatrix4(node);
+    expect(m.m[12]).toBeCloseTo(3);
+  });
+
+  it('composes parent and child local matrices', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    addNodeChild(parent, child);
+    parent.localMatrix.m[12] = 10;
+    invalidateNodeLocalTransform(parent);
+    child.localMatrix.m[12] = 5;
+    invalidateNodeLocalTransform(child);
+    const m = getNodeWorldTransformMatrix4(child);
+    expect(m.m[12]).toBeCloseTo(15);
+  });
+
+  it('world matrix is recomputed after localMatrix changes', () => {
+    const node = createTestNode();
+    invalidateNodeLocalTransform(node);
+    ensureNodeWorldTransformMatrix4(node);
+    const runtime = getNodeRuntime(node) as NodeRuntime<TestTraits> & HasTransform3DRuntime;
+    const first = runtime.worldTransformId;
+
+    node.localMatrix.m[12] = 99;
+    invalidateNodeLocalTransform(node);
+    ensureNodeWorldTransformMatrix4(node);
+    const second = runtime.worldTransformId;
+
+    expect(second).not.toBe(first);
+  });
+
+  it('world matrix is cached when nothing changes', () => {
+    const node = createTestNode();
+    ensureNodeWorldTransformMatrix4(node);
+    const runtime = getNodeRuntime(node) as NodeRuntime<TestTraits> & HasTransform3DRuntime;
+    const id1 = runtime.worldTransformId;
+    ensureNodeWorldTransformMatrix4(node);
+    const id2 = runtime.worldTransformId;
+    expect(id1).toBe(id2);
+  });
+
+  it('child world matrix updates when parent localMatrix changes', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    addNodeChild(parent, child);
+
+    setMatrix4Identity(parent.localMatrix);
+    setMatrix4Identity(child.localMatrix);
+    invalidateNodeLocalTransform(parent);
+    invalidateNodeLocalTransform(child);
+
+    parent.localMatrix.m[12] = 7;
+    invalidateNodeLocalTransform(parent);
+
+    const world = getNodeWorldTransformMatrix4(child);
+    expect(world.m[12]).toBeCloseTo(7);
+  });
+});