Create an AudioManager resource.

Create an `AudioManager` resource.

Mục tiêu:

Congratulations on achieving a massive milestone! Your player ship is no longer an abstract white square; it’s a visual entity, rendered from an image file, moving under your complete control. You’ve built a robust, asynchronous asset loading pipeline, which is a cornerstone of any modern game engine. The visual experience is taking shape, but a game world truly comes alive when it has sound.

This brings us to the next great leap for our engine: audio. Just as we needed a central place to store and manage loaded images, we now need a dedicated manager for all things audio-related. This task is about laying that architectural foundation by creating an AudioManager resource, a direct counterpart to the AssetManager you just built.

The Role of the `AudioManager` and the Web Audio API

The AudioManager will serve two primary functions:

Hold the “Audio Device”: In the browser, all audio operations are funneled through a single, powerful object called the AudioContext. It’s the gateway to the Web Audio API, a sophisticated interface for processing and synthesizing audio. Our AudioManager will hold onto this context, making it globally available to any system that needs to play a sound.
Cache Loaded Sounds: Similar to how we cached our HtmlImageElement in the AssetManager, we will load sound files (like .wav or .mp3) once, decode them into a playable format called an AudioBuffer, and store them in a HashMap. This prevents the costly process of re-loading and re-decoding a sound every time it’s played.

This pattern should feel very familiar. We are once again creating a unique, global Resource to manage a specific category of assets.

Step 1: Updating Dependencies in `Cargo.toml`

Before we can write any Rust code, we need to tell web-sys which parts of the Web Audio API we intend to use. This keeps our final Wasm binary lean by only including the bindings we actually need.

Open your Cargo.toml file and add AudioContext and AudioBuffer to the features list for web-sys.

# Cargo.toml

# ... (other sections are unchanged) ...

[dependencies]
# ... (other dependencies are unchanged) ...
web-sys = { version = "0.3", features = [
    'CanvasRenderingContext2d',
    'Document',
    'Element',
    'HtmlCanvasElement',
    'Window',
    'KeyboardEvent',
    'HtmlImageElement',
    'AudioContext', # <-- ADD THIS LINE
    'AudioBuffer',  # <-- AND THIS ONE
]}
# ... (the rest of the dependencies are unchanged) ...

Step 2: Defining the `AudioManager` Resource

Now, let’s define the structure of our new resource. We’ll add this to our resources module, alongside InputState and AssetManager.

Open src/resources.rs and add the AudioManager struct.

// src/resources.rs

use bevy_ecs::prelude::Resource;
use std::collections::HashMap;
use web_sys::{AudioBuffer, AudioContext, HtmlImageElement}; // Add AudioBuffer and AudioContext

// ... (InputState and AssetManager structs are unchanged) ...

// --- NEW CODE STARTS HERE ---

// The AudioManager will be a resource that holds our AudioContext and all
// loaded sound assets, ready to be played.
#[derive(Resource)]
pub struct AudioManager {
    // The AudioContext is the primary interface to the Web Audio API. It represents
    // the audio-processing graph and is required to decode and play sounds.
    pub context: AudioContext,

    // We will store our decoded audio data in a HashMap, just like our images.
    // The key is a String (the asset's path) and the value is the AudioBuffer,
    // which contains the raw, playable sound data.
    pub sounds: HashMap<String, AudioBuffer>,
}

// --- NEW CODE ENDS HERE ---

A Key Difference: No `Default`

You might notice something important is missing: #[derive(Default)]. We cannot use it here. Why? The Default trait is for types that can be created with a sensible “empty” or “zeroed” value. An InputState can default to all keys being false. An AssetManager can default to an empty HashMap.

However, an AudioContext cannot be “defaulted”. It must be actively created by calling a browser API (new AudioContext()), an operation that can potentially fail. Therefore, our AudioManager doesn’t have a default state; it must be constructed manually with a live AudioContext. This is an important lesson in API design: only provide a Default when it makes logical sense.

Step 3: Creating and Inserting the Resource

Since we must manually construct our AudioManager, the Game::new function is the perfect place to do it. We’ll create the AudioContext, use it to build our AudioManager instance, and then insert that instance into the World.

Open src/lib.rs and add the new logic to your Game::new function.

// src/lib.rs

// ... (make sure these types are in your `use` statements at the top)
use web_sys::{AudioContext, HtmlImageElement, KeyboardEvent};
// ...

impl Game {
    pub fn new() -> Self {
        // ... (getting canvas and context is unchanged) ...

        let mut world = World::new();

        // Inserting InputState and AssetManager is unchanged.
        world.insert_resource(InputState::default());
        world.insert_resource(AssetManager::default());

        // --- NEW CODE STARTS HERE ---

        // Create the AudioContext. The `new()` method returns a `Result`, as audio
        // contexts can fail to be created in some browser environments (e.g., if
        // hardware is unavailable or permissions are denied). We use `.expect()`
        // to panic if creation fails, as audio is critical for our engine.
        let audio_context =
            AudioContext::new().expect("Could not create AudioContext");

        // Manually construct our AudioManager instance.
        let audio_manager = AudioManager {
            context: audio_context,
            // We initialize the `sounds` HashMap as empty, ready for loading.
            sounds: HashMap::new(),
        };

        // Insert the newly created AudioManager as a resource into the World.
        world.insert_resource(audio_manager);

        // --- NEW CODE ENDS HERE ---

        // Spawning the player entity remains the same.
        world.spawn((
            // ...
        ));

        // ... (the rest of the function is unchanged) ...
    }
    // ...
}
// ...

