LogoLogo
  • Get Started
  • Getting Started
    • Initial Setup
    • Create Your First Game
    • API Reference
    • Build Your First World Map
    • Multiplayer Testing
    • Use Templates & Examples
    • Styling & Assets
      • Modeling Guidelines
      • Texturing Guidelines
      • Default Assets
  • Build Faster With AI Tools
  • SDK Guides
    • Assets
    • Audio & SFX
      • Audio Manager
    • Blocks & Chunks
      • Block Types
      • Block Type Registry
      • Chunks
      • Chunk Lattice
    • Camera
    • Chat & Commands
    • Debugging
    • Entities
      • Animations
      • Block Entities
      • Colliders & Hitbox
      • Child Entities
      • Entity Controllers
        • Base Entity Controller
        • Pathfinding Entity Controller
        • DefaultPlayer Entity Controller
        • Simple Entity Controller
      • Entity Manager
      • Model Entities
      • Movement & Pathfinding
      • Player Controlled Entities
    • Events
    • Input & Controls
    • Lighting
      • Ambient Light
      • Light Manager
      • Point Lights
      • Spot Lights
      • Sun Light (Directional)
    • Mobile
    • Persisted Data
    • Players
      • Player Manager
      • Persisted Player Data
    • Plugins
    • Physics
      • Colliders
      • Collision Groups
      • Debugging
      • Gravity
      • Raycasts
      • Rigid Bodies
    • User Interface
      • Overlay UI
      • Scene UIs
      • Scene UI Manager
    • Worlds
      • Map Data Format
  • Helpful Resources
    • HYTOPIA Architecture & Platform Overview
    • Useful Third-Party Tools
Powered by GitBook
On this page
  • Playing Ambient Audio
  • Playing Spatial Audio
  • Controlling Playback & Effects
  • Diving Deeper
  • Next Steps
Export as PDF
  1. SDK Guides

Audio & SFX

PreviousAssetsNextAudio Manager

Last updated 3 months ago

Music and sound effects are a key piece to any enjoyable game. The allows you to create and control playback of both ambient and spatial music and sound effects seamlessly within your game.

Playing Ambient Audio

Audio supports a number of features, but let's start with the simplest. Let's say we want to just play some nice ambient music for all of our players. We can do that like so:

startServer(world => {
  // ... Rest of our game setup code
  
  const gameMusic = new Audio({
    uri: 'audio/music/ambience.mp3',
    loop: true, // Loop the music when it ends
    volume: 0.5, // Relative volume 0 to 1
  });
  
  gameMusic.play(world); // Play the music in our world
      
  // ... More game setup code, ordering doesn't matter for Audio
})

Playing Spatial Audio

Oftentimes in games we need to play spatial audio that originates at some point in 3D space of the game, either from a specific coordinate or an entity. In this example, let's play some audio that constantly originates from each player and starts playing when a player joins the game.

startSever(world => {
  // ... Other game code
  
  world.on(PlayerEvent.JOINED_WORLD, ({ player }) => {
    const playerEntity = new PlayerEntity({
      player,
      modelUri: 'models/players/player.gltf', // resolves to assets/models/player.gltf
      modelLoopedAnimations: [ 'idle' ],
      modelScale: 0.5,
    });
    
    const playerSirenAudio = new Audio({
      uri: 'audio/sfx/siren.mp3',
      loop: true, // We could omit loop: true if we want this to be a one-shot, only playing once
      volume: 1, // loud, volume is 0 (ie 0%) to 1 (ie 100%)!
      attachedToEntity: playerEntity,
      // reference distance is the approximate block distance
      // a player can be to start hearing the audio, as they 
      // get closer to the source it'll get louder, up to the
      // volume value.
      referenceDistance: 20,
      // alternatively, we can have this audio spatially emit
      // from a fixed position by removing our attachedToEntity
      // value and instead providing
      // position: { x: 1, y: 5, z: 4 } 
    });
    
    playerSirenAudio.play(world);
  });
  
  // ... Other game code
});

Controlling Playback & Effects

Most audio playback settings and effects can be controlled while Audio is already playing. Effects will automatically be interpolated by the client for smooth transitions between effects. This means you can do interesting things like adjust playback speed, distortion, detune, volume, and more while audio plays.

Here's an example of how we can continuously speed up our audio playback of our game music over time.

startServer(world => {
  // ... Rest of our game setup code
  
  const gameMusic = new Audio({
    uri: 'audio/music/ambience.mp3',
    loop: true, // Loop the music when it ends
    volume: 0.5, // Relative volume 0 to 1
  });
  
  gameMusic.play(world); // Play the music in our world
  
  setInterval(() => {
    gameMusic.setPlaybackRate(gameMusic.playbackRate + 0.1);
  }, 1000); // Every 1 second (1000 milliseconds), increase speed!
      
  // ... More game setup code, ordering doesn't matter for Audio
})

Diving Deeper

Next Steps

The Audio class supports a wide variety of features and control through various exposed properties and methods. If you'd like to learn more, we recommend digging into the .

If there are features that we don't currently support for Audio that you'd like to see added to the HYTOPIA SDK, you can .

Audio class
Audio API Reference that can be found here
submit a feature request here

Audio Manager

Documentation of the AudioManager, used to iterate and search all audio.

Audio API Reference

Learn more about the properties and methods exposed by the Audio class.