@series-inc/stowkit-phaser-loader 0.1.18 → 0.1.20

package/package.json

@@ -1,55 +1,58 @@
-{
-  "name": "@series-inc/stowkit-phaser-loader",
-  "version": "0.1.18",
-  "description": "Phaser loader for StowKit asset packs with KTX2/Basis Universal compressed texture support",
-  "main": "dist/stowkit-phaser-loader.js",
-  "module": "dist/stowkit-phaser-loader.esm.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "rollup -c",
-    "dev": "rollup -c -w",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@series-inc/stowkit-reader": "^0.1.3"
-  },
-  "peerDependencies": {
-    "phaser": "^3.60.0"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-typescript": "^11.1.5",
-    "phaser": "^3.70.0",
-    "rollup": "^4.9.1",
-    "tslib": "^2.6.2",
-    "typescript": "^5.3.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/series-ai/stowkit-2.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "stowkit",
-    "phaser",
-    "phaser3",
-    "game-engine",
-    "asset-loader",
-    "ktx2",
-    "basis-universal",
-    "compressed-textures",
-    "webassembly",
-    "texture-compression",
-    "bc3",
-    "dxt5",
-    "astc",
-    "etc2"
-  ],
-  "author": ""
-}
+{
+  "name": "@series-inc/stowkit-phaser-loader",
+  "version": "0.1.20",
+  "description": "Phaser loader for StowKit asset packs with KTX2/Basis Universal compressed texture support",
+  "main": "dist/stowkit-phaser-loader.js",
+  "module": "dist/stowkit-phaser-loader.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "scripts",
+    "skill.md"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.cjs"
+  },
+  "dependencies": {
+    "@series-inc/stowkit-reader": "^0.1.3"
+  },
+  "peerDependencies": {
+    "phaser": "^3.60.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^11.1.5",
+    "phaser": "^3.70.0",
+    "rollup": "^4.9.1",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/series-ai/stowkit-2.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "stowkit",
+    "phaser",
+    "phaser3",
+    "game-engine",
+    "asset-loader",
+    "ktx2",
+    "basis-universal",
+    "compressed-textures",
+    "webassembly",
+    "texture-compression",
+    "bc3",
+    "dxt5",
+    "astc",
+    "etc2"
+  ],
+  "author": ""
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,37 @@
+const fs = require('fs');
+const path = require('path');
+
+const isInNodeModules = __dirname.includes('node_modules');
+const projectRoot = process.env.INIT_CWD || process.cwd();
+
+if (isInNodeModules) {
+    // Copy AI skill/rule files
+    try {
+        const skillSrc = path.join(__dirname, '..', 'skill.md');
+
+        if (fs.existsSync(skillSrc)) {
+            // Claude: .claude/skills/stowkit-phaser/SKILL.md
+            const claudeSkillDir = path.join(projectRoot, '.claude', 'skills', 'stowkit-phaser');
+            fs.mkdirSync(claudeSkillDir, { recursive: true });
+            fs.copyFileSync(skillSrc, path.join(claudeSkillDir, 'SKILL.md'));
+            console.log('✓ Copied Claude skill to .claude/skills/stowkit-phaser/SKILL.md');
+
+            // Cursor: .cursor/rules/stowkit-phaser.mdc
+            const cursorRulesDir = path.join(projectRoot, '.cursor', 'rules');
+            fs.mkdirSync(cursorRulesDir, { recursive: true });
+            const skillContent = fs.readFileSync(skillSrc, 'utf-8');
+            const cursorRule = [
+                '---',
+                'description: StowKit Phaser loader — loading KTX2/Basis compressed textures and audio from .stow packs',
+                'alwaysApply: true',
+                '---',
+                '',
+                skillContent,
+            ].join('\n');
+            fs.writeFileSync(path.join(cursorRulesDir, 'stowkit-phaser.mdc'), cursorRule);
+            console.log('✓ Copied Cursor rule to .cursor/rules/stowkit-phaser.mdc');
+        }
+    } catch (error) {
+        console.warn('Could not copy AI skill/rule files:', error.message);
+    }
+}

package/skill.md