You have now successfully created the complete architectural foundation for your engine’s audio system. The AudioManager resource exists in the World, holding a live AudioContext, ready and waiting to be used. The “sound card” is plugged in, and the library for sound effects is built, even though its shelves are currently empty.

Next Steps

With the AudioManager and its AudioContext safely stored as a global resource, we are perfectly positioned for the next task: using that context. In the next step, you will leverage this setup to begin the process of fetching and decoding an actual sound file from the server, preparing it for playback.

Use `web-sys` to get the `AudioContext` from the `window`.

Mục tiêu:

Fantastic! You’ve successfully laid the architectural groundwork for your engine’s audio capabilities. In the previous task, you defined the AudioManager resource, creating a dedicated “warehouse” within your ECS World to hold all things sound-related. That warehouse currently has two parts: an empty HashMap for our future sound effects and, most importantly, a placeholder for the AudioContext.

Our current task is to acquire that AudioContext. This object is the absolute heart of the Web Audio API. It’s not just a simple setting; it is the central controller, the “virtual sound card” for our browser tab, through which all audio will be processed and played. Obtaining it is the critical step that powers up our entire audio engine.

`new()` vs. `get()`: Creating the Audio Graph

While we often “get” things like the document or canvas that already exist on the page, the AudioContext is different. Each web page that wants to use the Web Audio API must create its own, isolated audio environment. Therefore, we don’t get a pre-existing context; we construct a new one.

The web-sys crate provides a direct binding to the JavaScript new AudioContext() constructor. As you implemented in the final part of the previous task, this is done via the AudioContext::new() function. Let’s take a much deeper look at that single, powerful line of code, as it’s the entire solution to this task.

The implementation happens right within your Game::new() function, where all our one-time setup occurs.

// src/lib.rs

// ... (in the impl Game block)
impl Game {
    pub fn new() -> Self {
        // ... (getting canvas and context is unchanged) ...

        let mut world = World::new();

        world.insert_resource(InputState::default());
        world.insert_resource(AssetManager::default());

        // --- HIGHLIGHTED CODE FOR THIS TASK ---

        // Step 1: Call the constructor for the AudioContext.
        // This function can fail if the browser doesn't support the Web Audio API
        // or if certain security policies are in effect. Because of this, `web-sys`
        // correctly returns a `Result<AudioContext, JsValue>`.
        let audio_context =
            AudioContext::new().expect("Could not create AudioContext");

        // Step 2: Manually construct our AudioManager instance.
        let audio_manager = AudioManager {
            context: audio_context, // The context we just created is moved here
            sounds: HashMap::new(),
        };

        // Step 3: Insert the fully constructed resource into the world.
        world.insert_resource(audio_manager);

        // --- END OF HIGHLIGHTED CODE ---

        // ... (spawning the player entity is unchanged) ...

        // ... (rest of the function is unchanged) ...
    }
    // ...
}
// ...

Deconstructing the Code

Let’s dissect this crucial setup logic piece by piece:

AudioContext::new(): This is the web-sys function that calls the JavaScript new AudioContext() constructor. When this line executes, the browser allocates a new audio processing graph. This graph starts simple: it has an input source (where sounds will come from) and a final destination (usually your computer’s speakers), but nothing in between. Our job will be to connect nodes within this graph to play sounds.
-> Result<AudioContext, JsValue>: The new() function returns a Rust Result. This is a core concept in Rust for error handling. It acknowledges that creating an AudioContext is not a guaranteed success. Why could it fail?
- Browser Support: An extremely old browser might not support the API.
- Hardware Issues: The user’s system might not have a functioning audio output device.
- Permissions/Policies: A page running in a restrictive iframe might be blocked from creating an audio context. Rust forces us to handle this possibility, preventing unexpected crashes.
.expect("Could not create AudioContext"): This is our chosen method for handling the Result. expect is a direct, assertive approach. If the Result is Ok(audio_context), it unwraps it and gives us the AudioContext value. If it’s Err(...), the program will immediately panic (a controlled crash) and print the message we provided to the console. For our game engine, the ability to play sound is a non-negotiable, core feature. If we can’t even create the AudioContext, the engine cannot function as designed, so panicking is an appropriate and clear way to signal a fatal setup error.

A Note on Browser Autoplay Policies

Modern web browsers have strict policies against websites playing audio without user interaction. You can’t just have a webpage start making noise the moment it loads. Because of this, when you call AudioContext::new(), the context might start in a “suspended” state.

It will automatically “resume” when audio is triggered by a user event (like a click or keydown). Our current input system handles this perfectly! When we later implement the logic to play a sound inside our PlayerControlSystem (which is driven by key presses), the browser will see that the audio was initiated by a user and will allow the AudioContext to play sound. This is a crucial real-world detail that our engine’s design already handles gracefully.

