===============================================================================
| Better Music System - MUSE Version |
| A Morrowind Mod, Version 1.0 |
| by Necrolesian |
===============================================================================

---------
Summary |
---------

This mod consists of custom MUSE config files that (mostly) implement the
functionality of BTB's version of Better Music System.

Important Note: Installing this archive by itself will do nothing, because it
does not contain any music tracks. You'll need to fill the mod's empty music
directories (in music\MS) with tracks in order to hear custom music in-game.

Below you'll find instructions for distributing the music from BTB's soundtrack
to the various music directories, if you want to duplicate BTB's plugin as
closely as possible. But one of the benefits of MUSE is that it's supremely
customizable. You can deviate from those instructions, or use completely
different music from any other source.

-------------
Description |
-------------

This mod primarily consists of a bunch of custom MUSE config files (the files
in MWSE\config\MS). These config files mostly replicate the functionality of
BTB's Better Music System plugin, with a few adjustments. The following custom
music is implemented:

Regions: The region (MS_r_) files allow for different music in the game's
various regions. Like BTB's plugin, there are three different region categories
that can have different music: Red Mountain, Solstheim, and everywhere else.
There's also a file for Firemoth Region, so you can have custom music there if
you're using Siege at Firemoth.

Towns: The custom town music is implemented by the cell (MS_c_) files. There's
separate music for Vivec, Ebonheart, Pelagiad, Molag Mar, Ghostgate and
Mournhold.

There's also music for Hlaalu Towns (Balmora, Caldera, Suran), Redoran towns
(Ald-ruhn, Gnisis, Maar Gan), Telvanni towns (Sadrith Mora, Tel Aruhn, Tel
Branora, Tel Fyr, Tel Mora, Tel Vos, Vos), fishing villages (Seyda Neen, Hla
Oad, Gnaar Mok, Ald Velothi, Khuul), Nordic villages (Dagon Fel, Skaal Village,
Thirsk, Raven Rock), and Ashlander camps.

Dungeons: Dungeon music is implemented partly by the tileset (MS_t_) files and
partly by the cell files. The following dungeon types can have their own custom
music: caves, Daedric shrines, Dwemer ruins, Dunmer strongholds, tombs,
Solstheim ice caves, barrows, mines, grottoes, Velothi towers, underworks,
Sixth House bases, shipwrecks, and Old Mournhold.

You can also have unique music for Sixth House citadels inside the Ghostfence,
Dagoth Ur, the Clockwork City (with the Dome of Sotha Sil being separate),
Castle Karstaag, Mortrag Glacier (with the maze cells being separate), and the
Cavern of the Incarnate. There's also a directory for Firemoth.

In addition you can put music in the Dungeon General directory for any dungeons
(really only mod-added ones) not covered.

Other cell types: Many other types of cells can have separate custom music
(implemented mostly by cell files, with one tileset file thrown in). These
include Imperial forts, Fighters Guilds, Mages Guilds, Morag Tong Guildhalls,
temples (with the temple in Mournhold being separate), taverns/inns, smithys,
magic-type shops, and other shops.

The Royal Palace and Museum of Artifacts in Mournhold each have their own
separate music, and a number of isolated farmhouses and shacks also have their
own music category. Even the Imperial Prison Ship can have separate music
(though you might want to just put the main Morrowind theme in there).

Battle music: The battle music categories, implemented by the enemy (MS_e_)
files, are similar to the implementation in BTB's plugin, with a few additional
high-tier enemies added to the "sub-boss" category. However, battle music in
this mod is more customizeable.

Dagoth Ur, Almalexia, Hircine and Vivec each have their own boss music.

In addition, there are separate music directories for: Ash Vampires, Dagoth
Gares, Divayth Fyr, Helseth, Umbra, the Imperfect, Karstaag, the Udyrfrykte,
Gedna Relvel, the Hands of Almalexia, the Grandmaster Writ targets, faction
bosses (like Gothren, Eno Hlaalu, Bolvyn Venim, and more), the Black Dart Gang,
Daedra bosses, Dark Brotherhood bosses, Goblin bosses, undead bosses, vampire
bosses (including the heads of the clans), and werewolves.

Even the ghosts of the failed incarnates in the Cavern of the Incarnate get
their own battle music, if you're crazy enough to fight them. There's also a
directory for other sub-boss enemies (such as Gaenor, Karrod, Falx Carius, the
Dreugh Warlord, and more). Finally, Grurn (from Siege at Firemoth) also has his
own music.