@@ -0,0 +1,166 @@
+# StowKit Phaser Loader
+
+Use `@series-inc/stowkit-phaser-loader` to load `.stow` asset packs in Phaser applications. Supports 2D textures and audio only — for 3D models use `@series-inc/stowkit-three-loader`.
+
+## Installation
+
+```bash
+npm install @series-inc/stowkit-phaser-loader phaser
+```
+
+Requires Phaser 3.60+ for compressed texture support.
+
+## Loading a Pack
+
+```typescript
+import { StowKitPhaserLoader } from '@series-inc/stowkit-phaser-loader';
+
+const pack = await StowKitPhaserLoader.load('/assets/game.stow');
+```
+
+Options (all optional):
+- `basisPath` — path to Basis Universal transcoder dir (default: `'/basis/'`)
+- `wasmPath` — path to `stowkit_reader.wasm` (default: `'/stowkit/stowkit_reader.wasm'`)
+- `gl` — WebGL context to use (if not provided, a temporary canvas is created)
+
+Load from memory:
+```typescript
+const buffer = await fetch(url).then(r => r.arrayBuffer());
+const pack = await StowKitPhaserLoader.loadFromMemory(buffer);
+```
+
+## Asset Types
+
+| Type | Enum | Load Method |
+|------|------|-------------|
+| Texture | `AssetType.TEXTURE_2D` (2) | `pack.loadTexture(path, scene)` / `pack.getPhaserTexture(index, scene)` |
+| Audio | `AssetType.AUDIO` (3) | `pack.loadAudio(path, ctx?)` / `pack.loadAudioByIndex(index, ctx?)` |
+
+Assets are referenced by their `stringId` from `.stowmeta` files.
+
+## Textures
+
+```typescript
+await pack.loadTexture('characters/player', this);
+const player = this.add.sprite(400, 300, 'characters/player');
+```
+
+`loadTexture` registers the texture with Phaser's texture manager using the asset path as the key. Must be called in or after `create()`.
+
+KTX2 textures are automatically transcoded to the best GPU-compressed format:
+- **Desktop:** BC7 (BPTC), BC3 (DXT5), BC1 (DXT1)
+- **Mobile:** ASTC 4x4, ETC2, ETC1, PVRTC
+- **Fallback:** RGBA32 uncompressed
+
+## Audio
+
+```typescript
+const buffer = await pack.loadAudio('sounds/bgm');
+
+// Or with a specific AudioContext
+const ctx = new AudioContext();
+const buffer = await pack.loadAudio('sounds/bgm', ctx);
+```
+
+For HTML5 preview: `const el = await pack.createAudioPreview(index);`
+
+## Pack Manifest
+
+```typescript
+const assets = pack.listAssets();
+// Each: { index, name, id, type, dataSize, hasMetadata }
+
+const count = pack.getAssetCount();
+const info = pack.getAssetInfo(0);
+```
+
+## Metadata Helpers
+
+```typescript
+const tex = pack.getTextureMetadata(index);
+// { width, height, channels, channelFormat }
+
+const audio = pack.getAudioMetadata(index);
+// { sampleRate, channels, durationMs }
+```
+
+## Multiple Packs
+
+Each pack has its own WASM reader instance — fully isolated:
+```typescript
+const [uiPack, levelPack] = await Promise.all([
+    StowKitPhaserLoader.load('/assets/ui.stow'),
+    StowKitPhaserLoader.load('/assets/level1.stow'),
+]);
+```
+
+## Cleanup
+
+```typescript
+pack.dispose(); // Closes WASM reader, frees resources
+StowKitPhaserLoader.dispose(); // Frees shared Basis transcoder + temp WebGL context
+```
+
+## Exports
+
+```typescript
+import {
+    StowKitPhaserLoader,  // Static loader class
+    StowKitPhaserPack,    // Pack instance (returned by load)
+    BasisTranscoder,      // Basis Universal transcoder
+    AssetType,            // Enum: STATIC_MESH, TEXTURE_2D, AUDIO, etc.
+    PerfLogger            // Performance logging
+} from '@series-inc/stowkit-phaser-loader';
+
+// Types
+import type {
+    StowKitPhaserLoaderOptions,
+    TextureData
+} from '@series-inc/stowkit-phaser-loader';
+```
+
+## Complete Example
+
+```typescript
+import Phaser from 'phaser';
+import { StowKitPhaserLoader } from '@series-inc/stowkit-phaser-loader';
+
+class GameScene extends Phaser.Scene {
+    constructor() {
+        super('GameScene');
+    }
+
+    async create() {
+        const pack = await StowKitPhaserLoader.load('/assets/game.stow');
+
+        await pack.loadTexture('backgrounds/sky', this);
+        await pack.loadTexture('characters/player', this);
+        await pack.loadTexture('ui/button', this);
+
+        this.add.image(400, 300, 'backgrounds/sky');
+        const player = this.add.sprite(400, 300, 'characters/player');
+        this.add.image(100, 50, 'ui/button');
+
+        const bgm = await pack.loadAudio('sounds/bgm');
+        const source = this.sound.context.createBufferSource();
+        source.buffer = bgm;
+        source.connect(this.sound.context.destination);
+        source.loop = true;
+        source.start();
+    }
+}
+
+const game = new Phaser.Game({
+    type: Phaser.WEBGL,
+    width: 800,
+    height: 600,
+    scene: GameScene
+});
+```
+
+## Troubleshooting
+
+- **Textures not loading** — Ensure Basis transcoder files are accessible at the `basisPath` URL
+- **"Scene required" errors** — `loadTexture` must be called in or after `create()`, not in `preload()`
+- **No compressed format supported** — Falls back to RGBA32; check WebGL context is available
+- **Need 3D models?** — Use `@series-inc/stowkit-three-loader` instead; this loader is 2D only