You have now officially powered on your engine’s audio hardware. The AudioManager resource holds a live, ready-to-use AudioContext, waiting for instructions.

Next Steps

With our virtual sound card active and ready, the next task is to load our first sound effect. We will implement a function to fetch an audio file (like a .wav for a laser blast) from our server as raw binary data, specifically as an ArrayBuffer. This is the first step in the audio loading pipeline, preparing the data for the AudioContext to process.

Implement a function to fetch audio files (`.wav` or `.mp3`) as an `ArrayBuffer`.

Mục tiêu:

You have successfully powered up your engine’s audio system. By creating the AudioManager and initializing the AudioContext, you have a direct line to the browser’s audio hardware. The AudioContext is the “sound card,” and it’s now ready to receive data. Our current task is to fetch that data from the server.

Loading audio is different from loading an image. An image can be represented by an HtmlImageElement, an object with visual properties. Audio, on the other hand, is best treated as pure, raw binary data. We need to fetch the bytes of the .wav or .mp3 file from our server and load them into memory. The standard way to represent a chunk of generic binary data in the browser is with an ArrayBuffer.

To perform this network request, we will use the modern, powerful, and flexible fetch API. And because fetch is an asynchronous, Promise-based API, it is a perfect candidate for the async/await pattern you so brilliantly implemented for image loading. We will create a new async fn load_sound that mirrors the structure of load_image, reinforcing this clean and scalable pattern.

Step 1: Prepare Your Asset and Dependencies

First, you need a sound to load.

Inside your assets directory, place a small sound file. A short .wav file is ideal for sound effects. Let’s assume you’ve added a file named laser_shoot.wav.
Next, we must update our Cargo.toml to give web-sys access to the fetch API components.

Open Cargo.toml and add the new features to the web-sys dependency:

# Cargo.toml

# ... (other sections are unchanged) ...

[dependencies]
# ... (other dependencies are unchanged) ...
web-sys = { version = "0.3", features = [
    'CanvasRenderingContext2d',
    'Document',
    'Element',
    'HtmlCanvasElement',
    'Window',
    'KeyboardEvent',
    'HtmlImageElement',
    'AudioContext',
    'AudioBuffer',
    'Request',        # <-- ADD THIS
    'RequestInit',    # <-- ADD THIS
    'RequestMode',    # <-- ADD THIS
    'Response',       # <-- ADD THIS
]}
# ... (the rest of the dependencies are unchanged) ...

Step 2: Implement the `async fn load_sound` Function

Now we will create a new asynchronous helper function dedicated to loading sound files. Its structure will look very familiar, but instead of creating an HtmlImageElement, it will perform a network fetch request.

Add this new function in src/lib.rs, near your load_image function.

// src/lib.rs

// ... (your existing use statements and functions) ...

// This async function fetches the content of a URL and returns it as a raw ArrayBuffer.
// It's a generic utility for loading any kind of binary data, perfect for our sound files.
async fn load_sound(src: &str) -> Result<js_sys::ArrayBuffer, JsValue> {
    // We create a `RequestInit` object to configure our fetch request.
    // `mode: RequestMode::Cors` is important for requests that might be cross-origin.
    let mut opts = web_sys::RequestInit::new();
    opts.method("GET");
    opts.mode(web_sys::RequestMode::Cors);

    // Create a new `Request` with the URL and options.
    let request = web_sys::Request::new_with_str_and_init(src, &opts)?;

    // Get the global `window` object.
    let window = web_sys::window().unwrap();

    // Call `fetch_with_request`. This returns a JavaScript `Promise` that will
    // resolve to a `Response` object.
    let resp_value = JsFuture::from(window.fetch_with_request(&request)).await?;

    // The `Promise` resolved successfully. We need to cast the `JsValue` to a `Response` type.
    let resp: web_sys::Response = resp_value.dyn_into().unwrap();

    // The `Response` object has a method `.array_buffer()`, which also returns a `Promise`!
    // This second promise resolves to the actual `ArrayBuffer` containing the file's binary data.
    // We await this second promise to get the final result.
    let buffer_value = JsFuture::from(resp.array_buffer()?).await?;

    // The promise resolved, and we have our ArrayBuffer as a JsValue. We cast it and return.
    Ok(buffer_value.dyn_into().unwrap())
}

// ... (your load_image function, run function, etc.) ...

Deconstructing the `fetch` Pipeline

This function is a perfect demonstration of a chained asynchronous operation.

RequestInit and Request: We create a Request object. This is a good practice as it allows for fine-grained control over things like HTTP methods (GET, POST), headers, and CORS (Cross-Origin Resource Sharing) policies.
window.fetch_with_request(&request): This is the call that initiates the network request. It immediately returns a Promise.
JsFuture::from(...).await?: We convert the Promise to a Rust Future and .await its completion. The ? operator will propagate any network errors. The result is a JsValue representing the Response object.
resp.array_buffer()?: Once we have the Response, we call .array_buffer(). This is another asynchronous operation that reads the entire response body from the network stream and converts it into an ArrayBuffer. It, too, returns a Promise.
Awaiting the Second Promise: We again use JsFuture and .await to wait for the body to be fully read. The final result is the ArrayBuffer we need.

