@haiyue/extensions 0.1.0

package/src/spine/SpineAnimationBoneTimelines.ts

@@ -0,0 +1,30 @@
+import type {
+  SpineAnimationBoneTimelines,
+  SpineAnimationData,
+} from './SpineSkeletonRuntime';
+
+interface SpineAnimationBoneTimelineEntry {
+  boneName: string;
+  timelines: SpineAnimationBoneTimelines;
+}
+
+const cache = new WeakMap<object, SpineAnimationBoneTimelineEntry[]>();
+const EMPTY: SpineAnimationBoneTimelineEntry[] = [];
+
+export function compileAnimationBoneTimelines(animations: Record<string, SpineAnimationData>): void {
+  for (const animation of Object.values(animations)) getAnimationBoneTimelines(animation);
+}
+
+export function getAnimationBoneTimelines(
+  animation: SpineAnimationData | undefined,
+): SpineAnimationBoneTimelineEntry[] {
+  if (!animation || typeof animation !== 'object') return EMPTY;
+  const cached = cache.get(animation);
+  if (cached) return cached;
+  const entries: SpineAnimationBoneTimelineEntry[] = [];
+  for (const [boneName, timelines] of Object.entries(animation.bones ?? {})) {
+    entries.push({ boneName, timelines });
+  }
+  cache.set(animation, entries);
+  return entries;
+}

package/src/spine/SpineAssetParser.ts

@@ -0,0 +1,20 @@
+import { parseAtlas, type AtlasRegion } from './SpineAtlasParser';
+import { normalizeSpineData } from './SpineSkeletonRuntime';
+
+export interface SpineAssetParserInput { json: unknown; atlasText: string; }
+/** Structured-clone-safe parser boundary; the runtime validates and narrows this payload before use. */
+export interface SpineParsedAsset { data: unknown; regions: Array<[string, AtlasRegion]>; }
+
+export const SPINE_ASSET_PARSER = Object.freeze({
+  type: 'skeleton/spine',
+  parse(input: SpineAssetParserInput, _context?: { signal?: AbortSignal; source?: string }): SpineParsedAsset {
+    return {
+      data: normalizeSpineData(input.json),
+      regions: [...parseAtlas(input.atlasText).entries()],
+    };
+  },
+});
+
+export function parseSpineAssetPayload(input: SpineAssetParserInput): SpineParsedAsset {
+  return SPINE_ASSET_PARSER.parse(input, { source: 'spine' });
+}

package/src/spine/SpineAssetWorkerClient.ts

