@forgeax/engine-skinning 0.1.2

package/dist/plugin.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+/** Install skeletal binding components in a World that consumes skinned scenes. */
+export declare function skinningPlugin(): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAcrD,mFAAmF;AACnF,wBAAgB,cAAc,IAAI,MAAM,CAQvC"}

package/dist/resolve-skin-joints.d.ts

@@ -0,0 +1,10 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { type SkinError } from './errors.js';
+export declare function resolveSkinJoints(jointPaths: readonly string[], names: ReadonlyMap<string, EntityHandle>, skinEntity: EntityHandle): {
+    ok: true;
+    value: Uint32Array;
+} | {
+    ok: false;
+    error: SkinError;
+};
+//# sourceMappingURL=resolve-skin-joints.d.ts.map

package/dist/resolve-skin-joints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-skin-joints.d.ts","sourceRoot":"","sources":["../src/resolve-skin-joints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,KAAK,SAAS,EAAgC,MAAM,aAAa,CAAC;AAE3E,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EACxC,UAAU,EAAE,YAAY,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAgBpE"}

package/dist/skin.d.ts

@@ -0,0 +1,5 @@
+export declare const Skin: import("@forgeax/engine-ecs").Component<"Skin", {
+    readonly skeleton: "shared<SkeletonAsset>";
+    readonly joints: "array<entity>";
+}>;
+//# sourceMappingURL=skin.d.ts.map

package/dist/skin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin.d.ts","sourceRoot":"","sources":["../src/skin.ts"],"names":[],"mappings":"AA8DA,eAAO,MAAM,IAAI;;;EAKf,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@forgeax/engine-skinning",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Optional skin and joint binding domain.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.1.2",
+    "@forgeax/engine-plugin": "0.1.2"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "headless binding package"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "binding is validated by unit tests"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package binary gate"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/binding.unit.test.ts

@@ -0,0 +1,44 @@
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { resolveSkinJoints, Skin, SkinJointPathUnresolvedError } from '@forgeax/engine-skinning';
+import { describe, expect, it } from 'vitest';
+import { skinContribution } from '../assets/skin-decoder';
+
+describe('skinning binding contract', () => {
+  it('exposes the skin owner contribution for the shared decoder map', () => {
+    expect(skinContribution.kind.kind).toBe('skin');
+    expect(skinContribution.consumer).toBe('resolveSkinJoints');
+  });
+  it('exposes Skin as the optional binding component', () => {
+    expect(Skin.name).toBe('Skin');
+    expect(componentSchema(Skin).skeleton).toBe('shared<SkeletonAsset>');
+    expect(componentSchema(Skin).joints).toBe('array<entity>');
+  });
+
+  it('returns the canonical error and retries with only the Name map repaired', () => {
+    const jointPaths = ['Root/Arm', 'Root/Missing', 'Root/Hand'];
+    const names = new Map([
+      ['Arm', 4 as never],
+      ['Root', 5 as never],
+    ]);
+    const result = resolveSkinJoints(jointPaths, names, 7 as never);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    const expected = new SkinJointPathUnresolvedError(7, ['Root', 'Missing'], 1);
+    expect(result.error).toBeInstanceOf(SkinJointPathUnresolvedError);
+    expect(result.error.code).toBe('skin-joint-path-unresolved');
+    expect(result.error.expected).toBe(expected.expected);
+    expect(result.error.hint).toBe(expected.hint);
+    expect(result.error.detail).toEqual(expected.detail);
+
+    names.set('Missing', 6 as never);
+    names.set('Hand', 8 as never);
+    const retry = resolveSkinJoints(jointPaths, names, 7 as never);
+    expect(retry).toEqual({ ok: true, value: new Uint32Array([4, 6, 8]) });
+  });
+
+  it('returns a concrete joint payload for the render consumer', () => {
+    const result = resolveSkinJoints(['Root/Arm'], new Map([['Arm', 4 as never]]), 7 as never);
+
+    expect(result).toEqual({ ok: true, value: new Uint32Array([4]) });
+  });
+});