Step 3: Trigger the Sound Loading

Now, let’s use our new function. In the run function, inside the spawn_local block, add a call to load_sound. For now, we won’t do anything with the buffer except log a success message. This allows us to confirm our fetch logic is working correctly before moving on.

// src/lib.rs

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    let game = Rc::new(RefCell::new(Game::new()));

    spawn_local(async move {
        // --- Image Loading (unchanged) ---
        let image_src = "assets/player_ship.png";
        let image = load_image(image_src).await.unwrap();

        // --- NEW SOUND LOADING ---
        let sound_src = "assets/laser_shoot.wav";
        match load_sound(sound_src).await {
            Ok(_array_buffer) => {
                // For now, we just log that we successfully fetched the raw data.
                // The `_array_buffer` variable holds our sound data in memory.
                log("Sound file fetched successfully!");
            }
            Err(e) => {
                log(&format!("Error loading sound: {:?}", e));
            }
        }

        // --- Inserting the loaded image (unchanged) ---
        log("Image loaded, inserting into AssetManager.");
        let mut game = game.borrow_mut();
        if let Some(mut asset_manager) = game.world.get_resource_mut::<AssetManager>() {
            asset_manager
                .assets
                .insert(String::from(image_src), image);
        }
    });

    // ... (rest of run function is unchanged) ...
    Ok(())
}

If you build and run your project now, you should see “Sound file fetched successfully!” in your browser’s console after a brief moment. You have successfully fetched the raw binary data of your sound effect and are holding it in Wasm memory.

Next Steps

The raw audio data is now in your hands, but it’s like having a music CD without a CD player. The ArrayBuffer contains the data, but the AudioContext doesn’t know how to interpret it yet. The next critical task is to use the audio_context.decode_audio_data function. This asynchronous method will take our raw ArrayBuffer and transform it into a playable AudioBuffer, the format the Web Audio API understands and can use to generate sound.

Decode Audio Data with Web Audio API in Rust/WASM

Mục tiêu: Modify an asynchronous Rust function to decode raw audio data from an ArrayBuffer into a playable AudioBuffer using the AudioContext.decode\_audio\_data method, handling the asynchronous operation with async/await and JsFuture.

You have successfully fetched the raw, binary essence of your sound file from the server. The ArrayBuffer you now hold in memory is like a tightly sealed package containing all the data for your “laser shoot” sound effect. However, the browser’s audio hardware, represented by the AudioContext, can’t read this package directly. It needs the data to be unwrapped, decoded, and laid out in a format it can understand and send to the speakers.

This crucial “unwrapping” process is the focus of our current task. We will use the AudioContext’s powerful decode_audio_data method. This function takes our raw ArrayBuffer, does the complex work of decompressing and interpreting the audio format (like .wav or .mp3), and gives us back a fully playable AudioBuffer.

Unsurprisingly, this decoding process can take a moment, especially for larger audio files. It is therefore—you guessed it—another asynchronous, Promise-based API. This is a perfect opportunity to further leverage the clean and powerful async/await pattern we’ve established, chaining this new asynchronous step onto our existing load_sound function.

Enhancing `load_sound` to Decode

Our load_sound function is currently good at fetching, but we can make it great by giving it the responsibility of decoding as well. We will upgrade it so that it performs the entire pipeline: fetch the raw data, decode it into a playable format, and return the final, ready-to-use AudioBuffer.

This requires a small but significant change to its signature. To perform the decoding, the function will need access to the AudioContext.

Let’s modify our load_sound function in src/lib.rs.

// src/lib.rs

// ... (your existing use statements and functions) ...

// We've upgraded this function. It now takes a reference to the AudioContext
// and its return type is now a playable `AudioBuffer`.
async fn load_sound(
    audio_context: &web_sys::AudioContext,
    src: &str,
) -> Result<web_sys::AudioBuffer, JsValue> {
    // This first part, fetching the raw data into an ArrayBuffer, is the same.
    let mut opts = web_sys::RequestInit::new();
    opts.method("GET");
    opts.mode(web_sys::RequestMode::Cors);
    let request = web_sys::Request::new_with_str_and_init(src, &opts)?;
    let window = web_sys::window().unwrap();
    let resp_value = JsFuture::from(window.fetch_with_request(&request)).await?;
    let resp: web_sys::Response = resp_value.dyn_into().unwrap();
    let array_buffer_value = JsFuture::from(resp.array_buffer()?).await?;
    let array_buffer: js_sys::ArrayBuffer = array_buffer_value.dyn_into().unwrap();

    // --- NEW DECODING LOGIC STARTS HERE ---

    // Now, we call `decode_audio_data`. This function lives on the AudioContext
    // and takes our ArrayBuffer as input. It returns a JavaScript `Promise`
    // that will resolve to an `AudioBuffer`.
    let audio_buffer_promise = audio_context
        .decode_audio_data(&array_buffer)?;

    // We convert that `Promise` into a Rust `Future` and `.await` it.
    let audio_buffer_value = JsFuture::from(audio_buffer_promise).await?;

    // The future resolved to a JsValue. We cast it to the expected `AudioBuffer` type.
    let audio_buffer: web_sys::AudioBuffer = audio_buffer_value.dyn_into().unwrap();

    // Finally, we return the fully decoded and playable AudioBuffer.
    Ok(audio_buffer)

    // --- NEW DECODING LOGIC ENDS HERE ---
}