@@ -0,0 +1,112 @@
+import { WorkerChannel, type WorkerChannelLike } from '@haiyue/engine/experimental/async';
+import type { SpineParsedAsset } from './SpineAssetParser';
+import type { SpineAssetWorker } from './SpineAssetWorkerContract';
+
+type SpineWorkerLike = WorkerChannelLike;
+
+export class SpineAssetWorkerClient implements SpineAssetWorker {
+  private readonly channel: WorkerChannel;
+
+  constructor(worker: SpineWorkerLike, private readonly objectUrl: string | null = null) {
+    this.channel = new WorkerChannel(worker, {
+      label: 'Spine asset worker',
+      path: 'spine.worker',
+      context: { resourceType: 'skeleton/spine' },
+    });
+  }
+
+  loadParsedAsset(jsonUrl: string, atlasUrl: string, options: { signal?: AbortSignal } = {}): Promise<SpineParsedAsset> {
+    return this.channel.request('loadParsedSpineAsset', { jsonUrl, atlasUrl }, {
+      ...(options.signal ? { signal: options.signal } : {}),
+      context: { url: jsonUrl },
+      abortMessage: 'Spine load aborted.',
+      validate: isSpineParsedAsset,
+    });
+  }
+
+  dispose(options: { terminate?: boolean } = {}): void {
+    const alreadyDisposed = this.channel.isDisposed;
+    this.channel.dispose(options);
+    if (!alreadyDisposed && this.objectUrl) URL.revokeObjectURL(this.objectUrl);
+  }
+}
+
+function isSpineParsedAsset(value: unknown): value is SpineParsedAsset {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as { data?: unknown; regions?: unknown };
+  const data = candidate.data as { bones?: unknown } | null | undefined;
+  return !!data && typeof data === 'object'
+    && Array.isArray(data.bones)
+    && Array.isArray(candidate.regions);
+}
+
+
+export function createSpineAssetWorkerSource(extensionSpineModuleUrl: string): string {
+  return `
+const parserModulePromise = import(${JSON.stringify(extensionSpineModuleUrl)});
+const requests = new Map();
+const assetError = (message, code, path, recovery, context, cause) => Object.assign(new Error(message), {
+  domain: 'component', code, path, recovery, recoverable: recovery === 'retry', context, cause,
+});
+self.addEventListener('message', async event => {
+  const request = event.data;
+  if (!request || request.version !== 1 || typeof request.id !== 'number') return;
+  if (request.type === 'cancel') { requests.get(request.id)?.abort('cancelled'); requests.delete(request.id); return; }
+  if (request.type !== 'loadParsedSpineAsset') return;
+  const controller = new AbortController();
+  requests.set(request.id, controller);
+  try {
+    const [parser, jsonResponse, atlasResponse] = await Promise.all([
+      parserModulePromise,
+      fetch(request.jsonUrl, { signal: controller.signal }),
+      request.atlasUrl ? fetch(request.atlasUrl, { signal: controller.signal }) : Promise.resolve(null),
+    ]);
+    if (!jsonResponse.ok) throw assetError(
+      'Failed to load Spine JSON: ' + jsonResponse.status + ' ' + jsonResponse.statusText,
+      'E_ASSET_LOAD_FAILED', 'spine.json', 'retry',
+      { url: request.jsonUrl, resourceType: 'skeleton/spine-json', status: jsonResponse.status },
+    );
+    if (atlasResponse && !atlasResponse.ok) throw assetError(
+      'Failed to load Spine atlas: ' + atlasResponse.status + ' ' + atlasResponse.statusText,
+      'E_ASSET_LOAD_FAILED', 'spine.atlas', 'retry',
+      { url: request.atlasUrl, resourceType: 'skeleton/spine-atlas', status: atlasResponse.status },
+    );
+    let json;
+    try { json = await jsonResponse.json(); }
+    catch (cause) {
+      throw assetError(
+        'Spine JSON is not valid JSON.', 'E_ASSET_INVALID_DATA', 'spine.json', 'release-resource',
+        { url: request.jsonUrl, resourceType: 'skeleton/spine-json' }, cause,
+      );
+    }
+    const value = parser.parseSpineAssetPayload({
+      json,
+      atlasText: atlasResponse ? await atlasResponse.text() : '',
+    });
+    self.postMessage({ version: 1, id: request.id, ok: true, value });
+  } catch (error) {
+    if (controller.signal.aborted) return;
+    const serialized = error && typeof error.toJSON === 'function' ? error.toJSON() : {
+      name: 'EngineError', domain: error && error.domain || 'asset', code: error && error.code || 'E_ASSET_INVALID_DATA',
+      message: error instanceof Error ? error.message : String(error),
+      recovery: error && error.recovery || 'release-resource',
+      recoverable: error && typeof error.recoverable === 'boolean' ? error.recoverable : false,
+      context: Object.assign({ url: request.jsonUrl, resourceType: 'skeleton/spine' }, error && error.context || {}),
+      path: error && error.path || 'spine.parse',
+      cause: error instanceof Error ? { name: error.name, message: error.message, stack: error.stack } : undefined,
+    };
+    self.postMessage({ version: 1, id: request.id, ok: false, error: serialized });
+  } finally { requests.delete(request.id); }
+});
+`.trim();
+}
+
+export function createInlineSpineAssetWorkerClient(extensionSpineModuleUrl: string, options?: WorkerOptions): SpineAssetWorkerClient {
+  const blob = new Blob([createSpineAssetWorkerSource(extensionSpineModuleUrl)], { type: 'text/javascript' });
+  const url = URL.createObjectURL(blob);
+  return new SpineAssetWorkerClient(new Worker(url, { type: 'module', ...options }), url);
+}
+
+export function createSpineAssetWorkerClientFromUrl(url: string | URL, options?: WorkerOptions): SpineAssetWorkerClient {
+  return new SpineAssetWorkerClient(new Worker(url, options));
+}

