ecspresso 0.10.2 → 0.11.0

package/dist/bundles/audio.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Audio Bundle for ECSpresso
+ *
+ * Web Audio API integration via Howler.js for sound effects and music playback.
+ * User-defined channels with type-safe volume control, hybrid resource + component API,
+ * and asset manager integration.
+ */
+import { Bundle } from 'ecspresso';
+import type { SystemPhase, AssetsOfWorld } from 'ecspresso';
+import type { Howl } from 'howler';
+/**
+ * Configuration for a single audio channel.
+ */
+export interface AudioChannelConfig {
+    readonly volume: number;
+}
+/**
+ * Define audio channels with type-safe names and initial volumes.
+ * Mirrors `defineCollisionLayers` pattern.
+ *
+ * @param channels Object mapping channel names to their configuration
+ * @returns Frozen channel configuration with inferred channel name union
+ *
+ * @example
+ * ```typescript
+ * const channels = defineAudioChannels({
+ *   sfx: { volume: 1 },
+ *   music: { volume: 0.7 },
+ *   ui: { volume: 0.8 },
+ * });
+ * type Ch = ChannelsOf<typeof channels>; // 'sfx' | 'music' | 'ui'
+ * ```
+ */
+export declare function defineAudioChannels<const T extends Record<string, AudioChannelConfig>>(channels: T): Readonly<T>;
+/**
+ * Extract channel name union from a `defineAudioChannels` result.
+ */
+export type ChannelsOf<T> = T extends Record<infer K extends string, AudioChannelConfig> ? K : never;
+/**
+ * Audio source component attached to entities for positional/entity-bound audio.
+ */
+export interface AudioSource<Ch extends string = string> {
+    /** Asset key for the sound */
+    readonly sound: string;
+    /** Channel this sound plays on */
+    readonly channel: Ch;
+    /** Individual volume (0-1) */
+    volume: number;
+    /** Whether sound loops */
+    loop: boolean;
+    /** Remove entity when sound ends (like timer autoRemove) */
+    autoRemove: boolean;
+    /** Whether sound is currently playing (system-managed) */
+    playing: boolean;
+    /** Howler sound ID (system-managed, -1 = not started) */
+    _soundId: number;
+}
+/**
+ * Component types provided by the audio bundle.
+ */
+export interface AudioComponentTypes<Ch extends string = string> {
+    audioSource: AudioSource<Ch>;
+}
+/**
+ * Event to trigger fire-and-forget sound playback from any system.
+ */
+export interface PlaySoundEvent<Ch extends string = string> {
+    /** Asset key for the sound */
+    sound: string;
+    /** Channel to play on */
+    channel?: Ch;
+    /** Individual volume (0-1) */
+    volume?: number;
+    /** Whether sound loops */
+    loop?: boolean;
+}
+/**
+ * Event to stop music on a channel.
+ */
+export interface StopMusicEvent<Ch extends string = string> {
+    /** Channel to stop music on. If omitted, stops all music. */
+    channel?: Ch;
+}
+/**
+ * Event published when a sound finishes playing.
+ */
+export interface SoundEndedEvent {
+    /** Entity ID if sound was entity-attached, -1 for fire-and-forget */
+    entityId: number;
+    /** Howler sound ID */
+    soundId: number;
+    /** Asset key of the sound */
+    sound: string;
+}
+/**
+ * Event types provided by the audio bundle.
+ */
+export interface AudioEventTypes<Ch extends string = string> {
+    playSound: PlaySoundEvent<Ch>;
+    stopMusic: StopMusicEvent<Ch>;
+    soundEnded: SoundEndedEvent;
+}
+/**
+ * Play options for fire-and-forget sound effects.
+ */
+export interface PlayOptions<Ch extends string = string> {
+    /** Channel to play on (uses first defined channel if omitted) */
+    channel?: Ch;
+    /** Individual volume (0-1, default: 1) */
+    volume?: number;
+    /** Whether to loop (default: false) */
+    loop?: boolean;
+}
+/**
+ * Music playback options.
+ */
+export interface MusicOptions<Ch extends string = string> {
+    /** Channel to play music on (uses first defined channel if omitted) */
+    channel?: Ch;
+    /** Volume (0-1, default: 1) */
+    volume?: number;
+    /** Whether to loop (default: true) */
+    loop?: boolean;
+}
+/**
+ * Audio state resource providing fire-and-forget SFX and music control.
+ * Effective volume = individual * channel * master.
+ */
+export interface AudioState<Ch extends string = string> {
+    /** Play a fire-and-forget sound effect. Returns the Howler sound ID. */
+    play(sound: string, options?: PlayOptions<Ch>): number;
+    /** Stop a specific sound by its Howler sound ID. */
+    stop(soundId: number): void;
+    /** Play music on a channel. Stops any existing music on that channel first. */
+    playMusic(sound: string, options?: MusicOptions<Ch>): void;
+    /** Stop music on a channel. If omitted, stops all music. */
+    stopMusic(channel?: Ch): void;
+    /** Pause music on a channel. If omitted, pauses all music. */
+    pauseMusic(channel?: Ch): void;
+    /** Resume music on a channel. If omitted, resumes all music. */
+    resumeMusic(channel?: Ch): void;
+    /** Set volume for a channel (0-1). */
+    setChannelVolume(channel: Ch, volume: number): void;
+    /** Get current volume for a channel. */
+    getChannelVolume(channel: Ch): number;
+    /** Set master volume (0-1). */
+    setMasterVolume(volume: number): void;
+    /** Get current master volume. */
+    getMasterVolume(): number;
+    /** Mute all audio. */
+    mute(): void;
+    /** Unmute all audio. */
+    unmute(): void;
+    /** Toggle mute state. */
+    toggleMute(): void;
+    /** Check if audio is muted. */
+    isMuted(): boolean;
+}
+/**
+ * Resource types provided by the audio bundle.
+ */
+export interface AudioResourceTypes<Ch extends string = string> {
+    audioState: AudioState<Ch>;
+}
+/**
+ * Configuration options for the audio bundle.
+ */
+export interface AudioBundleOptions<Ch extends string, G extends string = 'audio'> {
+    /** Channel definitions from defineAudioChannels */
+    channels: Readonly<Record<Ch, AudioChannelConfig>>;
+    /** System group name (default: 'audio') */
+    systemGroup?: G;
+    /** Priority for audio sync system (default: 0) */
+    priority?: number;
+    /** Execution phase (default: 'update') */
+    phase?: SystemPhase;
+}
+/**
+ * Create an audioSource component for entity-attached audio.
+ *
+ * @param sound Asset key for the sound
+ * @param channel Channel to play on
+ * @param options Optional configuration
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createAudioSource('explosion', 'sfx'),
+ *   ...createTransform(100, 200),
+ * });
+ * ```
+ */
+export declare function createAudioSource<Ch extends string>(sound: string, channel: Ch, options?: {
+    volume?: number;
+    loop?: boolean;
+    autoRemove?: boolean;
+}): Pick<AudioComponentTypes<Ch>, 'audioSource'>;
+/**
+ * Create a loader function for use with the asset manager.
+ * Returns a factory function that loads a Howl when called.
+ *
+ * @param src URL(s) for the sound file
+ * @param options Optional Howl configuration
+ * @returns Factory function compatible with asset manager's loader parameter
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withAssets(a => a
+ *     .add('explosion', loadSound('/sounds/explosion.mp3'))
+ *     .add('bgm', loadSound(['/sounds/bgm.webm', '/sounds/bgm.mp3']))
+ *   )
+ *   .build();
+ * ```
+ */
+export declare function loadSound(src: string | string[], options?: {
+    html5?: boolean;
+    preload?: boolean;
+}): () => Promise<Howl>;
+/**
+ * Create an audio bundle for ECSpresso.
+ *
+ * Provides:
+ * - `audioState` resource for fire-and-forget SFX and music
+ * - `audioSource` component for entity-attached sounds
+ * - Volume hierarchy: individual * channel * master
+ * - `playSound` / `stopMusic` event handlers
+ * - `soundEnded` event on completion
+ * - Automatic cleanup on entity removal (dispose callback)
+ *
+ * Sounds must be preloaded through the asset pipeline (`loadSound` helper).
+ *
+ * @example
+ * ```typescript
+ * const channels = defineAudioChannels({
+ *   sfx: { volume: 1 },
+ *   music: { volume: 0.7 },
+ * });
+ *
+ * const ecs = ECSpresso.create()
+ *   .withAssets(a => a.add('explosion', loadSound('/sfx/boom.mp3')))
+ *   .withBundle(createAudioBundle({ channels }))
+ *   .build();
+ *
+ * await ecs.initialize();
+ * const audio = ecs.getResource('audioState');
+ * audio.play('explosion', { channel: 'sfx' });
+ * ```
+ */
+export declare function createAudioBundle<Ch extends string, G extends string = 'audio'>(options: AudioBundleOptions<Ch, G>): Bundle<AudioComponentTypes<Ch>, AudioEventTypes<Ch>, AudioResourceTypes<Ch>, {}, {}, 'audio-sync', G, never, 'audio-sources'>;
+type AnyECSpresso = import('ecspresso').default<any, any, any, any, any, any, any>;
+/**
+ * Kit result from createAudioKit.
+ */
+export interface AudioKit<W extends AnyECSpresso, Ch extends string, G extends string = 'audio'> {
+    bundle: Bundle<AudioComponentTypes<Ch>, AudioEventTypes<Ch>, AudioResourceTypes<Ch>, {}, {}, 'audio-sync', G, never, 'audio-sources'>;
+    createAudioSource: (sound: keyof AssetsOfWorld<W> & string, channel: Ch, options?: {
+        volume?: number;
+        loop?: boolean;
+        autoRemove?: boolean;
+    }) => Pick<AudioComponentTypes<Ch>, 'audioSource'>;
+    loadSound: typeof loadSound;
+}
+/**
+ * Create a typed audio kit that captures the world type W and channel type Ch.
+ *
+ * The returned `createAudioSource` validates sound keys against the world's
+ * asset types at compile time.
+ *
+ * @template W - Concrete ECS world type (e.g. `typeof ecs`)
+ * @template Ch - Channel name union from defineAudioChannels
+ * @template G - System group name (default: 'audio')
+ * @param options - Bundle configuration including channel definitions
+ * @returns A kit object with bundle, createAudioSource, loadSound
+ *
+ * @example
+ * ```typescript
+ * const channels = defineAudioChannels({ sfx: { volume: 1 }, music: { volume: 0.7 } });
+ * type Ch = ChannelsOf<typeof channels>;
+ * const kit = createAudioKit<typeof ecs, Ch>({ channels });
+ *
+ * const ecs = ECSpresso.create()
+ *   .withBundle(kit.bundle)
+ *   .withAssets(a => a.add('boom', loadSound('/sfx/boom.mp3')))
+ *   .build();
+ *
+ * // Type-safe: 'boom' must be a registered asset
+ * kit.createAudioSource('boom', 'sfx');
+ * ```
+ */
+export declare function createAudioKit<W extends AnyECSpresso, Ch extends string, G extends string = 'audio'>(options: AudioBundleOptions<Ch, G>): AudioKit<W, Ch, G>;
+export {};