// ... (the rest of your file) ...

Deconstructing the Decoding Step

audio_context.decode_audio_data(&array_buffer)?: This is the core of the new logic. We call the method on the AudioContext we passed into the function, giving it a reference to our fetched ArrayBuffer. Like many web-sys functions, it can fail synchronously (e.g., if the buffer is invalid), so it returns a Result. The ? operator handles this for us. The successful result is the Promise that represents the ongoing decoding work.
JsFuture::from(...).await?: This should be a very familiar pattern to you now. We convert the JavaScript Promise into a Rust Future and pause our async function until the decoding is complete. This is the power of async/await—it makes chaining asynchronous operations look like simple, sequential code.
dyn_into().unwrap(): The Future resolves to a generic JsValue. We, the programmers, know that a successful decode_audio_data call will produce an AudioBuffer, so we cast the JsValue to that specific type.

Updating the `run` Function to Use the New Logic

Now that load_sound has been upgraded, we need to update how we call it from our spawn_local block in the run function. Specifically, we need to provide it with the AudioContext.

// src/lib.rs

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    let game = Rc::new(RefCell::new(Game::new()));

    spawn_local(async move {
        // --- Image Loading (unchanged) ---
        let image_src = "assets/player_ship.png";
        let image = load_image(image_src).await.unwrap();

        // --- UPDATED SOUND LOADING ---
        let sound_src = "assets/laser_shoot.wav";

        // We need a reference to the AudioContext to pass to `load_sound`.
        // To get it, we must borrow the game state. We create a new scope `{}` here
        // to ensure that the immutable borrow on `game` is released immediately
        // after we get the AudioBuffer. This is good practice and allows us to
        // get a mutable borrow later without issues.
        let audio_buffer = {
            let game_state = game.borrow();
            let audio_manager = game_state
                .world
                .get_resource::<AudioManager>()
                .expect("AudioManager resource not found");

            // Call our upgraded `load_sound` function.
            load_sound(&audio_manager.context, sound_src)
                .await
                .expect("Failed to load sound")
        };

        // Our sound data is now fully decoded and ready to play!
        log(&format!("Sound '{:?}' decoded successfully!", sound_src));

        // --- Inserting the loaded image (unchanged) ---
        log("Image loaded, inserting into AssetManager.");
        let mut game_state = game.borrow_mut();
        if let Some(mut asset_manager) = game_state.world.get_resource_mut::<AssetManager>() {
            asset_manager
                .assets
                .insert(String::from(image_src), image);
        }
    });

    // ... (rest of run function is unchanged) ...
    Ok(())
}

If you build and run your project now, the console will proudly announce that the sound has been decoded. You have successfully transformed a static file on a server into a dynamic, ready-to-play piece of audio data in your engine’s memory.

Next Steps

The “laser shoot” AudioBuffer now exists, but it vanishes as soon as our async block finishes. It’s like a perfectly tuned instrument that we’ve let fall to the floor. The next logical and final step in our audio loading pipeline is to store this precious, decoded AudioBuffer in our AudioManager’s HashMap. This will cache the sound, making it permanently available for any system in our engine to play on command.

Cache the Decoded AudioBuffer in the AudioManager

Mục tiêu: Modify the asynchronous asset loading block to permanently store the decoded AudioBuffer in the AudioManager’s sounds HashMap, implementing an efficient caching mechanism for audio assets.

Magnificent work! You have navigated the complexities of the web’s asynchronous APIs to create a complete audio loading and decoding pipeline. Your load_sound function is a masterpiece of modern Rust on the web: it fetches raw data using fetch, then hands it off to the AudioContext to be transformed into a playable AudioBuffer. The decoded audio data now exists as a local variable within your async block, a perfectly tuned instrument ready to make noise.

However, an instrument is only useful if it’s kept in the orchestra pit. Right now, this audio_buffer variable is temporary. As soon as the spawn_local task finishes, the buffer will be dropped from memory. If we want to play the laser sound a second time, we’d have to re-fetch and re-decode the entire file, which is incredibly inefficient.

This brings us to the final, crucial step of our loading pipeline: caching the result. We must take our freshly decoded AudioBuffer and give it a permanent home in the AudioManager’s sounds HashMap. This ensures that the expensive work of loading and decoding happens only once, and the sound is instantly available for the lifetime of our game session.

From Temporary Variable to Permanent Asset

This pattern should feel very familiar—it’s the exact same logic we used for storing our loaded HtmlImageElement in the AssetManager. We will get mutable access to our game state, retrieve the AudioManager resource, and insert the new asset.

Let’s modify the spawn_local block in your src/lib.rs file’s run function to perform this final step. We can neatly combine the insertion of both the image and the sound into a single block of code for clarity and efficiency.

