easy_bass.txt

--@name Easy Bass
--@author legokidlogan
--@client

easyBass = easyBass or {}

if easyBass._alreadyLoaded then return end
easyBass._alreadyLoaded = true


local allBassObjs = {}
local soundIDIncrement = 0

local realtime = timer.realtime

local handleFollowTarget
local handleDestroyWhenDone
local handleFadeInOut
local loadBass


--[[
    - Creates a bassObj from a clientside game sound file.
    - callback behaves identically to the callback in bass.loadFile.
    - failCallback receives errNum, errName, nonBassErr as arguments if the sound fails to load.
        - Return true to automatically retry the sound.
        - If failCallback is not provided, the sound will always be retried.

    - settings: A table of settings for the sound. All settings are optional, and will default to the following if not specified:
        {
            Flags = "3d stereo noblock noplay", -- Flags to pass to bass.loadFile.
            Volume = 1, -- Volume to play the sound at.
            Pitch = 1, -- Pitch to play the sound at.
            FadeStart = 700, -- Distance at which the sound starts to fade.
            FadeEnd = 2000, -- Distance at which the sound is completely silent.
            UseSimpleFading = true, -- Whether or not to use simple distance fading. See Bass:setFade() in the starfall docs for more info.
            FadeIn = 0, -- Time in seconds to fade in the sound.
            FadeOut = 0, -- Time in seconds from the end to fade out the sound. Disabled if Duration is not given.
            Duration = nil, -- Duration of the sound in seconds. If nil, the duration will be automatically calculated.
            Target = chip(), -- The entity or vector to play the sound at.
            Loop = false, -- Whether or not to loop the sound.
            DestroyWhenDone = true, -- Whether or not to destroy the sound when it finishes playing. Disabled if Duration is provided.
            StaleThreshold = 30, -- How many ticks of silence must occur in a row for a sound to be considered done, for use with DestroyWhenDone.
        }
--]]
function easyBass.loadFile( path, settings, callback, failCallback )
    if not string.startWith( path, "sound/" ) then
        path = "sound/" .. path
    end

    loadBass( bass.loadFile, path, settings, callback, failCallback )
end

-- Behaves identically to easyBass.loadFile, but loads a sound from a URL instead.
function easyBass.loadURL( link, settings, callback, failCallback )
    loadBass( bass.loadURL, link, settings, callback, failCallback )
end


----- PRIVATE FUNCTIONS -----

handleFollowTarget = function( bassObj )
    if bassObj._dontFollowTarget then return end

    local target = bassObj._target

    if not isValid( target ) then
        bassObj:stop()

        return true
    end

    if target:isPlayer() then
        bassObj:setPos( target:obbCenterW() )
    else
        bassObj:setPos( target:getPos() )
    end
end

handleDestroyWhenDone = function( bassObj )
    if bassObj._dontDestroyWhenDone then return end
    if bassObj:isPaused() or bassObj:isStalled() then return end

    local volL, volR = bassObj:getLevels() -- :getLevels() is unaffected by :setVolume(), so additional checks aren't needed.

    if volL ~= 0 or volR ~= 0 then
        bassObj._staleStacks = 0

        return
    end

    local staleStacks = ( bassObj._staleStacks or 0 ) + 1
    bassObj._staleStacks = staleStacks

    if staleStacks > bassObj._staleThreshold then
        bassObj:stop()

        return true
    end
end

handleFadeInOut = function( bassObj, now )
    local volume = bassObj._volume
    local fadeInDuration = bassObj._fadeInDuration
    local fadeOutDuration = bassObj._fadeOutDuration

    if fadeOutDuration then
        local endTime = bassObj._endTime
        local timeUntilEnd = endTime - now

        if timeUntilEnd < fadeOutDuration then
            bassObj:setVolumeEffective( volume * ( timeUntilEnd / fadeOutDuration ) )

            return
        end
    end

    if fadeInDuration then
        local startTime = bassObj._startTime
        local timeSinceStart = now - startTime

        if timeSinceStart < fadeInDuration then
            bassObj:setVolumeEffective( volume * ( timeSinceStart / fadeInDuration ) )

            return
        end
    end

    return true
end

