engineAudioUpdater.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file engineAudioUpdater.h
//! \brief Defines the DtEngineAudioUpdater component for simulating vehicle engine sounds.
//!
//! This component provides dynamic audio simulation for vehicle engines, modulating sound pitch
//! and volume based on engine RPM or speed values from state attributes.
//!
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
#include "vrePlayerStation/playerComponent.h"
 
#include <vector>
 
//! \brief Component configuration and usage details
//!
//! The DtEngineAudioUpdater plays audio sounds for the engaged entity based on the value
//! of a floating point state attribute (typically RPM or speed). The state attribute value
//! modulates the pitch and gain of the sound to create realistic engine effects.
//!
//! Features:
//! - Uses state attributes (RPM or speed) to control sound pitch and volume
//! - Applies smoothing to prevent jitter in pitch changes
//! - Controls multiple engine sounds with different characteristics
//! - Positions sounds at the entity's location for 3D audio effects
//! - Supports engine on/off state via a boolean attribute
//!
//! Entities need to have a boolean state attribute to represent the engine being on/off.
//! The default attribute name is "engine-on" but can be changed in the configuration.
//! If this attribute is false, engine audio sounds will not play.
//!
//! \par Example Configuration:
//! \code
//! ["engineAudio"] = {
//!    componentType = "DtEngineAudioUpdater";
//!    priority = 10;
//!    audioPath = "$(DATA_DIR)\\audio\\sounds\\";
//!    engineOnAttribute = "engine-on"; -- can also use "engineOnName" for compatibility
//!    sources = {
//!       {
//!         audioFile = "tankEngine.wav",      -- can also use "audio" for compatibility
//!         rpmAttribute = "rpm",            -- can also use "stateAttribute" for compatibility
//!         rpmMax = 3100,                  -- can also use "maxValue" for compatibility
//!         rpmSmoothing = 0.999,           -- can also use "lowpassAlpha" (1.0 - smoothing) for compatibility
//!         minPitch = 0.1,                 -- minimum pitch scaling (default: 0.1)
//!         maxPitch = 1.0,                 -- maximum pitch scaling (default: 1.0)
//!         gain = 0.75,                    -- volume multiplier (default: 1.0)
//!         decibels = 70.0                 -- sound level in decibels (default: 80.0)
//!       },
//!       {
//!         audioFile = "tank.wav",
//!         rpmAttribute = "speed",
//!         rpmMax = 45,
//!         rpmSmoothing = 0.925,
//!         decibels = 80.0
//!         -- gain defaults to 1.0
//!       }
//!    };
//! };
//! \endcode
 
namespace makAudio
{
//! \brief Forward declaration of the audio sound class
class DtSound;
} // namespace makAudio
 
namespace EngineAudioUpdaterConfig
{
//! \ingroup RoleConfigParams
//! \defgroup EngineAudioUpdaterRoleParams Engine Audio Updater Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for engine audio updater role.
//! @{
 
//! \vreRoleParam{audioPath,string,"$(SHARED_DATA_DIR)/Audio/",engineAudioUpdater,Base path for locating audio files.}
constexpr const char* audioPath = "audioPath";
 
//! \vreRoleParam{engineOnAttribute,string,"engine-on",engineAudioUpdater,Name of the boolean state attribute that controls engine on/off state.}
constexpr const char* engineOnAttribute = "engineOnAttribute";
 
//! \vreRoleParam{engineOnName,string,"engine-on",engineAudioUpdater,Legacy name for the engine on/off attribute (use engineOnAttribute instead).}
constexpr const char* engineOnName = "engineOnName";
 
//! \vreRoleParam{sources,table,"",engineAudioUpdater,Table of engine audio sources with RPM-based modulation settings.}
constexpr const char* sources = "sources";
 
//! @}
} // namespace EngineAudioUpdaterConfig
 
namespace makVre
{
//! \brief Type identifier for DtEngineAudioUpdater component
constexpr const char* DtEngineAudioUpdaterType = "DtEngineAudioUpdater";
 
//! \brief Component for simulating vehicle engine sounds
//!
//! The DtEngineAudioUpdater provides realistic audio simulation for vehicle engines.
//! It dynamically modulates sound pitch and volume based on engine RPM or speed values,
//! applies smoothing to prevent jitter, and positions sounds in 3D space based on
//! the entity's location.
//!
//! The component supports multiple engine sounds with different characteristics
//! and can tie sound playback to an engine on/off state attribute.
class VRECOMMONCOMPONENTS_DLL DtEngineAudioUpdater : public DtPlayerComponent
{
public:
   //! \brief Constructor for DtEngineAudioUpdater
   //!
   //! Initializes the component with the name "DtEngineAudioUpdater".
   DtEngineAudioUpdater();
 
   //! \brief Virtual destructor for DtEngineAudioUpdater
   //!
   //! Ensures proper cleanup of audio resources when the component is destroyed.
   virtual ~DtEngineAudioUpdater() override;
 
   //! \brief Initializes the component with configuration from Lua
   //!
   //! Sets up audio sources based on the provided configuration. Each source is configured
   //! with its associated RPM attribute, maximum RPM value, pitch range, smoothing factor,
   //! gain, and decibel level.
   //!
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing initialization parameters, especially the sources table
   //! \return True if initialization succeeds, false otherwise
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Updates the audio playback based on RPM state attributes
   //!
   //! Called each frame to manage audio playback. For each configured sound:
   //! - Reads the associated RPM attribute value
   //! - Normalizes the value based on the maximum RPM
   //! - Applies smoothing to reduce jitter
   //! - Calculates and sets pitch and gain values
   //! - Updates the sound position to match the entity's location
   //!
   //! \param dt Delta time in seconds since the last tick
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the component
   //!
   //! Cleans up all audio resources by stopping and deleting sounds.
   virtual void shutdown() override;
 
   //! \brief Returns the type identifier for this component
   //! \return The type string for DtEngineAudioUpdater
   virtual const char* type() const override;
 
protected:
   //! \brief Name of the state attribute that indicates if the engine is on
   //!
   //! This attribute controls whether engine sounds are played at all.
   //! Default is "engine-on" but can be changed via configuration.
   std::string myEngineOnAttributeName;
 
   //! \brief Structure for managing engine sound resources and their parameters
   struct EngineSound
   {
      //! \brief Name of the state attribute providing RPM/speed values
      //!
      //! This attribute's value is used to modulate sound pitch and gain.
      std::string myRpmAttributeName;
 
      //! \brief Pointer to the audio sound resource
      makAudio::DtSound* myDtSound;
 
      //! \brief Maximum expected RPM/speed value
      //!
      //! Used to normalize the RPM value to a 0.0-1.0 range.
      float myRpmMax;
 
      //! \brief Maximum pitch scaling factor
      //!
      //! Applied when the normalized RPM value is 1.0 (maximum).
      float myMaxPitch;
 
      //! \brief Minimum pitch scaling factor
      //!
      //! Applied when the normalized RPM value is 0.0 (idle).
      float myMinPitch;
 
      //! \brief Previously calculated normalized RPM value
      //!
      //! Used for smoothing between frames to reduce jitter.
      float myPreviousNormalizedRpm;
 
      //! \brief Smoothing factor for RPM changes
      //!
      //! Value between 0.0 (no smoothing) and 0.99 (maximum smoothing).
      //! Higher values result in slower response to RPM changes.
      double mySmoothing;
   };
 
   //! \brief Collection of engine sounds managed by this component
   std::vector<EngineSound> myEngineSounds;
};
} // namespace makVre