// src/lib.rs

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    let game = Rc::new(RefCell::new(Game::new()));

    spawn_local(async move {
        // --- ASSET LOADING ---
        // These sections for loading the image and sound are unchanged.
        // They run concurrently, and we await their results.
        let image_src = "assets/player_ship.png";
        let image = load_image(image_src).await.expect("Failed to load image");

        let sound_src = "assets/laser_shoot.wav";
        let audio_buffer = {
            let game_state = game.borrow();
            let audio_manager = game_state
                .world
                .get_resource::<AudioManager>()
                .expect("AudioManager resource not found");
            load_sound(&audio_manager.context, sound_src)
                .await
                .expect("Failed to load sound")
        };

        log("All assets loaded and decoded successfully.");

        // --- HIGHLIGHTED CHANGES START ---

        // --- ASSET INSERTION ---
        // Now that all assets are loaded and in memory, we get a single mutable
        // lock on the game state to insert them into their respective managers.
        let mut game_state = game.borrow_mut();

        // Insert the loaded image into the AssetManager.
        if let Some(mut asset_manager) = game_state.world.get_resource_mut::<AssetManager>() {
            asset_manager
                .assets
                .insert(String::from(image_src), image);
        }

        // Insert the decoded audio buffer into the AudioManager.
        if let Some(mut audio_manager) = game_state.world.get_resource_mut::<AudioManager>() {
            // We use the same `HashMap::insert` method. The key is the sound's path,
            // and the value is the `AudioBuffer` we just created. The `move` keyword
            // on the `async` block ensures `audio_buffer` is owned here and can be moved
            // into the HashMap.
            audio_manager
                .sounds
                .insert(String::from(sound_src), audio_buffer);
        }

        // --- HIGHLIGHTED CHANGES END ---
    });

    // The rest of the run function (keyboard listeners and game loop setup) remains the same.
    let f = Rc::new(RefCell::new(None));
    // ...
    Ok(())
}

Deconstructing the Code

Architectural Symmetry: Notice the beautiful symmetry between managing images and sounds. We get mutable access to the World, request the appropriate manager resource (AssetManager or AudioManager), and then use the standard HashMap::insert method. This consistent, resource-based architecture is clean, easy to understand, and highly scalable.
game.borrow_mut(): We request write access to our shared game state. This is necessary because inserting into a HashMap modifies it.
world.get_resource_mut::<AudioManager>(): We ask the World for mutable access to our global AudioManager. The if let Some(...) pattern ensures this operation is safe and will only proceed if the resource exists.
audio_manager.sounds.insert(...): This is the final action. We move ownership of our hard-earned audio_buffer into the sounds HashMap, using its file path as the unique key. From this moment on, the decoded laser sound is a permanent, first-class citizen of our ECS World.

With this change, your audio loading pipeline is now complete and robust. You have a system that can fetch any sound file, decode it into a playable format, and safely store it for later use, all without blocking the main game loop.

Next Steps

The instrument has been tuned and placed in the orchestra pit, ready for the conductor’s signal. Our AudioBuffer is safely cached in the AudioManager. The next logical and exciting task is to play it! You will create a play_sound method on the AudioManager. This method will look up a buffer from the HashMap, use it to create an AudioBufferSourceNode (the Web Audio API’s equivalent of “hitting a key on a sampler”), connect that node to the speakers, and start the playback, finally giving your game a voice.

Implement Audio Playback with the Web Audio API

Mục tiêu: Implement the play\_sound method on an AudioManager struct in Rust. This task involves using the Web Audio API’s audio graph to create a source node, connect it to the destination, and start playback for a cached AudioBuffer.

You have masterfully orchestrated the entire audio loading pipeline. A raw sound file from your server has been fetched, decoded into a high-fidelity format, and is now safely cached as an AudioBuffer in your AudioManager. The instrument is perfectly tuned and sits ready in the orchestra pit. All that’s left is for the conductor to give the signal.

This task is about becoming that conductor. We will implement the play_sound method, the core function that transforms our stored audio data into actual sound waves that reach the player’s ears. This is where your game will finally get its voice.

Understanding the Web Audio API Graph

Before we write the code, it’s crucial to understand the mental model of the Web Audio API. It’s not as simple as calling a single play() function. Instead, it operates on the concept of an audio routing graph. Think of it like a guitarist’s effects pedal board:

The Source: You have a source of sound (the guitar). In our case, this will be an AudioBufferSourceNode. This node is like a temporary “CD player” that we load our AudioBuffer “CD” into.
The Destination: You have a final output (the amplifier and speaker). In the browser, this is a special node on our AudioContext called destination.
The Connection: You use a cable to connect the guitar to the amplifier. In our code, we will explicitly connect our source node to the destination node.

Crucially, an AudioBufferSourceNode is a one-shot object. Once it has finished playing its buffer, it’s exhausted and cannot be used again. To play the same sound twice, you must create a new source node, connect it, and start it. Our play_sound method will encapsulate this entire “create, connect, play” process.

Implementing the `play_sound` Method

The most idiomatic and organized place for this logic is within an impl block for our AudioManager struct. This directly associates the “play sound” behavior with the data it needs (the context and the sounds HashMap).

Let’s open src/resources.rs and add this implementation right after the AudioManager struct definition.

// src/resources.rs