loadBass = function( loadFunc, path, settings, callback, failCallback, soundID )
    if type( path ) ~= "string" then
        error( "Expected path to be a string" )
    end

    settings = settings or {}
    local flags = settings.Flags or "3d stereo noblock noplay"
    local volume = settings.Volume or 1
    local pitch = settings.Pitch or 1
    local fadeStart = settings.FadeStart or 700
    local fadeEnd = settings.FadeEnd or 2000
    local useSimpleFading = settings.UseSimpleFading
    local fadeIn = settings.FadeIn or 0
    local fadeOut = settings.FadeOut or 0
    local duration = settings.Duration or 0
    local target = settings.Target or chip()
    local loop = settings.Loop or false
    local destroyWhenDone = false
    local staleThreshold = settings.StaleThreshold or 30

    duration = math.max( duration, 0 )

    if duration == 0 then
        duration = false
        fadeOut = 0

        if settings.DestroyWhenDone == nil then
            destroyWhenDone = true
        else
            destroyWhenDone = settings.DestroyWhenDone
        end
    end

    if useSimpleFading == nil then
        useSimpleFading = true
    end

    if fadeIn <= 0 then
        fadeIn = false
    end

    if fadeOut <= 0 then
        fadeOut = false
    end

    if soundID then
        timer.remove( "LKL_EasyBass_RetrySound_" .. soundID )
    else
        soundIDIncrement = soundIDIncrement + 1
        soundID = soundIDIncrement
    end

    loadFunc( path, flags, function( bassObj, errNum, errName )
        local success, nonBassErr
        success, nonBassErr = pcall( function()
            local now = realtime()

            if not bassObj then
                error( "Invalid bassObj" )
            end

            table.insert( allBassObjs, bassObj )
            bassObj._easyBass_setVolume = bassObj.setVolume
            bassObj._easyBass_stop = bassObj.stop

            function bassObj:setVolume( vol )
                if self._volume == vol then return end

                self._volume = vol

                if handleFadeInOut( self, realtime() ) then
                    self:setVolumeEffective( vol )
                end
            end

            function bassObj:getVolume()
                return self._volume
            end

            -- Sets the effective volume without changing the desired volume. Used by in/ou fading.
            function bassObj:setVolumeEffective( vol )
                if self._volumeEffective == vol then return end

                self._volumeEffective = vol
                self:_easyBass_setVolume( vol )
            end

            function bassObj:getVolumeEffective()
                return self._volumeEffective
            end

            function bassObj:stop()
                table.removeByValue( allBassObjs, self )

                self:pause()
                self:_easyBass_stop()

                function self:stop()
                end
            end

            bassObj._soundID = soundID
            bassObj._staleThreshold = staleThreshold
            bassObj._startTime = now
            bassObj._dontDestroyWhenDone = not destroyWhenDone
            bassObj._fadeInDuration = fadeIn
            bassObj._fadeOutDuration = fadeOut
            bassObj._volume = 1
            bassObj._volumeEffective = 1
            bassObj:setVolume( volume )
            bassObj:setPitch( pitch )
            bassObj:setLooping( loop )
            bassObj:setFade( fadeStart, fadeEnd, useSimpleFading )
            bassObj:play()

            if duration then
                bassObj._endTime = now + duration

                timer.simple( duration, function()
                    if not isValid( bassObj ) then return end

                    bassObj:stop()
                end )
            end

            if type( target ) == "Vector" then
                bassObj:setPos( target )
                bassObj._dontFollowTarget = true
            elseif isValid( target ) then
                bassObj._target = target
                bassObj._dontFollowTarget = false
            end

            if callback then
                callback( bassObj, errNum, errName )
            end
        end )

        if not success then
            if isValid( bassObj ) then
                bassObj:pause()
                bassObj:stop()
            end

            local retry = true

            if failCallback then
                retry = failCallback( errNum, errName, nonBassErr )
            end

            if retry then
                timer.create( "LKL_EasyBass_RetrySound_" .. soundID, 1, 1, function()
                    loadBass( loadFunc, path, settings, callback, failCallback, soundID )
                end )
            end
        end
    end )
end


----- SETUP -----

hook.add( "Think", "LKL_EasyBass_Think", function()
    local now = realtime()

    for i = #allBassObjs, 1, -1 do
        local bassObj = allBassObjs[i]

        if isValid( bassObj ) then
            if handleFollowTarget( bassObj ) then continue end
            if handleDestroyWhenDone( bassObj ) then continue end

            handleFadeInOut( bassObj, now )
        else
            table.remove( allBassObjs, i )
        end
    end
end )