MusicPlus core: Song length, positioning, and fading features with Linedef Exec and Lua support

This is the reason why music-cleanup was proposed (!278 (merged)). This is also a prerequisite for libopenmpt and non-native MIDI.

This branch adds music seeking and fading to the engine, as well as Linedef Exec and Lua support.

See comments for Linedef Exec and Lua documentation.

Implementation

• The position/seeking methods depend on a new music tag LENGTHMS=milliseconds
  • This tag is necessary because SDL Mixer cannot detect song length.
  • Without this tag, the seeking will still happen, with the following side effects:
    • Seeking past the end of the song may reset the "listening" position at 0, but the internal position counter will increment from the erroneous seek position. It will never reset to 0 until the music is changed.
    • Any future features that depend on reading song position will not work correctly (e.g., jingle resuming) until the music is changed.
  • The game spits a warning in DEVMODE 2 (detailed) if this tag is not present.
  • OGG, FLAC, and MP3 support this length tag. GME and MOD do not need this tag. MIDI cannot use this tag.
  • Auto-tag all your music lumps by running your WAD through musiclengthms.zip (Source). music.dta could use this treatment for future releases.
• The fading method implements an "internal music volume", a percentage of the user's configured game volume.
  • When an internal volume of less-than 100% is applied, the game adjusts the playback volume to make the song quieter. This is always relative to the user-configured volume. Fading is accomplished by incrementing this internal volume per millisecond.
  • I do not use SDL Mixer's Mix_FadeIn/OutMusic() methods due to these reasons:
    1. They are thread-blocking, e.g., the game window cannot exit until the fade is completed
    2. They cannot be interrupted in the middle of the fade
    3. They do not respect the user's configured volume (at least not easily)
    4. They do not work on GME
  • MIDI cannot fade due to the Win32 volume hack

Test Files

• test_music.wad - Collection of music lumps in different formats
• test_musicplus-safe.lua - Lua functions for testing; type musichelp in console for a list of these
  • Sample: musicchange MAP02M 1 0 10000 2000 1000 - Switch to MAP02M music, looping enabled (1), track 0, jump to position 10000, fade out for 2000 ms, fade in for 1000 ms
• test_le-music.wad - Linedef executor test for fading and positioning functions
• Srb2-21-changemusic.cfg - ZoneBuilder config for the updated Change Music linedef exec features
• EXE binaries
  • 32-bit EXE
  • 64-bit EXE