// ... (your existing use statements and struct definitions are unchanged) ...

#[derive(Resource)]
pub struct AudioManager {
    pub context: AudioContext,
    pub sounds: HashMap<String, AudioBuffer>,
}

// --- NEW CODE STARTS HERE ---

// We implement methods directly on our AudioManager struct.
// This is a clean, object-oriented approach that keeps our code organized.
impl AudioManager {
    // This method takes an immutable reference to self (`&self`) because it doesn't
    // need to *change* the AudioManager (we're just reading from it). It also
    // takes the key of the sound we want to play.
    pub fn play_sound(&self, key: &str) {
        // Step 1: Look up the requested AudioBuffer in our HashMap.
        // The `get` method returns an `Option<&AudioBuffer>`. If the key doesn't
        // exist, it returns `None`. The `if let Some(...)` pattern is the perfect,
        // safe way to handle this, preventing a panic if we ask for a sound
        // that hasn't been loaded or doesn't exist.
        if let Some(buffer) = self.sounds.get(key) {
            // Step 2: Create an AudioBufferSourceNode.
            // This is our temporary, one-shot "player" for the sound. The
            // `create_buffer_source` method can fail, so it returns a `Result`.
            // We `.expect` a success, as failure here would indicate a major
            // problem with the AudioContext.
            let source = self
                .context
                .create_buffer_source()
                .expect("Could not create buffer source");

            // Step 3: Assign our loaded buffer to the source node.
            // This effectively "loads the CD into the CD player".
            source.set_buffer(Some(buffer));

            // Step 4: Connect the source node to the destination (the speakers).
            // This creates the "cable" in our audio graph, routing the output
            // of our source node to the final output of the AudioContext.
            // This method also returns a `Result`.
            source
                .connect_with_audio_node(&self.context.destination())
                .expect("Could not connect source to destination");

            // Step 5: Start playback.
            // The `start()` method schedules the sound to be played immediately.
            // After this call, the audio processing happens in a separate thread,
            // managed by the browser, so it doesn't block our game loop.
            source.start().expect("Could not start playback");

            // At this point, `source` goes out of scope. Rust drops it, but that's okay!
            // The Web Audio API has already been instructed to play the sound. The node
            // will be garbage-collected by the browser once it finishes playing.
        } else {
            // It's good practice to log when an asset is missing.
            log(&format!("Sound key not found in AudioManager: {}", key));
        }
    }
}

// --- NEW CODE ENDS HERE ---

Deconstructing the Code

You have just written a complete, self-contained function for playing any sound you’ve loaded. Let’s break down its key components:

if let Some(buffer) = self.sounds.get(key): This is the gatekeeper. The entire process only happens if the requested sound has been successfully loaded and stored in our AudioManager. This makes the function robust against typos or timing issues.
self.context.create_buffer_source(): This is the factory for our sound player. We ask the main AudioContext to create a new source node for us.
source.set_buffer(Some(buffer)): This method links our decoded audio data (buffer) with the player (source).
source.connect_with_audio_node(&self.context.destination()): This is the essential routing step. It establishes the path from our sound’s source all the way to the user’s speakers. Without this connection, the sound would play into a void and never be heard.
source.start(): This is the final command. It tells the browser’s audio engine to schedule the playback. You can also pass a time argument to schedule playback in the future, which is useful for rhythm games or synchronizing audio to animations.

You have now armed your AudioManager with the ability to play any sound in its library on command. The “conductor” is ready and knows the score.

Next Steps

The play_sound method is a perfectly crafted tool, but a tool is useless until it’s picked up and used. It currently sits dormant inside your AudioManager. The final, thrilling task of this audio step is to trigger this method from within another system. You will modify a system, like the PlayerControlSystem, to call audio_manager.play_sound("assets/laser_shoot.wav") in response to a player action, finally hearing the satisfying “zap” of your laser in the game.

Triggering a Laser Sound on Key Press

Mục tiêu: Connect the game’s input system to the audio manager. This task involves modifying the keydown event listener to detect a spacebar press, which then calls the play_sound method to trigger a laser sound effect.

You have assembled a complete, robust audio loading pipeline and crafted the perfect tool for playback: the play_sound method. Your AudioManager is fully equipped, holding a library of decoded sounds, ready to bring your game world to life. Yet, for all this power, the world remains silent. The final, crucial step is to connect this audio capability to the game’s logic, to give the player an action that elicits a sound reaction.

This task is all about that connection. We will make the player’s ship “speak” by firing its laser, accompanied by the satisfying sound effect you’ve so carefully prepared.

Choosing the Right Trigger Point

Where in our code should we call play_sound? We could put it in a system like PlayerControlSystem, but that system runs on every single frame. If we played a sound there, it would trigger 60 times per second, creating a horrible continuous buzz. What we need is a way to detect a single, discrete event: the moment a key is pressed.

The perfect place for this is the keydown event listener we’ve already built in our run function. This closure executes only once when a key is first pressed down, making it the ideal trigger for a one-shot sound effect like a laser blast.

Step 1: Add a “Shoot” Action to the Input State

First, let’s make our “shoot” action a formal part of our game’s state. We’ll use the Spacebar for this action.

