LuteMod

LuteMod is a mod for Mordhau that allows you to choose songs in-game, and move freely while playing

LuteMod was created by Monty and updated by D.Mentia. FLuteMod\_1.3+ is required for Shawm support

LuteBot must be used to add songs (called Partitions) to LuteMod

## Install

As of LuteBot 3.3.0, manual install is no longer required.

* LuteBot can automatically perform both Install and Initialization. See LuteBot Install
* Inside LuteBot, if you're not prompted automatically, you can choose `Options -> Install LuteMod`
* Once this is complete, you can skip to Adding Songs

This should solve the crash on Mordhau startup from an old version. LuteBot 3.3.1+ will also remove the offending line from engine.ini, to prevent future crashes, since the new ModLoader no longer needs it

If you are still getting crashes, you can reset your Mordhau install to default. Right click Mordhau, go to Properties, then Local Files. Select 'Verify Integrity of Game Files' as shown, then use LuteBot to reinstall LuteMod

###### Manual Install

If the LuteBot auto-install is not working or you don't want to use it, you can follow these steps to install LuteMod manually

Pak files are all installed by pasting or extracting the Pak file into `C:\Program Files (x86)\Steam\steamapps\common\Mordhau\Mordhau\Content\CustomPaks` (substitute your Mordhau path if necessary)

You will have to create the CustomPaks folder the first time you install one

1. Download Clientside Mod Autoloader
	* Download `autoloaderwindowsclient.zip` (or the most recent release), and unzip the Pak file into `Mordhau/Content/CustomPaks`
2. Download LuteMod
	* Download the most recent `lutemod.n.zip` and unzip the Pak file into `Mordhau/Content/CustomPaks`
3. Add these lines to the end of `Game.ini` at `%localappdata%\Mordhau\Saved\Config\WindowsClient` (You can paste that directly into your file address bar)

`[/AutoLoader/BP_AutoLoaderActor.BP_AutoLoaderActor_C]

ClientMods=/Game/Mordhau/Maps/LuteMod/Client/BP_LuteModClientLoader.BP_LuteModClientLoader_C

ModListWidgetStayTime=5.0

[Mods]

ModStartupMap=/AutoLoader/ClientModNew_MainMenu.ClientModNew_MainMenu`

###### First Use

After your first manual installation, you must initialize the partitions.  If you’ve used LuteMod previously or LuteBot installed it, you probably already have a PartitionIndex and can skip this step

1. Start Mordhau, and verify that the modloader pops up on the main menu, and shows lutemod is loaded.
2. Open a local map
3. Wait a few seconds for it to load, equip a lute, and press Kick until you see a Partition Menu

Once you've seen this menu, you can begin adding songs

## Controls

The important LuteMod controls are bound to your Mordhau controls, so you can change Mordhau keybindings to change LuteMod keybindings

The controls are listed here with their Mordhau counterpart

* Open Partition List/Next Page - Kick (Default F) (Closes partition list if you reach the end)
* Select Partition - Choose 1-9 (Default 1-9) (NOTE: This may be different from your equipment selection bindings)
* Play/Pause - Feint (Default Q) (NOTE: Not Feint/Parry, which is a different action)

These controls are advanced and not usually needed, but do not have a Mordhau binding counterpart, and can't be changed currently

* Octave Up - Arrow Key Up (While Playing) (Currently equipped instrument)
* Octave Down - Arrow Key Down (While Playing) (Currently equipped instrument)
* Next Page - Kick (Default F), Arrow Key Right
* Previous Page - Arrow Key Left
* Next Page x5 - Ctrl + Arrow Key Right (Does not close list if you reach the end)
* Prev Page x5 - Ctrl + Arrow Key Left
* Flute Cutting Up - Ctrl + Arrow Key Up (Flute ignores copied or mirrored notes in the lowest N octaves)
* Flute Cutting Down - Ctrl + Arrow Key Down (Flute ignores copied or mirrored notes in the lowest N octaves)
* Toggle Note Duplication - Shift + Arrow Key Up (Currently equipped instrument does not remove queued notes when playing them)
* Toggle Copying - Shift + Arrow Key Down (Currently equipped instrument type copies notes from the other instrument type)