package/dist/bundles/{utils/bounds.d.ts → bounds.d.ts}

@@ -31,13 +31,15 @@ export interface WrapAtBounds {
 }
 /**
  * Component types provided by the bounds bundle.
- * Extend your component types with this interface.
+ * Included automatically via `.withBundle(createBoundsBundle())`.
  *
  * @example
  * ```typescript
- * interface GameComponents extends TransformComponentTypes, BoundsComponentTypes {
- *   sprite: Sprite;
- * }
+ * const ecs = ECSpresso.create()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createBoundsBundle({ width: 800, height: 600 }))
+ *   .withComponentTypes<{ sprite: Sprite }>()
+ *   .build();
  * ```
  */
 export interface BoundsComponentTypes {
@@ -82,9 +84,9 @@ export interface BoundsEventTypes {
 /**
  * Configuration options for the bounds bundle.
  */
-export interface BoundsBundleOptions {
+export interface BoundsBundleOptions<G extends string = 'physics'> {
     /** System group name (default: 'physics') */
-    systemGroup?: string;
+    systemGroup?: G;
     /** Priority for bounds systems (default: 50) */
     priority?: number;
     /** Resource key for bounds rectangle (default: 'bounds') */
@@ -185,5 +187,5 @@ type CombinedComponentTypes = BoundsComponentTypes & TransformComponentTypes;
  * });
  * ```
  */
-export declare function createBoundsBundle<ResourceTypes extends BoundsResourceTypes = BoundsResourceTypes>(options?: BoundsBundleOptions): Bundle<CombinedComponentTypes, BoundsEventTypes, ResourceTypes>;
+export declare function createBoundsBundle<ResourceTypes extends BoundsResourceTypes = BoundsResourceTypes, G extends string = 'physics'>(options?: BoundsBundleOptions<G>): Bundle<CombinedComponentTypes, BoundsEventTypes, ResourceTypes, {}, {}, 'bounds-destroy' | 'bounds-clamp' | 'bounds-wrap', G>;
 export {};

package/dist/bundles/camera.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Camera / Viewport Bundle for ECSpresso
+ *
+ * Provides a camera entity with world/screen coordinate conversion, smooth follow,
+ * trauma-based shake, bounds clamping, and logical viewport dimensions.
+ *
+ * This bundle is renderer-agnostic. PixiJS or other renderer integration (applying
+ * cameraState to a container/stage transform) is the consumer's responsibility.
+ *
+ * Camera uses its own x/y/zoom/rotation rather than localTransform/worldTransform.
+ * It reads the target entity's worldTransform for follow, but doesn't participate
+ * in the transform hierarchy itself.
+ */
+import { Bundle } from 'ecspresso';
+import type { SystemPhase } from 'ecspresso';
+import type ECSpresso from 'ecspresso';
+import type { TransformComponentTypes } from './transform';
+export interface Camera {
+    x: number;
+    y: number;
+    zoom: number;
+    rotation: number;
+}
+export interface CameraFollow {
+    target: number;
+    smoothing: number;
+    deadzoneX: number;
+    deadzoneY: number;
+    offsetX: number;
+    offsetY: number;
+}
+export interface CameraShake {
+    trauma: number;
+    traumaDecay: number;
+    maxOffsetX: number;
+    maxOffsetY: number;
+    maxRotation: number;
+}
+export interface CameraBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface CameraComponentTypes {
+    camera: Camera;
+    cameraFollow: CameraFollow;
+    cameraShake: CameraShake;
+    cameraBounds: CameraBounds;
+}
+type CombinedComponentTypes = CameraComponentTypes & TransformComponentTypes;
+export interface CameraState {
+    x: number;
+    y: number;
+    zoom: number;
+    rotation: number;
+    shakeOffsetX: number;
+    shakeOffsetY: number;
+    shakeRotation: number;
+    viewportWidth: number;
+    viewportHeight: number;
+}
+export interface CameraResourceTypes {
+    cameraState: CameraState;
+}
+export interface CameraBundleOptions<G extends string = 'camera'> {
+    viewportWidth?: number;
+    viewportHeight?: number;
+    systemGroup?: G;
+    phase?: SystemPhase;
+    randomFn?: () => number;
+}
+export declare const DEFAULT_CAMERA: Readonly<Camera>;
+export declare const DEFAULT_CAMERA_STATE: Readonly<CameraState>;
+export declare function createCamera(x?: number, y?: number, zoom?: number, rotation?: number): Pick<CameraComponentTypes, 'camera'>;
+export declare function createCameraFollow(target: number, options?: Partial<Omit<CameraFollow, 'target'>>): Pick<CameraComponentTypes, 'cameraFollow'>;
+export declare function createCameraShake(options?: Partial<CameraShake>): Pick<CameraComponentTypes, 'cameraShake'>;
+export declare function createCameraBounds(minX: number, minY: number, maxX: number, maxY: number): Pick<CameraComponentTypes, 'cameraBounds'>;
+export declare function addTrauma<C extends CombinedComponentTypes, R extends CameraResourceTypes>(ecs: ECSpresso<C, any, R>, entityId: number, amount: number): void;
+export declare function worldToScreen(worldX: number, worldY: number, state: CameraState): {
+    x: number;
+    y: number;
+};
+export declare function screenToWorld(screenX: number, screenY: number, state: CameraState): {
+    x: number;
+    y: number;
+};
+export declare function createCameraBundle<G extends string = 'camera'>(options?: CameraBundleOptions<G>): Bundle<CombinedComponentTypes, {}, CameraResourceTypes, {}, {}, 'camera-follow' | 'camera-shake-update' | 'camera-bounds' | 'camera-state-sync', G>;
+export {};