@series-inc/stowkit-reader 0.1.41

package/LICENSE.txt

@@ -0,0 +1,6 @@
+By downloading, copying, or using this template, you agree to the
+RUN.game Terms of Service:
+
+https://policy.run.game/eula.html
+
+© Series Inc. All rights reserved.

package/README.md

@@ -0,0 +1,330 @@
+# @series-inc/stowkit-reader
+
+WebAssembly-based reader for StowKit (.stow) asset pack files. Low-level API for reading and parsing binary asset data.
+
+## Features
+
+- 🚀 **Pure WASM** - All binary parsing done in WebAssembly (Zig)
+- 📦 **Zero Dependencies** - Just WebAssembly, no external libraries
+- 🔍 **WASM Metadata Parsing** - Parse complex structures in WASM, not JavaScript
+- 🎮 **Game-Ready** - Supports all asset types (meshes, textures, audio, animations)
+- 📝 **TypeScript Support** - Full type definitions included
+- ⚡ **Fast** - WASM parsing is 10-50x faster than JavaScript DataView
+
+## Installation
+
+```bash
+npm install @series-inc/stowkit-reader
+```
+
+## Usage
+
+```typescript
+import { StowKitReader } from '@series-inc/stowkit-reader';
+
+// Initialize the reader
+const reader = new StowKitReader();
+await reader.init();
+
+// Open a .stow file
+const response = await fetch('assets.stow');
+const buffer = await response.arrayBuffer();
+await reader.open(buffer);
+
+// List all assets
+const assets = reader.listAssets();
+console.log(`Found ${assets.length} assets`);
+
+// Find asset by path
+const index = reader.findAssetByPath('models/character.mesh');
+
+// Read asset data
+const data = reader.readAssetData(index);
+
+// Parse metadata (done in WASM!)
+const texInfo = reader.parseTextureMetadata(index);
+console.log(`Texture: ${texInfo.width}x${texInfo.height}`);
+
+const audioInfo = reader.parseAudioMetadata(index);
+console.log(`Audio: ${audioInfo.sampleRate}Hz, ${audioInfo.durationMs}ms`);
+
+const animInfo = reader.parseAnimationMetadata(index);
+console.log(`Animation: ${animInfo.duration}s, ${animInfo.boneCount} bones`);
+
+// Clean up
+reader.close();
+```
+
+## Asset Types
+
+| Type | ID | Description |
+|------|-------|-------------|
+| Static Mesh | 1 | Draco-compressed 3D models |
+| Texture 2D | 2 | KTX2/Basis Universal textures |
+| Audio | 3 | OGG/MP3 audio files |
+| Material Schema | 4 | Material template definitions |
+| Skinned Mesh | 5 | Skeletal meshes with bones |
+| Animation Clip | 6 | Bone animation keyframes |
+
+## API Reference
+
+### Exports
+
+```typescript
+export { StowKitReader } from '@series-inc/stowkit-reader';
+export { PerfLogger } from '@series-inc/stowkit-reader';
+export { AssetType } from '@series-inc/stowkit-reader';
+
+// Interfaces
+export type { AssetInfo, AssetListItem, TextureMetadata, AudioMetadata } from '@series-inc/stowkit-reader';
+```
+
+### Asset Types Enum
+
+```typescript
+enum AssetType {
+    UNKNOWN = 0,
+    STATIC_MESH = 1,
+    TEXTURE_2D = 2,
+    AUDIO = 3,
+    MATERIAL_SCHEMA = 4,
+    SKINNED_MESH = 5,
+    ANIMATION_CLIP = 6,
+}
+```
+
+### Initialization
+
+#### `new StowKitReader(wasmUrl?: string)`
+Create a new reader instance. Optionally specify the WASM file URL (default: `'/stowkit/stowkit_reader.wasm'`).
+
+#### `async init(): Promise<StowKitReader>`
+Initialize the WebAssembly module. Must be called before using the reader.
+
+```typescript
+const reader = new StowKitReader('/path/to/stowkit_reader.wasm');
+await reader.init();
+```
+
+### Opening Files
+
+#### `async open(file: ArrayBuffer | File): Promise<boolean>`
+Open a .stow file from memory.
+
+```typescript
+// From fetch
+const response = await fetch('assets.stow');
+const buffer = await response.arrayBuffer();
+await reader.open(buffer);
+
+// From file input
+const file = input.files[0];
+await reader.open(file);
+```
+
+### Asset Access
+
+#### `getAssetCount(): number`
+Get the total number of assets in the pack.
+
+#### `listAssets(): AssetListItem[]`
+Get information about all assets.
+
+```typescript
+const assets = reader.listAssets();
+assets.forEach(asset => {
+    console.log(`${asset.name} (type ${asset.type}): ${asset.dataSize} bytes`);
+});
+```
+
+#### `findAssetByPath(path: string): number`
+Find an asset index by its canonical path. Returns -1 if not found.
+
+```typescript
+const index = reader.findAssetByPath('models/character.mesh');
+if (index >= 0) {
+    const data = reader.readAssetData(index);
+}
+```
+
+#### `getAssetInfo(index: number): AssetInfo | null`
+Get detailed information about a specific asset.
+
+#### `readAssetData(index: number): Uint8Array | null`
+Read the binary data of an asset.
+
+#### `readAssetMetadata(index: number): Uint8Array | null`
+Read the raw metadata bytes of an asset.
+
+### WASM Metadata Parsing
+
+All metadata parsing is done in WASM for maximum performance. No manual DataView manipulation needed!
+
+#### `parseTextureMetadata(index: number): TextureMetadata | null`
+Parse texture metadata from WASM.
+
+```typescript
+const info = reader.parseTextureMetadata(2);
+// { stringId, width, height, channels, channelFormat, tags }
+```
+
+#### `parseAudioMetadata(index: number): AudioMetadata | null`
+Parse audio metadata from WASM.
+
+```typescript
+const info = reader.parseAudioMetadata(3);
+// { stringId, sampleRate, channels, durationMs, tags }
+```
+
+#### `parseMeshMetadata(index: number): object | null`
+Parse static mesh metadata from WASM.
+
+```typescript
+const info = reader.parseMeshMetadata(1);
+// { stringId, tags }
+```
+
+#### `parseAnimationMetadata(index: number): object | null`
+Parse animation clip metadata from WASM.
+
+```typescript
+const info = reader.parseAnimationMetadata(9);
+// { stringId, targetMeshId, duration, ticksPerSecond, channelCount, boneCount }
+```
+
+#### `parseMaterialSchemaMetadata(index: number): object | null`
+Parse material schema metadata from WASM.
+
+```typescript
+const schema = reader.parseMaterialSchemaMetadata(4);
+// { stringId, schemaName, fieldCount, fields: [...] }
+```
+
+#### `parseSkinnedMeshMetadata(index: number): object | null`
+Parse skinned mesh metadata from WASM (returns bone hierarchy and stringId).
+
+```typescript
+const info = reader.parseSkinnedMeshMetadata(8);
+// { stringId, boneCount, bones: [{name, parentIndex}, ...], tags }
+```
+
+#### `parseSkinnedMeshGeometryFast(metadataBlob: Uint8Array, dataBlob: Uint8Array): object | null`
+Parse skinned mesh geometry using WASM (10-50x faster than JavaScript!). Returns combined vertex/index buffers ready for rendering.
+
+```typescript
+const metadata = reader.readAssetMetadata(index);
+const data = reader.readAssetData(index);
+
+const geometry = reader.parseSkinnedMeshGeometryFast(metadata, data);
+if (geometry) {
+    const { vertexCount, indexCount, positions, normals, uvs, skinIndices, skinWeights, indices } = geometry;
+    // Use with Three.js BufferGeometry, etc.
+}
+```
+
+### Utility Methods
+
+#### `setAssetName(index: number, name: string): void`
+Set a custom name for an asset (for UI display purposes).
+
+```typescript
+reader.setAssetName(5, 'Custom Asset Name');
+const assets = reader.listAssets();
+// Asset at index 5 will now have name 'Custom Asset Name'
+```
+
+#### `static formatBytes(bytes: number): string`
+Format byte count to human-readable string.
+
+```typescript
+console.log(StowKitReader.formatBytes(1024));        // "1 KB"
+console.log(StowKitReader.formatBytes(1048576));     // "1 MB"
+console.log(StowKitReader.formatBytes(524288000));   // "500 MB"
+```
+
+### Cleanup
+
+#### `close(): void`
+Close the current file and free resources.
+
+```typescript
+reader.close();
+```
+
+## Why WASM Parsing?
+
+**Before (JavaScript):**
+```typescript
+// 50+ lines of manual DataView parsing
+const view = new DataView(metadata.buffer, metadata.byteOffset);
+const stringIdBytes = metadata.slice(0, 128);
+const decoder = new TextDecoder();
+const stringId = decoder.decode(stringIdBytes.slice(0, stringIdBytes.indexOf(0)));
+const sampleRate = view.getUint32(128, true);
+// ... 40 more lines ...
+```
+
+**After (WASM):**
+```typescript
+// 1 line!
+const info = reader.parseAudioMetadata(index);
+```
+
+**Benefits:**
+- ✅ Single source of truth (C header defines all structs)
+- ✅ 10-50x faster parsing
+- ✅ No sync issues between reader and parser
+- ✅ Less prone to offset calculation bugs
+- ✅ Cleaner, more maintainable code
+
+## Examples
+
+### Inspect a Pack
+
+```typescript
+import { StowKitReader, AssetType } from '@series-inc/stowkit-reader';
+
+const reader = new StowKitReader();
+await reader.init();
+
+const response = await fetch('game.stow');
+await reader.open(await response.arrayBuffer());
+
+const assets = reader.listAssets();
+console.log(`Pack contains ${assets.length} assets`);
+
+assets.forEach(asset => {
+    const typeName = ['Unknown', 'Mesh', 'Texture', 'Audio', 'Schema', 'Skinned Mesh', 'Animation'][asset.type] || 'Unknown';
+    console.log(`[${asset.index}] ${asset.name} - ${typeName} (${StowKitReader.formatBytes(asset.dataSize)})`);
+});
+
+reader.close();
+```
+
+### Extract Assets
+
+```typescript
+const reader = new StowKitReader();
+await reader.init();
+await reader.open(buffer);
+
+// Find and extract a specific asset
+const index = reader.findAssetByPath('models/character.mesh');
+if (index >= 0) {
+    const data = reader.readAssetData(index);
+    const metadata = reader.readAssetMetadata(index);
+    
+    // Save to file
+    const blob = new Blob([data]);
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = 'character.mesh';
+    a.click();
+}
+```
+
+## Requirements
+
+- WebAssembly support in the browser
+- The `stowkit_reader.wasm` file must be accessible at runtime