## Adding Songs

You can add songs to your LuteMod with LuteBot. In LuteMod, these formatted songs are called 'Partitions'

1. Load any midi through clicking the Load Midi button, or the Guild Library
2. If it's not already, open the 'Track Filtering' menu with the button at the top of LuteBot
3. Ensure the selected instrument is correct, Mordhau Lute or Mordhau Flute
	* You may filter the song differently for each instrument to be able to play either or both. It is recommended to have only one 'instrument' enabled on the MIDI for Mordhau Flute. Some MIDIs will automatically load settings that others have set for Mordhau
4. If it's not already, open the 'Lutemod Partitions' menu with the button at the top of LuteBot
5. Click 'Save Current Song' in the Partition menu.  A pop up box will ask you to name it, and it should add it to the partitions
	* Short names should be used when possible, both to fit in the screen, and to avoid the LuteMod Oversized Partition bug

Note that older tutorials may show a LuteMod Converter - that converter isn't updated to new Mordhau instruments, and you should generally use the LuteBot conversion

You can change the LuteBot Settings to automatically open the appropriate menus on startup (they should do this by default)

## Playing Songs

In-game, the controls are as follows (you must have a Lute or Flute in hand, the lute must not be in weapon mode, and it may take 10-20 seconds after match start before it's initialized)

**Kick**: Open song/partition menu, or go to next page, or close menu if at last page

**Number Keys (Equipment Select)**: Select song from menu. Only while partition menu is open

**Feint**: Play/Pause Song

## Getting Songs

   The easiest way to find songs that are already curated for Mordhau are through the Guild Library in LuteBot

* These songs are downloaded to `%appdata%/LuteBot/GuildLibrary/songs` when you load them (if you don't already have them)
* The Mordhau Score is a bit outdated, but might still be a good indicator if a midi has been edited or not
* Only the top 20 results are returned; you must be specific. There is no way to browse the full library at this time

You can also Download your songs from the internet

* Just google for 'song name midi' or 'artist midi'
* Many niche artists and songs don't have midis; you'd have to make one
* You cannot convert an mp3 or other sound file to a midi file (it will sound terrible)
* Not all songs sound good on lute, which can't hold long notes, or flute, which can't play complex pieces

If you're an initiated member of The Bard's Guild, you can also check the #midi-submissions channel for midis, or use /search inside the discord

## Fixing Songs

Since the lute now plays more notes, many songs will be bad by default.  Here's my simple troubleshooting process:

1. Load the song in LuteBot
2. Open the Track Filtering menu if it's not already (Window -> Track Filtering)
3. Click on the 'Advanced' button in the bottom left of Track Filtering.  This should show all instruments on the piano roll
4. Play the song in a local match, via Lutebot.  Watch the instrument colors light up when they play.  If you get to a part that sounds bad, uncheck the box in Track Filtering for one of the instruments that lit up
5. If it's still messy, consider disabling any tracks that cover the same range as others; if there are two Acoustic Grand Pianos that both are the same size and play at mostly the same time, you can usually get rid of one
6. Consider disabling any instruments that lute can't reasonably mimic; strings, bells, etc
	* (Optional) When satisfied with the song, save it
7. Once it plays well in Lutebot, 'Save Current Song' into the **LuteMod** Partitions, and test it in LuteMod.  It should use all the same settings that you just set

Note that you can also move the entire song, or any individual instrument, up or down octaves by dragging the song or instrument's box in Track Filtering.  You must disable advanced mode to move the entire song

## Flute Configuration

If using FLutemod 2.0+, the Shawm(Flute) is playable with **LuteMod**, and all instruments in your inventory can play notes, even when not equipped. Follow these steps to configure a midi to use the flute:

1. Load the song in Lutebot
2. Open the Track Filtering menu if it's not already (`Window` -> `Track Filtering`)
3. Set the instrument to either `Mordhau Lute` or `Mordhau Flute`
4. Adjust the song as necessary using the instructions for Fixing Songs, and check/uncheck tracks or channels that you don't want played on that instrument
5. Once you are satisfied with one instrument, change to the other, and adjust the settings there as appropriate
	* Flute can only play one note at a time, ignores '`Notes Per Chord`', and does best with only 1-2 channels/tracks selected for it.  It is usually great at playing vocals, or brass instruments. If you carry multiple flutes, it can play more channels/tracks
	* It’s usually best to make sure your Lute is not playing the track that your Flute is playing, to help the flutes stand out
	* (Optional) Use '`Save As...`' to store your settings into a new midi.  The midi now contains your settings for both instruments and can be distributed to the Guild Library
	* LuteMod offers options to copy notes from one instrument to another when playing, so you should always configure both instruments, and if someone wants to play it with only one, they can use those options
6. If it's not already, open the 'LuteMod Partitions' menu with the button at the top of LuteBot's main menu
7. Click 'Save Current Song' in the LuteMod Partitions window, and name your song for Mordhau

Lutemod will automatically detect which instruments you have in your inventory and choose which notes they play.  If at least one of each instrument is in your inventory, it will play everything

Or, more simply: Open the song on Lute.  Find the vocal track and disable it.  Change to Flute.  Disable all but the vocal track.  Save as partition, play

## Chords

While LuteMod is capable of playing as fast as it wants for the user, Mordhau networking only allows others to hear the notes if they are played with at least a 16ms cooldown (the actual value may be lower, but in our tests, this was as low as we could go without dropping some notes in some songs)

In order to play chords, which are multiple notes within the same tick in a MIDI, it must queue them up and play them one after another, much like LuteBot's Chords.

Unlike LuteBot, LuteMod implements an actual queue. Each time a MIDI tick elapses and has notes, it stores all notes for that tick into its queue, erasing any previously queued notes. It then (re-)starts a function that repeats every 16ms, to play notes from the queue and remove them once played.

This means that chords occurring before empty sections can be played fully, and fast sections should play accurately, automatically prioritizing new notes over chords when playing the chords would cause timing problems.

In LuteMod 1.2+, this was adjusted to keep the most recent note in the queue (instead of clearing all of them) when a new note needs to be played, allowing for much fuller chords, while not causing any noticeable slowdowns during fast sections

Due to this difference in how LuteMod and LuteBot handle chords, songs saved as Partitions may sound slightly different when played

## Known Bugs

###### Skipped Notes

For LuteMod versions 1.1 and above, converted to the new Mordhau framework, LuteMod will sometimes skip notes when playing the same note quickly and repeatedly, such as in Mrisilou

* I am unsure if this was added in 1.2 with the queue adjustment, or if the new Mordhau Engine is discarding the notes for some reason. Haven't been able to find the problem yet -D.Mentia

###### Corrupt Partition

Causes Mordhau to crash when opening some partitions

* Mordhau's .sav files are apparently volatile. If edited without software, they have a chance to fail to load even when the size is preserved
* Even when editing with software, there seems to be a random chance that any given .sav file set will fail. Deleting and re-saving the partition usually resolves the issue
* I want to investigate this further, according to Monty they're unstable, but that doesn't really add up to me - there must be something going wrong in a rare case when creating the partition, but I haven't found anything, or really been able to reproduce -D.Mentia

###### Oversized PartitionIndex

Causes Mordhau to crash when opening some partitions. May cause some partition names to be shown incorrectly in-game

* Occurs when the PartitionIndex file becomes large enough to generate an additional file, and a song's name spans between multiple files
* This can be delayed by keeping song names short, so that many songs can fit within a single PartitionIndex
* More songs can be added as normal, or the same song can be added again and it should work, but you will have to avoid loading the partition(s) that got corrupted, forever. Deleting it will simply make the next song corrupt instead, so it needs to stay. You may delete it and rename it to something of similar length to help you avoid selecting it
* Alternatively, you can remove the corrupt song, then save the old '`PartitionIndex[0].sav`' file under a different name somewhere, and create a new PartitionIndex via LuteMod Initialization. You can then rename either file back to '`PartitionIndex[0].sav`' to use that set of songs the next time you open the LuteMod menu in-game
* This will be fixed eventually. I haven't really figured out how the file reading code in LuteMod works yet. -D.Mentia