bonkjs 0.2.0

package/README.md

@@ -0,0 +1,94 @@
+# bonkjs
+
+A 2D game toolkit for AI collaboration. TypeScript-first. No scene format, no component hierarchy — Claude decides the architecture per game.
+
+## Install
+
+```bash
+npm install bonkjs
+```
+
+## Quick Start
+
+```typescript
+import { Game, Sprite, Camera, RigidBody, Input, Transform } from 'bonkjs';
+
+const game = new Game();
+const canvas = await game.init({ width: 800, height: 600 });
+document.getElementById('app')!.appendChild(canvas);
+
+const player = new Transform({ position: [400, 300] });
+const sprite = new Sprite(game.renderer, { width: 48, height: 64, color: 0x00ff00, transform: player });
+const body = game.createBody(player, { type: 'dynamic', fixedRotation: true });
+body.addCollider({ type: 'box', width: 48, height: 64 });
+
+const camera = new Camera(game.renderer, { followSmoothing: 8 });
+camera.follow(() => player.worldPosition);
+
+game.onFixedUpdate(() => { body.syncFromPhysics(); });
+game.onUpdate(() => {
+  const h = Input.getAxisRaw('horizontal');
+  body.velocity = [h * 300, body.velocity[1]];
+  sprite.sync();
+});
+game.onLateUpdate(() => { camera.update(); });
+
+game.start();
+```
+
+No scene format. No component hierarchy. Import what you need — tree-shaking handles the rest.
+
+## What It Provides
+
+- **Rendering** — Sprites, animated sprites, camera follow/zoom/bounds, z-ordering, screen shake (PixiJS v8)
+- **Physics** — Rigid body, collider shapes, collision layers, triggers, raycasting (Matter.js)
+- **Input** — Named axes and buttons, raw key/mouse access, smoothed variants
+- **Audio** — Music, SFX, spatial audio, browser autoplay handling (Howler.js)
+- **Math** — vec2 operations (add, sub, normalize, dot, cross, lerp, rotate, distance)
+- **Game Loop** — Fixed timestep physics (60Hz), variable render, time scaling, coroutines
+
+## What It Does NOT Provide
+
+- Scene format or scene loader
+- GameObject/Component/Behavior hierarchy
+- Editor panels or inspector
+- Entity-component framework
+
+Games build their own architecture. The game code IS the scene.
+
+## Architecture — The Sandwich Model
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Layer 3: Bonk Overlay (game-agnostic dev tools)        │
+│  Debug wireframes, performance overlays, build targets  │
+├─────────────────────────────────────────────────────────┤
+│  Layer 2: Game Code (your code, game-specific)          │
+│  Whatever architecture THIS game needs                  │
+├─────────────────────────────────────────────────────────┤
+│  Layer 1: Bonk Runtime (game-agnostic tools)            │
+│  Rendering, physics, input, audio, math, camera, UI     │
+└─────────────────────────────────────────────────────────┘
+```
+
+Layer 1 is the npm package. Layer 2 is whatever your game needs. Layer 3 is optional dev tooling (planned).
+
+## Commands
+
+```bash
+npm run dev          # Hot-reload dev server (port 3000)
+npm run build        # Library build (ESM + declarations → dist/)
+npm run build:watch  # Library build with file watching
+npm run typecheck    # Type check only
+```
+
+## Documentation
+
+- [CLAUDE.md](./CLAUDE.md) — AI collaboration context, new game setup recipe, npm link workflow
+- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — Full architecture
+- [docs/CAMERA.md](./docs/CAMERA.md) — Camera system
+- [docs/PHYSICS.md](./docs/PHYSICS.md) — Physics and collision
+- [docs/INPUT.md](./docs/INPUT.md) — Input system
+- [docs/AUDIO-SYSTEM.md](./docs/AUDIO-SYSTEM.md) — Audio
+- [docs/EVENTS.md](./docs/EVENTS.md) — Event system
+- [docs/UI-SYSTEM.md](./docs/UI-SYSTEM.md) — UI system

package/dist/audio/AudioManager.d.ts

@@ -0,0 +1,105 @@
+import { Howl } from 'howler';
+/** Volume categories for audio */
+export type VolumeCategory = 'master' | 'music' | 'sfx';
+/** Audio events emitted by the system */
+export declare const AudioEvents: {
+    /** Fired when audio context is unlocked by user interaction */
+    readonly UNLOCKED: "audio:unlocked";
+    /** Fired when a volume category changes */
+    readonly VOLUME_CHANGED: "audio:volume:changed";
+};
+declare class AudioManagerImpl {
+    /** Cache of loaded sounds by path */
+    private cache;
+    /** Volume levels for each category */
+    private volumes;
+    /** Whether audio context has been unlocked */
+    private unlocked;
+    /** Callbacks waiting for unlock */
+    private unlockCallbacks;
+    /** Whether init has been called */
+    private initialized;
+    /**
+     * Initialize the audio manager.
+     * Sets up browser autoplay unlock listeners.
+     * Safe to call multiple times.
+     */
+    init(): void;
+    /** Handle successful audio unlock */
+    private handleUnlock;
+    /**
+     * Set volume for a category.
+     * @param category - The volume category
+     * @param value - Volume level (0-1)
+     */
+    setVolume(category: VolumeCategory, value: number): void;
+    /**
+     * Get volume for a category.
+     * @param category - The volume category
+     * @returns Volume level (0-1)
+     */
+    getVolume(category: VolumeCategory): number;
+    /**
+     * Get effective volume for a category (master * category).
+     * @param category - The volume category
+     * @returns Effective volume level (0-1)
+     */
+    getEffectiveVolume(category: VolumeCategory): number;
+    /**
+     * Preload audio files.
+     * @param paths - Array of audio file paths to preload
+     * @returns Promise that resolves when all files are loaded
+     */
+    preload(paths: string[]): Promise<void>;
+    /**
+     * Get or load a sound (async).
+     * @param path - Path to the audio file
+     * @returns Promise that resolves to the Howl instance
+     */
+    getSound(path: string): Promise<Howl>;
+    /**
+     * Get cached sound (sync).
+     * Returns null if not loaded.
+     * @param path - Path to the audio file
+     * @returns Howl instance or null
+     */
+    getSoundSync(path: string): Howl | null;
+    /**
+     * Check if audio context is unlocked.
+     * @returns True if audio can play without user interaction
+     */
+    isUnlocked(): boolean;
+    /**
+     * Register a callback for when audio is unlocked.
+     * Calls immediately if already unlocked.
+     * @param callback - Function to call when unlocked
+     */
+    onUnlock(callback: () => void): void;
+    /**
+     * Unload a specific sound from cache.
+     * @param path - Path to the audio file
+     */
+    unload(path: string): void;
+    /**
+     * Destroy and cleanup all sounds.
+     */
+    destroy(): void;
+    /**
+     * Pause all sounds.
+     */
+    pauseAll(): void;
+    /**
+     * Resume all sounds that were playing.
+     */
+    resumeAll(): void;
+    /**
+     * Stop all sounds.
+     */
+    stopAll(): void;
+}
+/** Global AudioManager singleton */
+export declare const AudioManager: AudioManagerImpl;
+/** Convenience function to get the AudioManager */
+export declare function getAudioManager(): AudioManagerImpl;
+export {};
+//# sourceMappingURL=AudioManager.d.ts.map

package/dist/audio/AudioManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioManager.d.ts","sourceRoot":"","sources":["../../src/audio/AudioManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAU,MAAM,QAAQ,CAAC;AAGtC,kCAAkC;AAClC,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;AAExD,yCAAyC;AACzC,eAAO,MAAM,WAAW;IACtB,+DAA+D;;IAE/D,2CAA2C;;CAEnC,CAAC;AAEX,cAAM,gBAAgB;IACpB,qCAAqC;IACrC,OAAO,CAAC,KAAK,CAA2B;IAExC,sCAAsC;IACtC,OAAO,CAAC,OAAO,CAIb;IAEF,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAS;IAEzB,mCAAmC;IACnC,OAAO,CAAC,eAAe,CAAyB;IAEhD,mCAAmC;IACnC,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAmCZ,qCAAqC;IACrC,OAAO,CAAC,YAAY;IAiBpB;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAWxD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM;IAI3C;;;;OAIG;IACH,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM;IAOpD;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C;;;;OAIG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB3C;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIvC;;;OAGG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAQpC;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ1B;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;IACH,QAAQ,IAAI,IAAI;IAMhB;;OAEG;IACH,SAAS,IAAI,IAAI;IAajB;;OAEG;IACH,OAAO,IAAI,IAAI;CAKhB;AAED,oCAAoC;AACpC,eAAO,MAAM,YAAY,kBAAyB,CAAC;AAEnD,mDAAmD;AACnD,wBAAgB,eAAe,IAAI,gBAAgB,CAElD"}

package/dist/audio/AudioSource.d.ts

@@ -0,0 +1,69 @@
+import { Renderer } from '../render/Renderer';
+import { Transform } from '../runtime/Transform';
+/** Configuration for creating an AudioSource */
+export interface AudioSourceConfig {
+    /** Audio file source path */
+    src?: string;
+    /** Base volume (0-1) */
+    volume?: number;
+    /** Whether to loop playback */
+    loop?: boolean;
+    /** Volume category */
+    category?: 'music' | 'sfx';
+    /** Enable spatial audio */
+    spatial?: boolean;
+    /** Minimum distance for full volume (spatial) */
+    minDistance?: number;
+    /** Maximum distance before silent (spatial) */
+    maxDistance?: number;
+}
+export declare class AudioSource {
+    /** Audio file source path */
+    src: string;
+    /** Base volume (0-1) */
+    volume: number;
+    /** Whether to loop */
+    loop: boolean;
+    /** Volume category */
+    category: 'music' | 'sfx';
+    /** Spatial audio enabled */
+    spatial: boolean;
+    /** Minimum distance for full volume */
+    minDistance: number;
+    /** Maximum distance before silent */
+    maxDistance: number;
+    private sound;
+    private soundId;
+    private effectiveVolume;
+    private _transform;
+    constructor(config?: AudioSourceConfig);
+    /** Set the transform for spatial audio positioning. */
+    setTransform(transform: Transform): void;
+    /** Load the audio file. Call before play(). */
+    load(): Promise<void>;
+    /** Play the sound. */
+    play(): void;
+    /** Pause playback. */
+    pause(): void;
+    /** Stop playback and reset. */
+    stop(): void;
+    /** Resume paused playback. */
+    resume(): void;
+    /** Seek to a specific time in seconds. */
+    seek(time: number): void;
+    /** Fade volume over time. */
+    fade(from: number, to: number, durationMs: number): void;
+    /** Check if currently playing. */
+    get playing(): boolean;
+    /** Get current playback time in seconds. */
+    getTime(): number;
+    /** Get total duration in seconds. */
+    getDuration(): number;
+    /** Play a one-shot sound. */
+    playOneShot(path?: string): Promise<void>;
+    /** Update spatial audio (call each frame if spatial is enabled). */
+    updateSpatialAudio(renderer: Renderer | null): void;
+    /** Destroy and clean up. */
+    destroy(): void;
+}
+//# sourceMappingURL=AudioSource.d.ts.map

package/dist/audio/AudioSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioSource.d.ts","sourceRoot":"","sources":["../../src/audio/AudioSource.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sBAAsB;IACtB,QAAQ,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAC3B,2BAA2B;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,WAAW;IACtB,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IAEZ,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IAEf,sBAAsB;IACtB,IAAI,EAAE,OAAO,CAAC;IAEd,sBAAsB;IACtB,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC;IAE1B,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IAEjB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IAEpB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,UAAU,CAA0B;gBAEhC,MAAM,CAAC,EAAE,iBAAiB;IAUtC,uDAAuD;IACvD,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC,+CAA+C;IACzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,sBAAsB;IACtB,IAAI,IAAI,IAAI;IAoBZ,sBAAsB;IACtB,KAAK,IAAI,IAAI;IAMb,+BAA+B;IAC/B,IAAI,IAAI,IAAI;IAOZ,8BAA8B;IAC9B,MAAM,IAAI,IAAI;IAMd,0CAA0C;IAC1C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMxB,6BAA6B;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAQxD,kCAAkC;IAClC,IAAI,OAAO,IAAI,OAAO,CAGrB;IAED,4CAA4C;IAC5C,OAAO,IAAI,MAAM;IAMjB,qCAAqC;IACrC,WAAW,IAAI,MAAM;IAKrB,6BAA6B;IACvB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/C,oEAAoE;IACpE,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI;IA4BnD,4BAA4B;IAC5B,OAAO,IAAI,IAAI;CAIhB"}

package/dist/audio/index.d.ts

@@ -0,0 +1,3 @@
+export { AudioManager, getAudioManager, AudioEvents, type VolumeCategory, } from './AudioManager';
+export { AudioSource, type AudioSourceConfig } from './AudioSource';
+//# sourceMappingURL=index.d.ts.map

package/dist/audio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,eAAe,EACf,WAAW,EACX,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC"}