Beyond the above high-tier enemies with boss or sub-boss music, every creature
and NPC in the game is divided into three tiers based on their health, like in
BTB's plugin. There's separate music for enemies with 200+ health, those with
50-199, and those below 50 health.

-------------------------------
Requirements and Installation |
-------------------------------

MWSE
----

First, since MUSE is an MWSE mod, it requires MGE XE and the latest version of
MWSE 2.1. Just install MGE XE and run MWSE-Update.exe to download the latest
build.

MUSE
----

Next, you'll need to install MUSE if you haven't already. You can install it
with Wrye Mash or your favorite mod management tool, or manually.

However, before or after you install MUSE, you might want to delete the default
config files in MWSE\config\MS, along with any empty music directories in
music\MS, to avoid confusion later.

MUSE fixes
----------

MUSE has a few bugs that can result in errors or otherwise cause aspects of the
mod to not work as intended. There are also a few things that can be tweaked to
work better with BTB's soundtrack and to make the functionality of MUSE closer
to BTB's plugin.

I suggest making a few fixes and tweaks to MUSE's code (the lua files in MWSE\
mods\music). This is not required, but it's recommended. The changes I
recommend making are below.

Note: #1 and #2 are mutually exclusive. Do one or the other, but not both. #2
is closer to how BTB's plugin works.

1. Threshold fix: In combat.lua, there's a function called CalculateTreshold
that calculates the combat threshold, with three separate formulas depending on
your level. There's an error in the formula for when you're level 30+: the term
"playerLevelTiers[1]" is subtracted one time too many, which causes the
threshold to suddenly drop off at level 30.

To fix this, toward the bottom of that function (on line 103 of the unmodified
file), remove one instance of subtracting that term. In other words, change
this:

if(player.level >= playerLevelTiers[2]) then --levels 30+, health treshold locked
combatTresholdCurrent = (combatTresholdInitial + ((playerLevelTiers[1] * enemyHealthAdditions[1]) - enemyHealthAdditions[1]) --add tier 1
+ ((((playerLevelTiers[2] - playerLevelTiers[1]) - playerLevelTiers[1]) * enemyHealthAdditions[2]) - enemyHealthAdditions[2])) --add tier 2
* (MUSE.settingsConfig.combatMusicTresholdMod/100) * modifier --mods
end

to this:

if(player.level >= playerLevelTiers[2]) then --levels 30+, health treshold locked
combatTresholdCurrent = (combatTresholdInitial + ((playerLevelTiers[1] * enemyHealthAdditions[1]) - enemyHealthAdditions[1]) --add tier 1
+ (((playerLevelTiers[2] - playerLevelTiers[1]) * enemyHealthAdditions[2]) - enemyHealthAdditions[2])) --add tier 2
* (MUSE.settingsConfig.combatMusicTresholdMod/100) * modifier --mods
end

2. Threshold modification: Alternatively, you can change how the threshold
works to more closely match BTB's plugin.

In BTB's plugin, the combat threshold is 50 in exteriors and 0 in interiors. To
replicate this functionality, replace the whole CalculateTreshold function
with:

local function CalculateTreshold(modifier)
local cell = tes3.player.cell

if cell.isInterior and not cell.behavesAsExterior then
combatTresholdCurrent = 0
else
combatTresholdCurrent = 50
end
end

Note: #3 and #4 are mutually exclusive. Do one or the other, but not both. #4
is closer to how BTB's plugin works.

