Editing Arcane University:Compatible Implementation of Hard Coded Music Types

{{Trail|Implementation}}
This page describes Beyond Skyrim's approach to the implementation of hard coded music types, such as Combat and Discovery music, without making the individual projects incompatible with each other, and also gives pointers for other mod authors on how to create compatibility patches with Beyond Skyrim.

== Hard Coded Music ==

For most types of music, mods can add additional music without having to overwrite any vanilla forms. A plugin can just add a new [https://www.creationkit.com/index.php?title=Music_Type Music Type] containing exploration music and assign that to its own world spaces, regions and cells, meaning the [https://www.creationkit.com/index.php?title=Music_Track Music Tracks] within will not play in areas from vanilla or other mods, nor will any other music of that kind play in the mod if it was not specifically added.

For some some types of music, however, the game executable is hard coded to use a specific set of Music Types from Skyrim.esm for certain purposes:

*MUSDiscoveryTown [000ABDA3]
*MUSDiscoveryCity [000ABDA5]
*MUSDiscoveryDungeon [000ABDA4]
*MUSDiscoveryGeneric [000AC13D]
*MUSSpecialWordOfPower [00017415]

In addition, the Default Object Manager (DOBJ) specifies more Music Types, which cannot be changed without introducing even more incompatibilities:

*MUSDungeonCleared [0010963F] (Dungeon Cleared Music)
*MUSSpecialSuccess [0003B565] (Success Music)
*MUSExploreTestb [00089A9C] (Default Music)
*MUSCombat [0003418E] (Battle Music)
*MUSSpecialDeath [00013686] (Death Music)
*MUSSpecialSuccess [0003B565] (Level Up Music)
*_NONE [0001BA72] (Stats Music)

Adding a new Music Type for e.g. combat music will therefore do nothing, since there is no entry point for the game to make use of it without your mod overriding the Default Object Manager, which you should not do. The least bad method for adding new tracks for the types listed above is:
*Override the Music Type to add your own Music Tracks to the stack
*Override the vanilla Music Tracks in the stack to add a condition excluding the track from playing in areas added by your mod

Since only one mod at a time can edit a Music Track or Music Type, multiple mods adding music of these types will therefore need a compatibility patch, which adds both mods' conditions to the vanilla Music Tracks in order to exclude them from both mods, and adds both mods' Music Tracks to the affected Music Types.

Note: Mods which are willing to require SKSE may use the [https://www.creationkit.com/index.php?title=DefaultObjectManager_Script DefaultObjectManager Script] to switch out the vanilla combat Music Type for a custom one and back again when the player enters and leaves the modded area. This is the strategy currently used by Atmora, but it only works for Music Types that are specified in the DOBJ.

== The Problem in Beyond Skyrim ==

Beyond Skyrim projects currently override the following vanilla Music Types and the vanilla Music Tracks contained within them in the manner described above:

*MUSDiscoveryGeneric [000AC13D]
*MUSDiscoveryTown [000ABDA3]
*MUSDiscoveryCity [000ABDA5]
*MUSDiscoveryDungeon [000ABDA4]
*MUSDungeonCleared [0010963F]
*MUSCombat [0003418E]

MUSCombatBoss [000D777A] is also edited, although this Music Type is not referenced in either the executable or the DOBJ, and all the tracks it contains (both vanilla and modded) are also in MUSCombat with appropriate conditions, so this Music Type may actually be unused.

In the currently released versions of Bruma (1.3 and earlier), edits to these Music Types are made in BSHeartland.esm which is specific to the Cyrodiil and Elsweyr projects, meaning it will even conflict with other Beyond Skyrim projects. In theory, compatibility patches would then be needed - including three-way and four-way patches - which is not acceptable.

There is also BSAssets.esm, which is used as a master by almost all Beyond Skyrim masters including BSHeartland.esm. However, moving everything into BSAssets - the Music Tracks and everything needed to condition them to the appropriate area - is not possible; although an entire worldspace can have a [https://www.creationkit.com/index.php?title=Location Location] assigned to it, and this Location can be put in BSAssets, this is not a sufficient solution for the Cyrodiil, Elsweyr and Iliac Bay projects. This is because those projects involve multiple provinces with their own soundtracks occupying the same world space, and music (especially combat music) will need to be restricted to the appropriate provinces, which cover large exterior areas. The common and only practical way to do this is to condition on a [https://www.creationkit.com/index.php?title=Region Region], and a Region cannot be added to BSAssets without it also containing the World Space which the Region pertains to. Moving the Beyond Skyrim World Spaces to BSAssets would be extremely technically disruptive at this stage in development.

== The Solution ==

To make the music in Beyond Skyrim compatible without requiring patches, these things must be done:
*BSAssets must override the vanilla Music Tracks from hard coded Music Types to exclude them playing in modded areas. This is done by conditioning on a "Beyond Skyrim" location which each project applies to its areas.
*Any custom Music Track that needs to go in a vanilla Music Type needs to be implemented in BSAssets, albeit in a dummied out form, so that it never plays.
*BSAssets needs to add all these Music Tracks - from all the projects - to the appropriate vanilla Music Types.
*Each project's own master must then override its own Music Tracks - which are in BSAssets - to add the file path and any other data, as well as conditions, which can use all the forms added in the project esm, such as regions.

=== Excluding Vanilla Music ===

BSAssets now contains a BSKBeyondSkyrimLocation [016036AD]. All vanilla Music Tracks in the Music Types touched by Bruma have had a condition added to them:

PlayerRef.GetInCurrentLoc(BSKBeyondSkyrimLocation) == FALSE

Beyond Skyrim projects can therefore "opt out" of vanilla music by applying the BSKBeyondSkyrimLocation to their world spaces, locations and/or cells. To do this comprehensively, here are the steps:
*Set BSKBeyondSkyrimLocation as the parent location of each of your top-level locations. This will typically be the location that denotes your province, such as CYRCyrodiilLocation or ROSRoscreaLocation. This will exclude vanilla music from all your interior cells, assuming all the locations in the mod are set up correctly with parents.
*If your main World Space has no location specified, then give it BSKBeyondSkyrimLocation, as this will cover the whole exterior area. If it already has one, then setting BSKBeyondSkyrimLocation as its parent will do the trick.
*Make sure BSKBeyondSkyrimLocation is also applied to any ancillary world spaces or cells which might not be covered by your main province location, such as daedric realms. Either set their location to BSKBeyondSkyrimLocation or make sure it is the parent of whichever location it might already have.

Note that this will exclude ''all'' the listed Music Types from your mod, even if you only wanted to exclude combat music. If you want to add other types back in, project-specific re-implementations of vanilla Music Tracks will have to be added to BSAssets and then activated by your esm as detailed below. This is done for Cyrodiil with generic discovery stingers, since the soundtrack does not contain any custom ones.

One might wonder why we didn't simply edit the conditions on vanilla tracks so that they only play in vanilla areas, negating the use for the BSKBeyondSkyrimLocation. The reason is that other mods may add new areas without necessarily having their own soundtrack, and we do not want to disable certain kinds of music for those.

=== Adding Dummied Music Tracks ===

If your project wants to add a track belonging to one of the affected categories, submit a plugin for BSAssets that introduces a new Music Track with a recognizable EditorID, which has an empty file path, and only one condition, which will guarantee that this track does nothing if your project is not loaded:

IsPS3 == TRUE

Also have your plugin modify the vanilla Music Type in order to add this track to the stack. You may add multiple tracks this way in the same plugin. If multiple plugins in a given merge window add tracks to the same Music Type, then only one will take effect, so the other tracks will have to be added to the stack in a subsequent merge.

=== Activating the Music Tracks ===

After a BSAssets merge has taken place, your dummied out tracks will be ready for your project esm to override them. Edit the track to add the proper file path and whatever other data it needs, and replace IsPS3 with as many conditions as you need, using any forms from BSAssets as well as your own project esm. Make sure your esm only overrides the BSAssets tracks that belong to your project, and do not override any vanilla tracks or Music Types.

== Creating Compatibility Patches ==

This method makes the Beyond Skyrim projects compatible with each other, but still no more compatible with other mods which add new tracks to hard coded music types, so compatibility patches will still be needed. The positive change is that a single patch can now make your mod compatible with Beyond Skyrim as a whole rather than just Bruma or any other single release.

The plugin will have to depend on the external mod as well as BSAssets.esm (it must NOT depend on any individual project esm). Combine the stacks in the hard coded Music Types so that they contain both your mod's tracks as well as the dummied out ones in BSAssets. If the conditions on your mod's Music Tracks do not already suffice to prevent them playing in Beyond Skyrim areas, you can have your plugin add this condition to them, like BSAssets does to vanilla tracks:

PlayerRef.GetInCurrentLoc(BSKBeyondSkyrimLocation) == FALSE

Your patch will likely have to be updated every time a Beyond Skyrim project releases, as new tracks will almost certainly have been added to BSAssets and need to be added to the hard coded music types.

== Custom Map Markers ==

Some projects wish to introduce [[Arcane University: Custom Map Marker Implementation|Custom Map Markers]], and will want to have custom discovery music for them as well. The type-specific discovery Music Types -  MUSDiscoveryTown, MUSDiscoveryCity, and MUSDiscoveryDungeon - will not play for those. Instead, such tracks will have to be added to MUSDiscoveryGeneric, using the same method. Since filtering by map marker type is not intrinsic to this Music Type, conditions will have to be added to the track, using either the specific location(s) the map marker is in, or keywords contained in either BSAssets or the province esm, or a plethora of other options.

== Gallery ==
<gallery>
File:HardCodedMusic_VanillaTracks.png|BSAssets excluding vanilla tracks using the Beyond Skyrim location
File:HardCodedMusic_CustomTracks.png|A Cyrodiil track dummied out in BSAssets and activated in BSHeartland
</gallery>

[[Category:Arcane University]][[Category:Asset_Tutorial]]