[Open Assets] - Lightweight Custom Death Sounds

What permissions do you give others to modify and/or maintain your submission?: Modify: YES - Maintain: YES - I give permission for my entire submission to be modified by others or used in their own work. I give permission for my entire submission to be maintained by others as well.

Do you want to give your characters some funny sounds they can play on death?
Do you need something to soften the blow to your ego when constantly losing?
Well, do I have the thing for you!

=== Custom Death Sounds ===

Disclaimer:

I recommend not editing any Lua contained in the 00_lib_CustomDeathSounds folder, as those files need to stay the exact same for all other addons that may also be using this library. It is designed to not load itself again if the code already exists. Modifying that code can cause server sync issues or destroy the intentions of other creators.

If you wish to make modifications to the library, be sure to change the name and all references of the CustomDeathSoundsGlobal table. That will allow you to make the modifications you need while keeping your code separated from the original functions.

=== What is this? ===

Custom Death Sounds is Lua code that enables you to give characters in Ring Racers up to two sounds that play on death, and it is implemented in a very efficient way so that you don't need to worry about its performance.

Here's an example of this in action, featuring my own self insert. (Character release date still pending.)

cds_allowsounds <on/off, Default = on>
This command allows you to control whether or not death sounds will be allowed to play at all.

ON: Any character with CDS data will play their assigned sound on death.
OFF: CDS will not run for any character.

cds_debugsoundplay <0/1/2, Default = 0>
This command is meant for testing your Death Sounds by guaranteeing which sound will play.
NOTE: Any value other than 0 will print Debug messages in your console! It is not recommended to have this set to anything other than 0 in public lobbies.

0: The sound will be selected randomly.
1: Death sound 1 will always be selected.
2: Death sound 2 will always be selected.

=== How do I use this? ===

Included in the downloads are a zip file that hold some example addons showing you how to create simple Lua files that add the sounds. You will need some basic understanding of Lua to proceed, or pick up on it by looking at the provided examples.

There's three main components you need:

The base Custom Death Sounds (CDS) Lua files.
A Lua file that defines and sets your sounds, we will call this the "sound config Lua".
An init.lua file to ensure everything is loaded in the correct order.

You'll want a sound config Lua file for each character you are adding sounds to.
This example only shows one for Knuckles. You can duplicate the file and adjust it for any other character!

Your sound config Lua will need to define the freeslots for your sounds, import the necessary functions from the CDS Lua, and then run the functions that add your sounds to your selected character.

You will need to have the following information to give death sounds to a character:

The sound freeslot.
The number of ticks that the lua should wait before playing the sound.
Whether you want to start counting ticks right on death or after the hitstun is over.

Rather than show it here, I recommend taking a look at the DL_CDS_KnuxExample_V2.pk3 file to see how we set two custom sounds for Knuckles in the knuckles.lua file. You simply use the provided function to send your data to the CDS Lua.
If you make any errors in this file, your game log will tell you what went wrong. Simply adjust it until it is correct.

All CDS functions are accessed from the CustomDeathSoundsGlobal table.
Example: CustomDeathSoundsGlobal.addSound(skin, sound, false, 30) is how you would use the addSound function in your own script.

Function	Return Values	Description
`addSound(string skinName, int soundNum, boolean NoHitstunWait, int ticksToWait)`	True or False	This function allows you to assign a single sound to any specified character. The amount of ticks after death that it takes to play the sound depends on `tickToWait`. The value must be 0 or higher. `NoHitstunWait`can be set to control when the count happens. `True`: The count will happen immediately on death. `False`: The count will happen after the hitstun animation is over. The function returns `True` if it runs successfully. It returns `False` if any errors occur.
`wipeSounds(string skinName)`	True or False	This function will remove all CDS data assigned to the specified skin. The function returns `True` if it runs successfully. It returns `False` if any errors occur.
`doesSkinHaveCDS(string skinName)`	True or False	Returns `True` if the specified skin has any CDS data assigned to them. Returns `False` if the specified skin is does not have any CDS data assigned to them.

Oh, and don't forget to specify the run order of your Lua in your init.lua file. The CDS library Lua should be loaded before any of your sound config Lua is run.

init.lua example:

local luaPath = ""
local function loadFromFolder(addonName)
    dofile(luaPath .. addonName)
end

--Load CustomDeathSounds files first
luaPath = "00_lib_CustomDeathSounds/"
loadFromFolder("00_Pikaspoop_CommonFunction_Lib.lua")
loadFromFolder("01_DL_CustomDeathSounds_V2.lua")

--Load CDS config for your character(s)
luaPath = "YourPackName_CDS_Lua/" --define the folder your lua is in.
/* luaPath = "YourPackName_CDS_Lua/subfolder/" --If you have sub-folders, list the whole path
   luaPath = "" --Or maybe the lua is not in any folder? Do this then.
*/
--Now we load the lua you set up for your character
loadFromFolder("knuckles.lua")

--Clean up variables now that this script won't run again
loadFromFolder = nil
luaPath = nil

There's a few other example scripts provided in the Examples.zip archive to further showcase more things you can do, such as how to give the same sounds to all characters, how to check if a character is already set to play sounds, how to wipe all sounds assigned to a character, and what happens when you attempt to give a character more than two sounds.

Q: Do I need to credit you for using this Lua?
A: Yes, please credit me if you plan to include this Lua in any of your projects. Be sure to include a url link back to this addon in the credit as well.

Q: Why can't I add more than two sounds?
A: I made a deliberate decision to hard-cap the number of death sounds a character can have at two. You are not going to enter the death state frequently, and adding more than two sounds will both severely bloat your addon and also waste valuable freeslots on sfx when those freeslots could be used elsewhere.

Q: Do I need to worry about worse performance in my netgames?
A: No. This Lua was designed to be loaded in multiple addons, and I made sure to make it as efficient as possible. CDS will detect if it was already loaded from another addon, and stop itself from loading any duplicate information.
Testing shows that it uses almost no processing bandwidth when inactive, and it takes on average 40us to run when a death sound is queued.
This is assuming that nobody changes the files in the 00_lib_CustomDeathSounds folder. If you notice my Lua running very poorly in a specific addon, check to see if any changes were made to it.

Q: Do I need to worry about updating this Lua in my characters?
A: I will inform you if any update is mandatory through the update feed. However the script will inform you if any newer versions of this script are loaded after older versions.
If there's a character pack that is no longer being maintained and using an old version of this Lua, loading the newest CDS lua before that character pack loads should fix the issue. The old sound config Lua should be compatible with new versions of CDS, so there's no need to worry about incompatibility.

Q: I found a bug or a way to improve the Lua! How do show you?
A: Feel free to share your bugs and improvements in the forum posts here! I'll add any changes that further optimize the Lua.

Q: Why can't I hear my death sounds in Bean's Dynamite Derby?
A: Turn off bdd_deathsounds in your console. Your Loss sound is probably overpowering your death sound.

Thank you! I hope you enjoy giving silly death sounds to your characters!
Feel free to DM me on the SRB2 MB or on Discord if you have any questions!

SRB2 MB: @Pikaspoop
Discord: @pikaspoop

Reactions: WootInABoot and Unfunnyio

[Open Assets] Lightweight Custom Death Sounds V2

More resources from Pikaspoop

Share this resource