dot big bang

Developer API
Menu

Class SoundComponent

All
  • Public
  • Public/Protected
  • All

Hierarchy

Index

Constructors

constructor

Properties

gain

gain: number

The gain to apply to the Sound clip audio playback. The gain is a multiplying factor applied to each sample of the Sound when it is played. A value of 1 plays the Sound at its natural level while a value of 0.5 will half each sample causing the audio to appear quieter. Note that large gain values make the audio louder but eventually cause a waveform distortion called "clipping" where the result of the multiplication of the sample value with the gain "saturates" to the maximum value supported by the audio system.

Readonly id

id: string

The 36-character identifier string of the Component. The id is unique within the Entity is belongs to. Currently, the same id may be used by another Component on a different Entity.

loop

loop: boolean

Setting the loop property causes playback of the region of the Sound defined by loopStart and loopEnd to continue indefinitely once any part of the looped region is played.

loopEnd

loopEnd: number

The time, in seconds, from the start of the Sound clip where the loop region ends (see loop property).

loopStart

loopStart: number

The time, in seconds, from the start of the Sound clip where the loop region starts (see loop property).

pitch

pitch: number

The pitch (or playback speed) to apply to the Sound clip audio playback. The pitch is a multiplier applied to the playback speed of the Sound when it is played. A value of 1 means normal speed while a value of 0.5 means half speed, or a lower pitch. A value of 2.0 means double speed, or a higher pitch. The value must be in the range (0.0, 8.0].

soundClip

soundClip: null | Sound

The Sound clip to play.

Readonly type

The type of the Component.

Accessors

entity

  • Gets the Entity the Component is part of. This throws an exception if the Component is not in an Entity. Use the isInEntity property to test for that.

    Returns Entity

game

  • Gets the Game the Component is part of (via the Entity it belongs to). This throws an exception if the Component is not in the game. Use the isInGame property to test for that.

    Returns Game<{ saveData: SaveData<any, any> }>

isInEntity

  • get isInEntity(): boolean
  • Returns true if the Component is part of an Entity.

    Returns boolean

isInGame

  • get isInGame(): boolean
  • Returns true if the Component is part of the Game (via the Entity it belongs to).

    Returns boolean

isPlaying

  • get isPlaying(): boolean
  • Indicates whether the Sound clip is currently being played.

    Returns boolean

Methods

play

  • play(offset?: number): void
  • Starts playing the Sound clip from the specified time offset, in seconds. Calling start while the Sound is already playing stops current playback and starts it again at the specified offset.

    Parameters

    • Optional offset: number

      The time offset, in seconds from the beginning of the Sound, at which to start playback.

    Returns void

playFromEntity

  • playFromEntity(offset?: number, rolloffFactor?: number, refDistance?: number, maxDistance?: number, distanceModel?: SoundDistanceModel, stopPolicy?: SoundStopPolicy): void
  • Starts playing the Sound clip from the specified time offset, in seconds. Calling start while the Sound is already playing stops current playback and starts it again at the specified offset.

    Parameters

    • Optional offset: number

      The time offset, in seconds from the beginning of the Sound, at which to start playback.

    • Optional rolloffFactor: number

      Describes how quickly gain should be reduced when moving away from the listener. Its range depends on the distanceModel used (negative values are not allowed).

      • SoundDistanceModel.Linear: The range is 0 to 1.
      • SoundDistanceModel.Inverse: The range is 0 to Infinity.
      • SoundDistanceModel.Exponential: The range is 0 to Infinity. Default value: 1.0
    • Optional refDistance: number

      The distance from position within which the sound will be at normal gain. Must be a non-negative number. Default value: 300

    • Optional maxDistance: number

      Represents the maximum distance between the audio source and the listener, outside which the gain is not reduced any further. This property is only used when using SoundDistanceModel.Linear for distanceModel. Must be a positive non-zero number. Default value: 800

    • Optional distanceModel: SoundDistanceModel

      Specifies how the Sound's gain should change based on its distance from the audio listener. Default value: SoundDistanceModel.Linear

    • Optional stopPolicy: SoundStopPolicy

    Returns void

stop

  • stop(finishPlaying?: boolean): void
  • Stops playing the Sound clip. Calling stop if the Sound isn't beeing played, has no effect.

    Parameters

    • Optional finishPlaying: boolean

      If true, loop is disabled and the Sound gets played to its end. If loop was not set in the first place, stop(true) has effectively no effect.

    Returns void