Safi Engine

    Audio Scripting

    Headers: Core/include/Core/AudioEngine.h, Core/include/Core/AudioComponents.h

    AudioSource Component

    Attach to any entity to make it a sound emitter:

    FieldTypeDefaultDescription
    clipPathstd::string""Path to audio file (.wav, .mp3, .ogg)
    volumefloat1.0Volume (0.0 = silent, 1.0 = full)
    pitchfloat1.0Pitch modifier
    loopboolfalseLoop playback
    spatialbooltrueEnable 3D spatial audio
    playOnAwakeboolfalseAuto-play when play mode starts

    AudioListener Component

    A tag component that marks which entity "hears" 3D audio. Typically attached to the main camera:

    // The AudioListener has no fields — it's just a marker
e.set(AudioListener{});
    Tip

    Attach AudioListener to your main camera entity so 3D sounds are heard from the player's perspective.

    Playing Sounds from Behaviors

    Use the AudioEngine directly for one-shot sounds:

    void OnUpdate(flecs::entity e, Engine &engine, float dt) override {
  auto &input = engine.GetInput();

  if (input.IsKeyPressed(GLFW_KEY_SPACE)) {
    engine.GetAudioEngine().Play("assets/sounds/jump.wav", 0.8f);
  }
}

    AudioEngine API

    MethodDescription
    Play(path, volume, loop)Play a sound file
    StopAll()Stop all playing sounds
    SetListenerPosition(x, y, z)Set 3D listener position
    SetListenerDirection(x, y, z)Set 3D listener facing direction

    3D Spatial Audio

    For sound that changes based on distance and direction:

    1. Add AudioSource to the sound-emitting entity with spatial = true
    2. Add AudioListener to the camera or player entity
    3. The engine automatically updates listener position from the entity's Transform
    // Example: footstep sounds on the player
void OnUpdate(flecs::entity e, Engine &engine, float dt) override {
  // Update listener position for 3D audio
  const auto *t = e.get<Transform>();
  if (t) {
    engine.GetAudioEngine().SetListenerPosition(
        t->position.x, t->position.y, t->position.z);
  }
}