package/dist/PerfLogger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Performance logging utility
+ * Centralized configuration for all performance logs
+ */
+export declare class PerfLogger {
+    private static enabled;
+    private static customLogger;
+    /**
+     * Enable performance logging across all StowKit modules
+     */
+    static enable(): void;
+    /**
+     * Disable performance logging across all StowKit modules
+     */
+    static disable(): void;
+    /**
+     * Check if performance logging is enabled
+     */
+    static isEnabled(): boolean;
+    /**
+     * Set a custom logging function
+     * @param logger - Function to call for each log message (receives formatted string)
+     */
+    static setCustomLogger(logger: ((message: string) => void) | null): void;
+    /**
+     * Log a performance message (only if enabled)
+     */
+    static log(message: string): void;
+    /**
+     * Log a performance error (always logged regardless of setting)
+     */
+    static error(message: string): void;
+    /**
+     * Log a performance warning (always logged regardless of setting)
+     */
+    static warn(message: string): void;
+}
+//# sourceMappingURL=PerfLogger.d.ts.map

package/dist/PerfLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PerfLogger.d.ts","sourceRoot":"","sources":["../src/PerfLogger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,MAAM,CAAC,OAAO,CAAkB;IACxC,OAAO,CAAC,MAAM,CAAC,YAAY,CAA4C;IAEvE;;OAEG;IACH,MAAM,CAAC,MAAM,IAAI,IAAI;IAIrB;;OAEG;IACH,MAAM,CAAC,OAAO,IAAI,IAAI;IAItB;;OAEG;IACH,MAAM,CAAC,SAAS,IAAI,OAAO;IAI3B;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAIxE;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUjC;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAInC;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAGrC"}

