kitten/sound

This module defines functions for working with sound effects. Kitten supports two sound systems:

• ZzFX + ZzFXM by Frank Force and Keith Clark
• the usual Web Audio API (so far only tested with .mp3’s, but other files should work too)

Once the sounds have been loaded into the engine, you can usee the same functions to initiate, play and stop them, regardless of original format.

To load sounds into the engine, you will need to specify paths to the files containing them (relative to your index.html) as strings in the sound_sources list when starting the engine. ZzFX(M) sounds must be stored as .js files; I highly recommend that you use their websites (ZzFX, ZzFXM) to create the sounds and then copy the JavaScript output.

To use the sounds in your game, use the new function in this module, passing the index of the desired sound file in the sound_sources list as the argument. The function is fallible and will only work if the sound file exists and was correct (although I am still figuring out the details). For this reason, you should only use it in your init function with an assert assignment, and store the result in your model. This way, you can be sure that if the game starts without errors, the sounds were loaded correctly.

Note that due to browser security restrictions, you will need some user interaction before playing a sound. In my testing with Firefox, it was sufficient that the user had pressed a key or clicked with their mouse at any point before the sound was played.

Example:

pub fn main() {
  canvas.start_fullscreen(init, update, view, "canvas", [], ["jump.js", "powerup.mp3"])
}

fn init() {
  let assert Ok(jump_sound) = sound.new(0)
  let assert Ok(powerup_sound) = sound.new(1)
  Model( 
    // ... 
    jump_sound:,
    powerup_sound:,
  )
}

fn update(model: Model) {
  // ... 
  case player_has_jumped {
    True -> sound.play(model.jump_sound)
    False -> Nil
  }
  case player_has_powered_up {
    True -> sound.play(model.powerup_sound)
    False -> Nil
  }
 // ...
}

pub opaque type Sound

pub fn new(id: Int) -> Result(Sound, Nil)

pub fn play(sound: Sound) -> Nil

pub fn stop() -> Nil