add sound type, convert to ts, further docs, export/import

Author: sojs-coder

Parts/Sound.ts

@@ -0,0 +1,88 @@
+import { Part } from "./Part";
+
+export class Sound extends Part {
+    audio: HTMLAudioElement;
+    playAfterLoad: boolean = false; // Flag to indicate if play should be attempted after load
+    private _isLoaded: boolean = false;
+
+    constructor({ name, src, volume = 1, loop = false }: { name: string, src: string, volume?: number, loop?: boolean }) {
+        super({ name });
+        this.debugEmoji = "🔊";
+        this.audio = new Audio(src);
+        this.audio.volume = volume;
+        this.audio.loop = loop;
+
+        this.audio.addEventListener('canplaythrough', () => {
+            this._isLoaded = true;
+            this.ready = true;
+            if (this.playAfterLoad) {
+                this.playAfterLoad = false; // Reset flag
+                // Ensure user has interacted with the screen before playing audio
+                if (document.readyState === "complete" && (document.hasFocus() || "ontouchstart" in window)) {
+                    this.play(); // Attempt to play after load
+                } else {
+                    const tryPlay = () => {
+                        this.play();
+                        window.removeEventListener('pointerdown', tryPlay);
+                        window.removeEventListener('keydown', tryPlay);
+                    };
+                    window.addEventListener('pointerdown', tryPlay, { once: true });
+                    window.addEventListener('keydown', tryPlay, { once: true });
+                }
+            }
+            console.log(`Sound <${this.name}> loaded successfully.`);
+        });
+
+        this.audio.addEventListener('error', () => {
+            this._isLoaded = false;
+            this.ready = false;
+            console.error(`Failed to load sound <${this.name}> from src: ${src}`);
+        });
+    }
+
+    play(options: { restart?: boolean, clone?: boolean } = {}) {
+        const { restart = false, clone = false } = options;
+
+        if (!this._isLoaded) {
+            console.warn(`Sound <${this.name}> is not loaded yet. Cannot play.`);
+            this.playAfterLoad = true;
+            return;
+        }
+
+        if (clone) {
+            // Play a new instance (overlap sounds)
+            const cloneAudio = this.audio.cloneNode(true) as HTMLAudioElement;
+            cloneAudio.volume = this.audio.volume;
+            cloneAudio.loop = this.audio.loop;
+            cloneAudio.play().catch(e => console.error(`Error playing cloned sound <${this.name}>:`, e));
+        } else {
+            // Restart current audio if requested
+            if (restart) {
+                this.audio.currentTime = 0;
+            }
+            this.audio.play().catch(e => console.error(`Error playing sound <${this.name}>:`, e));
+        }
+    }
+
+    pause() {
+        this.audio.pause();
+    }
+
+    stop() {
+        this.audio.pause();
+        this.audio.currentTime = 0;
+    }
+
+    setVolume(volume: number) {
+        this.audio.volume = Math.max(0, Math.min(1, volume)); // Clamp between 0 and 1
+    }
+
+    setLoop(loop: boolean) {
+        this.audio.loop = loop;
+    }
+
+    act() {
+        super.act();
+        this.hoverbug = `${this.audio.paused ? "⏸️" : "▶️"} V:${this.audio.volume.toFixed(2)} L:${this.audio.loop ? "✅" : "❌"}`;
+    }
+}

docs/_sidebar.md

@@ -8,6 +8,7 @@
     - [Scene](api/Scene.md)
     - [Layer](api/Layer.md)
     - [GameObject](api/GameObject.md)
+    - [Sound](api/Sound.md)
   - **Components**
     - [Transform](api/Transform.md)
     - [Camera](api/Camera.md)

docs/api/Sound.md

@@ -0,0 +1,114 @@
+# Sound
+
+**Extends:** [Part](./Part.md)
+
+The `Sound` component allows you to load and play audio files within your game. It wraps the browser's native `HTMLAudioElement`.
+
+## Properties
+
+-   `audio: HTMLAudioElement`
+    The underlying HTML Audio Element. You can access this directly for more advanced control if needed.
+
+-   `_isLoaded: boolean`
+    Internal flag indicating if the audio file has successfully loaded and is ready to play.
+
+## Constructor Parameters
+
+-   `name: string`
+    The name of the sound part.
+
+-   `src: string`
+    The path to the audio file (e.g., `"./assets/music.mp3"`, `"./assets/sfx/jump.wav"`).
+
+-   `volume?: number` (default: `1`)
+    The volume of the sound, a value between 0 (silent) and 1 (full volume).
+
+-   `loop?: boolean` (default: `false`)
+    If `true`, the sound will loop continuously when played.
+
+## Methods
+
+-   `play()`
+    Starts playing the sound. If the sound is already playing, it will restart from the beginning.
+
+-   `pause()`
+    Pauses the sound at its current playback position.
+
+-   `stop()`
+    Stops the sound and resets its playback position to the beginning.
+
+-   `setVolume(volume: number)`
+    Sets the volume of the sound. The value will be clamped between 0 and 1.
+
+-   `setLoop(loop: boolean)`
+    Sets whether the sound should loop.
+
+## Examples
+
+### Creating and Playing Background Music
+
+```javascript
+import { GameObject } from './Parts/GameObject';
+import { Sound } from './Parts/Sound';
+
+const backgroundMusic = new GameObject({ name: 'BackgroundMusic' });
+
+backgroundMusic.addChildren(
+    new Sound({
+        name: 'GameMusic',
+        src: './assets/audio/bg_music.mp3',
+        volume: 0.5,
+        loop: true
+    })
+);
+
+// Add the GameObject to a scene (e.g., your main menu scene)
+myMenuScene.addChild(backgroundMusic);
+
+// To start playing the music (e.g., when the scene starts or a button is clicked)
+// You would typically get a reference to the Sound part and call play()
+const musicPart = backgroundMusic.children['GameMusic'] as Sound;
+musicPart.play();
+```
+
+### Playing a Sound Effect on an Event
+
+```javascript
+import { GameObject } from './Parts/GameObject';
+import { Sound } from './Parts/Sound';
+import { Part } from './Parts/Part';
+
+// Assume 'player' is a GameObject
+declare const player: GameObject;
+
+// Add a Sound component for the jump sound effect to the player GameObject
+player.addChild(
+    new Sound({
+        name: 'JumpSound',
+        src: './assets/audio/jump.wav',
+        volume: 0.8,
+        loop: false
+    })
+);
+
+// In a custom PlayerController Part (sibling of the Sound part)
+class PlayerController extends Part {
+    constructor() { super(); this.name = 'PlayerController'; }
+
+    handleJump() {
+        const jumpSound = this.sibling<Sound>('JumpSound');
+        if (jumpSound) {
+            jumpSound.play(); // Play the jump sound
+        }
+    }
+
+    act() {
+        // Example: if jump key is pressed
+        // if (Input.isKeyPressed('Space')) {
+        //     this.handleJump();
+        // }
+    }
+}
+
+player.addChild(new PlayerController());
+```