package/dist/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * StowKit Reader - WebAssembly-based reader for .stow asset packs
+ */
+export { PerfLogger } from './PerfLogger';
+export declare enum AssetType {
+    UNKNOWN = 0,
+    STATIC_MESH = 1,
+    TEXTURE_2D = 2,
+    AUDIO = 3,
+    MATERIAL_SCHEMA = 4,
+    SKINNED_MESH = 5,
+    ANIMATION_CLIP = 6
+}
+export interface AssetInfo {
+    index: number;
+    type: number;
+    data_offset: number;
+    data_size: number;
+    metadata_offset: number;
+    metadata_size: number;
+}
+export interface AssetListItem extends AssetInfo {
+    name?: string;
+    id: bigint;
+    hasMetadata: boolean;
+    dataSize: number;
+    metadataSize: number;
+}
+export interface TextureMetadata {
+    width: number;
+    height: number;
+    channels: number;
+    channelFormat: number;
+    stringId?: string;
+    tags?: string[];
+}
+export interface AudioMetadata {
+    path?: string;
+    sampleRate?: number;
+    channels?: number;
+    durationMs?: number;
+    tags?: string[];
+}
+export declare class StowKitReader {
+    private wasm;
+    private memory;
+    private isReady;
+    private currentFile;
+    private assetNameMap;
+    private wasmUrl;
+    constructor(wasmUrl?: string);
+    /**
+     * Initialize the WASM module
+     */
+    init(): Promise<StowKitReader>;
+    /**
+     * Open a .stow file from an ArrayBuffer or File
+     */
+    open(fileOrBuffer: ArrayBuffer | File): Promise<boolean>;
+    /**
+     * Get the total number of assets
+     */
+    getAssetCount(): number;
+    /**
+     * Get info about all assets
+     */
+    listAssets(): AssetListItem[];
+    /**
+     * Get detailed info about a specific asset
+     */
+    getAssetInfo(index: number): AssetInfo | null;
+    /**
+     * Read the binary data of an asset
+     */
+    readAssetData(index: number): Uint8Array | null;
+    /**
+     * Read metadata of an asset (if available)
+     */
+    readAssetMetadata(index: number): Uint8Array | null;
+    /**
+     * Parse texture metadata using WASM (includes tags)
+     */
+    parseTextureMetadata(index: number): any;
+    /**
+     * Parse audio metadata using WASM (includes tags)
+     */
+    parseAudioMetadata(index: number): any;
+    /**
+     * Parse static mesh metadata using WASM (includes tags)
+     */
+    parseMeshMetadata(index: number): any;
+    /**
+     * Parse animation clip metadata using WASM
+     */
+    parseAnimationMetadata(index: number): any;
+    /**
+     * Parse skinned mesh metadata using WASM (partial - returns bone info)
+     */
+    parseSkinnedMeshMetadata(index: number): any;
+    /**
+     * Parse material schema metadata using WASM
+     */
+    parseMaterialSchemaMetadata(index: number): any;
+    /**
+     * Find an asset by its canonical path (string ID)
+     * Returns the asset index or -1 if not found
+     */
+    findAssetByPath(path: string): number;
+    /**
+     * Parse skinned mesh geometry using WASM (10-50x faster than JavaScript!)
+     * Returns combined vertex/index buffers ready for Three.js
+     */
+    parseSkinnedMeshGeometryFast(metadataBlob: Uint8Array, dataBlob: Uint8Array): {
+        vertexCount: number;
+        indexCount: number;
+        positions: Float32Array;
+        normals: Float32Array;
+        uvs: Float32Array;
+        skinIndices: Uint32Array;
+        skinWeights: Float32Array;
+        indices: Uint32Array;
+    } | null;
+    /**
+     * Close the current file and free resources
+     */
+    close(): void;
+    /**
+     * Set a custom name for an asset (for UI display)
+     */
+    setAssetName(index: number, name: string): void;
+    private _allocate;
+    private _free;
+    private _readString;
+    private _getAssetId;
+    /**
+     * Format bytes for display
+     */
+    static formatBytes(bytes: number): string;
+}
+export default StowKitReader;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}