loaforcsSoundAPI

A portable sound-replacement mod, built to give sound pack creators more control and a more maintainable code base.

For Sound-Pack creators

A simple tutorial to make a sound pack is available in the github wiki. Examples are available as well.

• Custom File Structure Hierarchy
• Mapping multiple sounds to the same sounds
• Sound-packs can create config options just like regular mods
• Swap out audio clips live based on what is happening in game.

For developers

SoundAPI will eventually contain multiple utilities to help with loading custom sounds. All common use methods are under the SoundAPI class.

Custom Conditions

Here is an example condition.

[SoundAPICondition("LethalCompany:apparatus_state")] // attribute for SoundAPI.RegisterAll function
public class ApparatusStateCondition : Condition {
    public enum StateType {
    	PULLED,
    	PLUGGED_IN
    }
    internal static bool CurrentApparatusPulled = false;

    public StateType? Value { get; internal set; }

    public override bool Evaluate(IContext context) {
    	StateType state = CurrentApparatusPulled ? StateType.PULLED : StateType.PLUGGED_IN;
		
    	return state == (Value ?? StateType.PULLED);
    }
}

// To register all in your assembly (this will respect other soft-dependencies in your mod)
SoundAPI.RegisterAll(Assembly.GetExecutingAssembly());

// Or manually (if you need more complex logic)
SoundAPI.RegisterCondition("LethalLevelLoader:dungeon:has_tag", () => new LLLTagCondition<ExtendedDungeonFlow>(() => {
    if (!RoundManager.Instance) return null;
    if (!RoundManager.Instance.dungeonGenerator) return null;
    if (!PatchedContent.TryGetExtendedContent(
        RoundManager.Instance.dungeonGenerator.Generator.DungeonFlow, 
        out ExtendedDungeonFlow lllDungeon)
    ) return null;
    return lllDungeon;
}));

Sound-pack creators will use

{
    "condition": {
        "type": "LethalCompany:apparatus_state"
    }
}

Because Value is nullable, the sound pack creator does not need to supply a value, and it will default to true. Otherwise, they can manually set it to PLUGGED_IN to check if the apparatus is plugged in. It's recommended to use an enum even if there are currently only two options for forward compatibility.

Mappings

Mappings are for a mod developer to write a shortcut to one or more sound matches. It's recommended sound pack creators use mappings where possible for forward compatibility (as the mod dev can update the mapping file with a mod update, without the sound pack needing to update.)

To use mappings you need to include a sound_pack.json in your mod zip (this is so SoundAPI loads it automatically, an option to load them via the SoundAPI class may come later). You do not need to include a replacers or sounds folder. A soundapi_mappings.json file then goes in the same folder.

Example soundapi_mappings.json file:

{
    "FacilityMeltdown:music": [
        "MeltdownHandler:MeltdownMusic:meltdownMusic"
    ],
    "FacilityMeltdown:warning_voice": [
        "MeltdownHandler:WarningVoice:warning1",
        "MeltdownHandler:WarningVoice:warning2",
        "MeltdownHandler:WarningVoice:warning3",
        "MeltdownHandler:WarningVoice:warning4"
    ]
}

NOTE: The soundapi_mappings.json may change file name later, but compatibility will be retained.

Sound-pack creators will then use your mappings in their replacers. Mappings in matches are prepended with a #.

{
    "replacements": [
        {
            "matches": "#FacilityMeltdown:music",
            "sounds": [
                {
                    "sound": "meltdown.ogg"
                }
            ]
        }
    ]
}

Naming Convention

It's recommended to follow a naming convention for your conditions and mappings. Don't have 1 'part' or more than 3. Each part should be seperated with a colon.

• NAME OF YOUR MOD:NAME or
• NAME OF YOUR MOD:SUB CATEGORY:NAME

2.0.1

• Replacements and sounds with a condition that are labelled as constant are now skipped when loading, as opposed to just entire replacer files
• Conditional objects marked with constant also now skip validation and mapping (meaning custom conditions/mappings from mods can be properly used like a soft-dependency)
• Fixed an issue where it was impossible for some sounds to be randomly chosen
• Added validation error for missing mapping
• When logging validation errors, the log source now has soundpack. infront of the sound pack name
• Changed resetsat to resets_at for the counter condition
• Added logs for when SoundAPI handles DebugLogSources
• Added smarter internal logic to handle SoundAPI updating some AudioSources. Should maybe be more performant
• Fixed an issue where the MatchStrings DebugLogSource did not log anything unless GenerateReports was also enabled.

2.0.2

• woops

2.0.3

• fixed an issue where if SoundAPI had nothing to load, it would spin infinitely.

2.0.4

• bleh

2.0.5

• upload to R.E.P.O.

2.0.6

• fixed an issue where SoundAPI would cause many issues if a loaded sound-pack tried to reference files that didn't exist.
• fixed an issue where SoundAPI would stop audio sources from playing if they were marked as playOnAwake and loaded with a scene.
  • note: this has a temporary config to disable it, as i'm not entirely sure if this will fully work
• added an extra check to prevent duplicate sound-packs from loading.
• added a warning log if no sound-packs loaded.

2.0.7

• uploaded to PEAK
• removed previously temporary config
• add metadata spoofing (fixes config names in Gale acting strange)
• added a new experiment
  • audio clip spoofing: enabling this experiment makes soundapi lie in some cases to other mods and the vanilla game about the true audioclip. this can help improve compatibilty

2.0.8

• hopefully fixed some issues with audio clip spoofing
• fixed an edge case where when a prefab was instantiated with a disabled playOnAwake audio source soundapi would try to play it (harmless, only a warning log)
• fixed config generation so that soundpacks which do not define config do not create a file.

2.0.9

• AudioClipSpoofing is no longer an experiment and is defaulted to true (it can still be disabled under the Advanced section in the config in case there are some remaining edge cases)
• UEFOneShotWorkAround has been added as a new experiment:
  • Some sounds are played on AudioSources with .PlayOneShot(), for these sounds it's impossible to replace them as they are being played
  • As a work-around, this experiment hijacks .PlayOneShot(), instead creating an AudioSource with duplicated settings, and calling .Play() instead
• Added SoundAPI.CloneAudioSource(source, target, flags) to facilitate UEFOneShotWorkaround
• Native Backend:
  • Native Backend is a rewrite to the patching method used to detect when an AudioSource has started playing.
  • This fixes all playOnAwake edge cases
    • Notably the ship thrusters in Lethal Company which were enabled by an animation were previously unreplaceable (at least im pretty sure; im writing this months later)
  • As a result native backend should also be significantly more performant, especially when many prefabs are instantiated in a short time frame
    • For example dungeon generation in Lethal Company would be faster (although async dungeon generation in v80 means it may not be noticable as much)
  • Native Backend is only supported on some unity versions:
    • 2022.3.9f1 (Lethal Company pre-v73)
    • 2022.3.62f2 (Lethal Company post-v73)
      • This version has a further performance improvement regarding cleaning up AudioSources when a scene is loaded
    • 2022.3.60f1 (internal test project)
    • If SoundAPI is run in an unsupported version it will fallback to the previously used HarmonyX backend, although this won't be supported as much.
  • A config option PreferredBackend is available to force use of the old HarmonyX backend, though the Native Backend should always be used if available
• Reports generated by SoundAPI now include the game name/version/company, the unity version and if native backend is supported/enabled.

2.0.10

• Fixes an issue where the HarmonyX backend did not work in REPO.

2.0.11

• Fixes an issue where SoundAPI could only replace the same audio clip on the same audio source once.