3. Air fix: There's a bug that causes the "air" music to not work. The mod
checks every frame (unless you're jumping) what height you're at, and sets that
height as "ground height." But the ground height check keeps happening even
when you're levitating, so the air music never triggers (the mod always thinks
you're at ground level).

To fix this, in depthsnair.lua, there are two places you'll need to add a
flying check. First, in the GetGroundPosition function toward the top (line
29), change this:

if(player.mobile.isJumping == false) then

to this:

if player.mobile.isJumping == false and player.mobile.isFlying == false then

Second, in the next function down (line 49), change this:

if(player.mobile.isJumping == false and inAir == true) then

to this:

if player.mobile.isJumping == false and player.mobile.isFlying == false and inAir == true then

4. Air and underwater disable: Alternatively, if you don't intend to use the
air or underwater music at all (BTB's plugin implements neither), you can
disable this part of the mod to improve performance (otherwise the mod will do
a bunch of useless checks every frame).

To do this, you'll need to make a couple changes in main.lua. First, in the
combat section, in the function CombatEnd (line 88), comment out or delete the
line that says "depthsNAirMod.StartMusic()". (Comment out a line by putting two
hyphens in front of it.)

Second, toward the bottom, in the OnUpdate function (line 115), comment out or
delete the line that says "depthsNAirMod.Simulate()".

5. Nil check: There's a problem with the tileset statics check that will spam
your MWSE.log with errors unless you put in a nil check. In interior.lua,
toward the bottom, in the TilesetMusic function, just before the line that says
"if(tilesetInfo[1].staticsFound == 0) then" (line 205), add the following:

if not tilesetInfo[1] or not tilesetInfo[1].staticsFound then
return
end

6. Mortrag combat music disable: BTB's plugin disables combat music in the
Mortrag Glacier maze cells (with all those werewolves), because it has the
intense sub-boss music playing the whole time in those cells.

To disable combat music in those cells, you can make another change to
combat.lua. Toward the bottom, in the StartMusic function, just after this
part:

if(combatTresholdCurrent > currentEnemiesHealth) then
return
end

(i.e. just after line 138 of the unmodified file), add the following:

local cell = tes3.player.cell.id

if cell == "Solstheim, Mortrag Glacier: Outer Ring" or cell == "Solstheim, Mortrag Glacier: Inner Ring" then
return
end

7. Game time check disable: Every frame MUSE checks what time it is (game
time), to know whether you're in "night mode." But nothing else is done with
this, because night music is not implemented, which means this is another
useless check happening every frame that you can disable for performance
reasons.

In main.lua, toward the bottom, in the OnUpdate function (line 116), comment
out or delete the line that says "MUSE.CheckHour()".

This mod
--------

After you install MUSE and optionally make a few tweaks to the code, you can
finally install this mod. The archive just consists of custom config files and
empty music directories. Just use Mash or your favorite mod management tool, or
you can manually copy the MWSE and Music directories to your Data Files
directory.

If you use a mod management tool, you might find it more convenient to extract
the archive somewhere (not in your Morrowind directory), fill the music
directories with music (described below), then repackage the archive and
install with Mash or MO2. But just installing now and then manually moving
music tracks over into Data Files works too.

Music tracks
------------

Before you can enjoy custom music, you'll need to actually add music tracks to
the mod's empty music directories. You can use tracks from any source, such as
Better Music System Redone. But if you enjoy BTB's version of Better Music
System, you can use the tracks from BTB's soundtrack to closely duplicate the
feel (well, the sound) of BTB's plugin.

First step is to download BTB's soundtrack, if you don't already have it. Don't
just install it as is; the tracks have to go into this mod's special
directories.

To make this mod as close to BTB's plugin as possible, distribute the tracks in
the following way:

music
MS
cell
Dungeons
Castle Karstaag
Nap

Clockwork City
Fields Of Tenerron

Dagoth Ur
Flashes

Firemoth
Flashes

Grottoes
Caves

Mines
Mines

Mortrag Halls
Hall Of the Warrior

Mortrag Maze
Battle In Oblivion

Old Mournhold
Nap

Shipwrecks
Caves

Sixth House Bases
Where The Dead Lay

Sixth House Citadels
Lost Relic

Tombs
Graveyard

Underworks
Dark Dungeon

Velothi Towers
Threshold

Misc
Cavern of the Incarnate
Singular

Dome of Sotha Sil
Singular

Imperial Prison Ship
Land Of The Dunmer

Isolated Houses
Morrowind Explore 1
Morrowind Explore 2
Morrowind Explore 3
Morrowind Explore 4
Morrowind Explore 5
Morrowind Explore 6
Morrowind Explore 7

Museum of Artifacts
Dawn Has Come

Royal Palace
New Dawn

Services
Fighters Guilds
Fighters Of Daggerfall

General Shops
Crystal Cavern

Mages Guilds
Mages Of Daggerfall

Magic Shops
Alchemist

Morag Tong
Singular

Mournhold Temple
Thanatophopia

Smiths
Imperial Song

Taverns
Explore
Show
Square
Taverns Of Daggerfall I
Taverns Of Daggerfall II

Temples
Floating
Metamorphosis

Towns
Ashlander Camps
Dream Of Tamriel
Esplorazione
Land Of The Dunmer

Ebonheart
Casted Life

Fishing Villages
Morrowind Explore 1
Morrowind Explore 2
Morrowind Explore 3
Morrowind Explore 4
Morrowind Explore 5
Morrowind Explore 6
Morrowind Explore 7

Ghostgate
The Warrior's Charge

Hlaalu
A Bosmer's Tale
A Young Mind
Lover And The Rain
Magic Of The Altmer
Sailing To Vvardenfell
Your Time Of Need

Molag Mar
Dream Of Tamriel
Esplorazione
Land Of The Dunmer

Mournhold
Flight Of The Kingfisher
Hope For Rebirth
The Light Of Dawn

Nordic
Dagon Fel
Raven Rock
Skaal
Thirsk

Pelagiad
Dawn By The Sally Garden

Redoran
A Bosmer's Tale
A Young Mind
Lover And The Rain
Magic Of The Altmer
Sailing To Vvardenfell
Your Time Of Need

Telvanni
Awakening
Dreaming Of Flying
Evening Falls
Mont St. Joseph
Remembrance
Secret Garden

Vivec
A Family To Have
Gloria
Honest Until Death
Return To Morrowind

combat
Almalexia
Prelude To War

Ash Vampires
Battle In Oblivion

Black Darts
Battle In Oblivion

Daedra Bosses
Battle In Oblivion

Dagoth Gares
Battle In Oblivion

Dagoth Ur
Battle Dagoth

DB Bosses
Battle In Oblivion

Divayth Fyr
Battle In Oblivion

Faction Bosses
Battle In Oblivion

Gedna Relvel
Battle In Oblivion

General Sub Boss
Battle In Oblivion

Goblin Bosses
Battle In Oblivion

Grandmaster Writs
Battle In Oblivion

Grurn
Battle In Oblivion

Hands
Battle In Oblivion

Helseth
Battle In Oblivion

Hircine
Bloody Hircine

Imperfect
Battle In Oblivion

Karstaag
Battle In Oblivion

Nerevarines
Battle In Oblivion

Tier 1
Morrowind Battle 1
Morrowind Battle 2
Morrowind Battle 3
Morrowind Battle 4
Morrowind Battle 5
Morrowind Battle 6
Morrowind Battle 7

Tier 2
Battaglia
Cursed
Escape
Robot Rampage
War
What's That Do

Tier 3
From Water To Wine
Hero Man
Intense Battle
Magedar Finale Master
Nacht Der Monde
Riders

Udyrfrykte
Battle In Oblivion

Umbra
Battle In Oblivion

Undead Bosses
Battle In Oblivion

Vampire Bosses
Battle In Oblivion

Vivec
Bloody Hircine

Werewolves
Battle In Oblivion

General
Dungeon General
Caves

interior
Barrows
Graveyard

Caves
Caves

Daedric
Passage Of The Undead

Dwemer
Dark Fortress

Ice Caves
Where The Dead Lay

Imperial Forts
Straight Into The Ambush

Strongholds
Dark Dungeon

Tombs
Graveyard

region
Firemoth
Mobs
The Power Of All Elements
Red Fields
Velothi Invasion

Overworld
Buffy (S2-5)
Buffy (S2-7)
Chosen
Close Your Eyes
Dawn's Ballet
Hush
Little Miss Muffet
Restless
Sacrifice
Sledgehammer
Vision Of Jenny
Waking Willow

Red Mountain
Mobs
The Power Of All Elements
Red Fields
Velothi Invasion

Solstheim
Dark Isle
Fallen Daggers
Passing Twilight
Serenity Falls
Tamriel's Theme
Within

MUSE settings
-------------

Finally, I'll address a couple settings in MUSE's Mod Config Menu.

If you modified the code in combat.lua to make the combat music threshold work
as in BTB's plugin (modification #2 above), then the threshold multiplier in
the MCM doesn't matter because it's not used for anything. Otherwise, you can
set this multiplier to whatever you want. However, I wouldn't set it higher
than the default, unless you want to not hear battle music very much.

The region music queueing option is also pretty important. By default (with
this option enabled), when you enter an area in which region music plays (say,
from a dungeon, or from a different region), the currently playing track will
finish before the music for the new region starts. If you disable region music
queueing, the music for the new region will begin immediately when you enter
the region.

I generally prefer disabling region queueing so the region music will start
right away. However, occasionally the music might switch back and forth when
you're traveling right along the boundary of a town cell. It's a matter of
personal preference.

-----------------
Version History |
-----------------

Version 1.0 - 2020-08-07
- Initial release.

---------
Credits |
---------

Without Rytelier's hard work in creating MUSE, these custom MUSE config files
would obviously not exist.

The original Better Music System was created by Xiran, and then improved by BTB
into the form that inspired me to create these config files to copy it as
closely as possible.

---------
Contact |
---------

Feel free to contact me on the Nexus with any comments or suggestions. You can
also find me on Discord as Necrolesian#9692.

-------
Usage |
-------

You can use this however you want.