package/src/spine/SpineAssetWorkerContract.ts

@@ -0,0 +1,4 @@
+/** Stable structural seam for optional Spine parsing offload. */
+export interface SpineAssetWorker {
+  loadParsedAsset(jsonUrl: string, atlasUrl: string, options?: { signal?: AbortSignal }): Promise<unknown>;
+}

package/src/spine/SpineAtlasParser.ts

@@ -0,0 +1,127 @@
+import { EngineError, EngineErrorCode } from '@haiyue/engine';
+import { ErrorDomain, ErrorRecovery } from '@haiyue/engine/core';
+
+export interface AtlasRegion {
+  name: string;
+  page: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  originalWidth: number;
+  originalHeight: number;
+  offsetX: number;
+  offsetY: number;
+  rotate: number;
+}
+
+export interface ResolveAtlasPageImageOptions {
+  atlasUrl: string;
+  imageUrl: string;
+  imageUrls: Record<string, string>;
+}
+
+export function parseAtlas(text: string): Map<string, AtlasRegion> {
+  const regions = new Map<string, AtlasRegion>();
+  const lines = text.split(/\r?\n/);
+  let page = '';
+  for (let i = 0; i < lines.length; i++) {
+    const sourceLine = lines[i];
+    if (sourceLine === undefined) continue;
+    const line = sourceLine.trim();
+    if (!line) continue;
+    if (!line.includes(':')) {
+      const next = lines[i + 1]?.trim() ?? '';
+      if (next.startsWith('size:') || next.startsWith('format:') || next.startsWith('filter:') || next.startsWith('repeat:')) {
+        page = line;
+        continue;
+      }
+      const name = line;
+      const region: AtlasRegion = {
+        name,
+        page,
+        x: 0,
+        y: 0,
+        width: 1,
+        height: 1,
+        originalWidth: 0,
+        originalHeight: 0,
+        offsetX: 0,
+        offsetY: 0,
+        rotate: 0,
+      };
+      while (i + 1 < lines.length) {
+        const propertyLine = lines[i + 1];
+        if (propertyLine === undefined || !propertyLine.includes(':')) break;
+        i++;
+        const separator = propertyLine.indexOf(':');
+        const key = propertyLine.slice(0, separator).trim();
+        const raw = propertyLine.slice(separator + 1).trim();
+        const nums = raw.split(',').map(Number);
+        const numberAt = (index: number, fallback: number): number => {
+          const value = nums[index];
+          return value !== undefined && Number.isFinite(value) ? value : fallback;
+        };
+        if (key === 'rotate') region.rotate = raw === 'true' ? 90 : raw === 'false' ? 0 : Number(raw) || 0;
+        if (key === 'bounds') {
+          region.x = numberAt(0, region.x);
+          region.y = numberAt(1, region.y);
+          region.width = numberAt(2, region.width);
+          region.height = numberAt(3, region.height);
+        }
+        if (key === 'xy') {
+          region.x = numberAt(0, region.x);
+          region.y = numberAt(1, region.y);
+        }
+        if (key === 'size') {
+          region.width = numberAt(0, region.width);
+          region.height = numberAt(1, region.height);
+        }
+        if (key === 'orig') {
+          region.originalWidth = numberAt(0, region.originalWidth);
+          region.originalHeight = numberAt(1, region.originalHeight);
+        }
+        if (key === 'offsets') {
+          region.offsetX = numberAt(0, region.offsetX);
+          region.offsetY = numberAt(1, region.offsetY);
+          region.originalWidth = numberAt(2, region.originalWidth);
+          region.originalHeight = numberAt(3, region.originalHeight);
+        }
+        if (key === 'offset') {
+          region.offsetX = numberAt(0, region.offsetX);
+          region.offsetY = numberAt(1, region.offsetY);
+        }
+      }
+      if (!region.originalWidth && !region.originalHeight) {
+        region.originalWidth = region.width;
+        region.originalHeight = region.height;
+      }
+      regions.set(name, region);
+    }
+  }
+  return regions;
+}
+
+export function resolveAtlasPageImageUrl(
+  options: ResolveAtlasPageImageOptions,
+  atlas: Map<string, AtlasRegion>,
+  page: string,
+): string {
+  const mapped = options.imageUrls[page] ?? options.imageUrls[page.split('/').pop() ?? page];
+  if (mapped) return mapped;
+  if (options.imageUrl && (!page || atlasPageCount(atlas) <= 1)) return options.imageUrl;
+  if (!page) {
+    if (options.imageUrl) return options.imageUrl;
+    throw new EngineError(EngineErrorCode.AssetInvalidData, 'Spine imageUrl is required when atlas has no page.', {
+      domain: ErrorDomain.Component,
+      recovery: ErrorRecovery.ReleaseResource,
+      context: { atlasUrl: options.atlasUrl, resourceType: 'skeleton/spine-atlas' },
+      path: 'spine.atlas.pages',
+    });
+  }
+  return new URL(page, options.atlasUrl || window.location.href).href;
+}
+
+export function atlasPageCount(atlas: Map<string, AtlasRegion>): number {
+  return new Set(Array.from(atlas.values()).map(region => region.page).filter(Boolean)).size;
+}