package/src/__tests__/errors.unit.test.ts

@@ -0,0 +1,13 @@
+import { type SkinError, SkinJointPathUnresolvedError } from '@forgeax/engine-skinning';
+import { describe, expect, it } from 'vitest';
+
+describe('skinning error boundary', () => {
+  it('keeps binding errors structured and exhaustive', () => {
+    const error: SkinError = new SkinJointPathUnresolvedError(2, ['Root', 'Arm'], 1);
+    expect(error).toBeInstanceOf(SkinJointPathUnresolvedError);
+    expect(error.code).toBe('skin-joint-path-unresolved');
+    expect(error.expected).toBe('joint entity with Name="Arm" exists in the world');
+    expect(error.detail.failedAtIndex).toBe(1);
+    expect(error.hint.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/plugin.integration.test.ts

@@ -0,0 +1,23 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Skin, skinningPlugin } from '../index';
+
+describe('skinningPlugin', () => {
+  it('installs only the optional Skin component vocabulary', async () => {
+    const world = new World();
+    const context = await createWorldContext(world, [skinningPlugin()]);
+
+    expect([...world.components.entries()].map(([name]) => name)).toEqual(['Skin']);
+    const skeleton = world.allocSharedRef('SkeletonAsset', {
+      kind: 'skeleton',
+      jointCount: 0,
+      inverseBindMatrices: new Float32Array(),
+    });
+    const entity = world.spawn({ component: Skin, data: { skeleton, joints: [] } }).unwrap();
+    expect(world.get(entity, Skin).ok).toBe(true);
+
+    world.despawn(entity).unwrap();
+    await context.fiber.dispose();
+    expect(world.components.entries()).toHaveLength(0);
+  });
+});

package/src/__tests__/skin-error-code-owner.test-d.ts

@@ -0,0 +1,91 @@
+import type { resolveSkinJoints } from '@forgeax/engine-skinning';
+import type { SkinError, SkinErrorCode, SkinExtractErrorCode } from '../errors.js';
+
+type Equal<Left, Right> =
+  (<Type>() => Type extends Left ? 1 : 2) extends <Type>() => Type extends Right ? 1 : 2
+    ? true
+    : false;
+
+type Assert<Value extends true> = Value;
+
+type ExpectedSkinErrorCodes =
+  | 'skin-joint-count-exceeded'
+  | 'skin-joint-despawned'
+  | 'skin-joint-path-unresolved'
+  | 'skin-instances-coexist-forbidden'
+  | 'skeleton-resolve-failed'
+  | 'joint-count-mismatch'
+  | 'joint-entity-dangling';
+
+type _SkinErrorCodeDerivesFromSkinError = Assert<Equal<SkinErrorCode, SkinError['code']>>;
+
+type _SkinErrorCodeHasExactMembership = Assert<Equal<SkinErrorCode, ExpectedSkinErrorCodes>>;
+
+type _SkinExtractErrorCodeIsASkinErrorCode = Assert<
+  SkinExtractErrorCode extends SkinErrorCode ? true : false
+>;
+
+type ResolveSkinJointsError = Extract<ReturnType<typeof resolveSkinJoints>, { ok: false }>['error'];
+type _ResolveSkinJointsUsesSkinErrorAuthority = Assert<Equal<ResolveSkinJointsError, SkinError>>;
+
+declare const extractCode: SkinExtractErrorCode;
+const acceptsSkinErrorCode = (code: SkinErrorCode): SkinErrorCode => code;
+acceptsSkinErrorCode(extractCode);
+
+// @ts-expect-error invalid codes must not be accepted.
+acceptsSkinErrorCode('not-a-skin-error');
+
+function narrowSkinErrorDetail(error: SkinError): void {
+  switch (error.code) {
+    case 'skin-joint-path-unresolved': {
+      const path: readonly string[] = error.detail.path;
+      void path;
+      // @ts-expect-error code-driven narrowing excludes unrelated detail fields.
+      void error.detail.jointCount;
+      break;
+    }
+    case 'joint-count-mismatch': {
+      const actual: number = error.detail.actual;
+      void actual;
+      break;
+    }
+    case 'skeleton-resolve-failed': {
+      const skeletonHandle: number = error.detail.skeletonHandle;
+      void skeletonHandle;
+      break;
+    }
+    case 'skin-joint-count-exceeded': {
+      void error.detail.max;
+      break;
+    }
+    case 'skin-joint-despawned': {
+      void error.detail.meshEntity;
+      break;
+    }
+    case 'skin-instances-coexist-forbidden': {
+      void error.detail.entity;
+      break;
+    }
+    case 'joint-entity-dangling': {
+      void error.detail.jointIndex;
+      break;
+    }
+    default: {
+      const exhaustive: never = error;
+      void exhaustive;
+    }
+  }
+}
+
+export type _SkinErrorCodeOwnerChecks = {
+  /** @internal */
+  _derived: _SkinErrorCodeDerivesFromSkinError;
+  /** @internal */
+  _membership: _SkinErrorCodeHasExactMembership;
+  /** @internal */
+  _extractSubset: _SkinExtractErrorCodeIsASkinErrorCode;
+  /** @internal */
+  _resolveAuthority: _ResolveSkinJointsUsesSkinErrorAuthority;
+  /** @internal */
+  _narrowDetail: typeof narrowSkinErrorDetail;
+};

package/src/assets/skin-decoder.ts

@@ -0,0 +1,69 @@
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  err,
+  ok,
+  type SkeletonAsset,
+  type SkinAsset,
+} from '@forgeax/engine-types';
+
+function floatArray(value: unknown): Float32Array | undefined {
+  if (value instanceof Float32Array) return value;
+  if (Array.isArray(value) && value.every((item) => typeof item === 'number')) {
+    return Float32Array.from(value);
+  }
+  return undefined;
+}
+
+export const skinContribution: AssetDecoderContribution<SkinAsset, 'skin'> = {
+  kind: { kind: 'skin' } as AssetKind<SkinAsset, 'skin'>,
+  consumer: 'resolveSkinJoints',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload;
+      if (
+        payload.kind === 'skin' &&
+        payload.skeletonGuid.length > 0 &&
+        payload.jointPaths.length > 0
+      ) {
+        return ok(payload);
+      }
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'a skin payload with a skeleton GUID and joint paths',
+        hint: 'recook the skin binding and publish its skeleton reference',
+        detail: { guid: envelope.guid, reason: 'skin owner validation failed' },
+      });
+    },
+  },
+};
+
+export const skeletonContribution: AssetDecoderContribution<SkeletonAsset, 'skeleton'> = {
+  kind: { kind: 'skeleton' } as AssetKind<SkeletonAsset, 'skeleton'>,
+  consumer: 'resolveSkinJoints',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload as unknown;
+      if (payload !== null && typeof payload === 'object') {
+        const source = payload as Record<string, unknown>;
+        const inverseBindMatrices = floatArray(source.inverseBindMatrices);
+        const jointCount = source.jointCount;
+        if (
+          source.kind === 'skeleton' &&
+          inverseBindMatrices !== undefined &&
+          Number.isSafeInteger(jointCount) &&
+          (jointCount as number) >= 0 &&
+          inverseBindMatrices.length === (jointCount as number) * 16
+        ) {
+          return ok({ kind: 'skeleton', inverseBindMatrices, jointCount: jointCount as number });
+        }
+      }
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'a skeleton payload with one inverse-bind matrix per joint',
+        hint: 'recook the skeleton and publish its complete joint data',
+        detail: { guid: envelope.guid, reason: 'skeleton owner validation failed' },
+      });
+    },
+  },
+};