Open src/resources.rs and add a new boolean field to your InputState struct.

// src/resources.rs

// ... (other use statements)

#[derive(Resource, Default)]
pub struct InputState {
    pub up_pressed: bool,
    pub down_pressed: bool,
    pub left_pressed: bool,
    pub right_pressed: bool,
    // --- NEW CODE STARTS HERE ---
    pub shoot_pressed: bool, // Will be true when the spacebar is held down
    // --- NEW CODE ENDS HERE ---
}

// ... (AssetManager and AudioManager are unchanged)

Step 2: Wire Up the Spacebar and Play the Sound

Now for the main event. We will modify our keydown and keyup closures in src/lib.rs. When the spacebar is pressed, we will not only update our InputState but also immediately get the AudioManager resource and call our play_sound method.

Navigate to the run function in src/lib.rs and update your event listener closures.

// src/lib.rs

// ... (in the `run` function)

    // --- KEYDOWN EVENT LISTENER ---
    {
        let game = game.clone();

        let keydown_closure = Closure::<dyn FnMut(_)>::new(move |event: KeyboardEvent| {
            let mut game = game.borrow_mut();

            if let Some(mut input_state) = game.world.get_resource_mut::<InputState>() {
                match event.key().as_str() {
                    "ArrowUp" => input_state.up_pressed = true,
                    "ArrowDown" => input_state.down_pressed = true,
                    "ArrowLeft" => input_state.left_pressed = true,
                    "ArrowRight" => input_state.right_pressed = true,

                    // --- HIGHLIGHTED CHANGES START ---

                    // Handle the Spacebar for shooting
                    " " => {
                        // We only want to play the sound on the initial key press,
                        // not every frame it's held down. This is why we do it here.
                        // First, check if the key was not already pressed to avoid
                        // re-triggering from keyboard auto-repeat.
                        if !input_state.shoot_pressed {
                            // Get immutable access to the AudioManager resource.
                            if let Some(audio_manager) = game.world.get_resource::<AudioManager>() {
                                // Call the method we built in the previous task!
                                audio_manager.play_sound("assets/laser_shoot.wav");
                            }
                        }
                        // Now, set the state to true.
                        input_state.shoot_pressed = true;
                    }

                    // --- HIGHLIGHTED CHANGES END ---

                    _ => {}
                }
            }
        });

        window
            .add_event_listener_with_callback("keydown", keydown_closure.as_ref().unchecked_ref())
            .unwrap();

        keydown_closure.forget();
    }

    // --- KEYUP EVENT LISTENER ---
    {
        let game = game.clone();

        let keyup_closure = Closure::<dyn FnMut(_)>::new(move |event: KeyboardEvent| {
            let mut game = game.borrow_mut();
            if let Some(mut input_state) = game.world.get_resource_mut::<InputState>() {
                match event.key().as_str() {
                    "ArrowUp" => input_state.up_pressed = false,
                    "ArrowDown" => input_state.down_pressed = false,
                    "ArrowLeft" => input_state.left_pressed = false,
                    "ArrowRight" => input_state.right_pressed = false,

                    // --- NEW CODE STARTS HERE ---
                    " " => input_state.shoot_pressed = false, // Reset the shoot state on release
                    // --- NEW CODE ENDS HERE ---

                    _ => {}
                }
            }
        });

        window
            .add_event_listener_with_callback("keyup", keyup_closure.as_ref().unchecked_ref())
            .unwrap();

        keyup_closure.forget();
    }

// ... (rest of the `run` function is unchanged)

Deconstructing the Code

This change beautifully ties together several parts of your engine:

" ": The event.key() for the spacebar is a simple string containing a single space. This is how we identify the key press.
if !input_state.shoot_pressed: This is a subtle but important check. Some operating systems will repeatedly fire keydown events if a key is held down (auto-repeat). By checking if we’ve already registered the key as pressed, we ensure our sound only plays on the very first press, not on the auto-repeated events.
game.world.get_resource::<AudioManager>(): Inside our closure, we already have mutable access to the game state. From there, we can ask the world for immutable (read-only) access to the AudioManager. This is perfectly safe and allowed by Rust’s borrow checker. We only need read access because our play_sound method takes &self.
audio_manager.play_sound(...): This is the payoff. We call the method we built, providing the exact same asset key we used when loading the sound. The AudioManager looks up the AudioBuffer and schedules it for immediate playback.

Build and Fire!

This is the moment. Rebuild your project and refresh the browser.

wasm-pack build --target web

Your ship appears on screen. Move it around. Now, press the Spacebar.

You should hear the crisp, satisfying sound of your laser firing. You have successfully integrated your audio engine with your input system, giving your game world a new dimension of interactive feedback.

Next Steps

Congratulations on completing the entire audio engine step! Your game now has visuals, control, and sound—the foundational pillars of any interactive experience.

The world, however, still feels a bit ethereal. Your ship can fly through anything, and nothing interacts with anything else. The next great frontier is physics. In Step 8: Implementing Collision Detection, you will build the systems that allow entities to occupy space and detect when they overlap. This will pave the way for making a real game where paddles can hit balls and lasers can destroy asteroids.