package/src/spine/SpineFloatBuilder.ts

@@ -0,0 +1,66 @@
+export class SpineFloatBuilder {
+  data: Float32Array;
+  length = 0;
+
+  constructor(initialCapacity = 1024) {
+    this.data = new Float32Array(initialCapacity);
+  }
+
+  clear(): void {
+    this.length = 0;
+  }
+
+  get byteLength(): number {
+    return this.length * 4;
+  }
+
+  get(index: number): number {
+    return this.data[index] ?? 0;
+  }
+
+  push(...values: number[]): void {
+    this.ensureCapacity(this.length + values.length);
+    this.data.set(values, this.length);
+    this.length += values.length;
+  }
+
+  push8(a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number): void {
+    this.ensureCapacity(this.length + 8);
+    const offset = this.length;
+    this.data[offset] = a;
+    this.data[offset + 1] = b;
+    this.data[offset + 2] = c;
+    this.data[offset + 3] = d;
+    this.data[offset + 4] = e;
+    this.data[offset + 5] = f;
+    this.data[offset + 6] = g;
+    this.data[offset + 7] = h;
+    this.length += 8;
+  }
+
+  appendArray(values: ArrayLike<number>, length = values.length): void {
+    this.ensureCapacity(this.length + length);
+    for (let i = 0; i < length; i++) this.data[this.length + i] = values[i] ?? 0;
+    this.length += length;
+  }
+
+  truncate(length: number): void {
+    this.length = Math.max(0, Math.min(this.length, length));
+  }
+
+  /** Grows storage if needed and exposes a reusable writable region without allocating a temporary array. */
+  reserveLength(length: number): void {
+    const nextLength = Math.max(0, length);
+    this.ensureCapacity(nextLength);
+    this.length = nextLength;
+  }
+
+  private ensureCapacity(required: number): void {
+    if (this.data.length >= required) return;
+    let nextCapacity = Math.max(1, this.data.length);
+    while (nextCapacity < required) nextCapacity *= 2;
+    const next = new Float32Array(nextCapacity);
+    next.set(this.data.subarray(0, this.length));
+    this.data = next;
+  }
+}