Features

• Music and sound stuff galore!
   

  • Enhanced music using MP3 and OGG can now be given loop points and crossfade timings in the DMap editor. The music will then loop at those points and fade in and out with those timings.
  • Scripts have new ways to interact with enhanced music: GetMusicPos(), SetMusicPos(), SetMusicSpeed(), GetMusicLength(), and SetMusicLoop()
  • Scripts can also play music with crossfades using CrossfadeEnhancedMusic().
  • Scripts can play sounds with different, volume, pan, frequency, and looping with PlaySoundEx().

  // Turns a SFX into an instrument by playing it back at different frequencies
  ffc script Piano
  {
     void run()
     {
         // Frequency values and keys for different notes
         int hz[] =   {16350L, 17320L, 18350L, 19450L, 20600L, 21830L, 23120L, 24500L, 25960L, 27500L, 29140L, 30870L, 32700L};
         int keys[] = {KEY_Z,  KEY_S,  KEY_X,  KEY_D,  KEY_C,  KEY_V,  KEY_G,  KEY_B,  KEY_H,  KEY_N,  KEY_J,  KEY_M,  KEY_COMMA};
         int sz = SizeOfArray(hz);
         int sfx = Rand(60); // Pick a random SFX
         while(true)
         {
             for(int i=0; i<sz; ++i)
             {
                 if(Input->KeyPress[keys[i]])
                 {
                     int j = (hz[i]/hz[0]) * 22050L; // Multiply by the sample rate of most default SFX
                     Audio->PlaySoundEx(sfx, 100, 0, j);
                 }
             }
  
             Waitframe();
         }
     }
  }

  • Scripts can also adjust sounds mid playback with AdjustSound() and track their completion with GetSoundCompletion().

  ffc script AdjustSound
  {
     void run()
     {
         // Play the sound panned to the left at half volume
         Audio->PlaySoundEx(SFX_SECRET, 50, -128, -1, false);
         // Run until the sound has stopped playing
         while(Audio->GetSoundCompletion(SFX_SECRET)!=-1)
         {
             int pct = Audio->GetSoundCompletion(SFX_SECRET) / 100;
             // Pan the sound to the right while increasing in volume
             Audio->AdjustSound(SFX_SECRET, Lerp(50, 100, pct), Lerp(-128, 127, pct), -1, false);
             Waitframe();
         }
     }
  }

  • Scripts can set MusicRefresh to prevent music from resetting when changing screens

  Audio->PlayEnhancedMusic("ExampleSong.ogg", 0);
  Audio->MusicRefresh = MR_DMAP; // Music will refresh on changing DMap
  Audio->MusicRefreshFlags[MRF_REVERT] = true; // Music refresh with revert to default behavior afterwards

  • AdjustMusicVolume() and AdjustSFXVolume() have been reworked to be a multiplier capped at the user's volume settings, rather than overwriting those settings.

   
  Relevant changes:

  • feat: music looping and length functions for ogg and mp3 0d00efce4
  • feat: add enhanced music loops for dmap music 8c6f66142
  • feat: add enhanced music loops for dmap music 1bf93ebc3
  • feat: PlaySound with different volume, pan, and loop f7afa08a7
  • feat: added frequency param to PlaySound() 51931b91f
  • feat: added crossfading enhanced music d03c55c0d
  • feat: dmap editor crossfades 5e34b007c
  • feat: zscript access for dmap crossfades 435449e33
  • feat: MusicRefresh setting for ZScript 5df225ec7
  • feat(zscript): music seeking functions for ogg and mp3 463a6d1dc
  • feat(zscript): dmapdata music loop point access fc8fa9918
  • feat(zscript): GetSoundCompletion() a2df0883a
  • feat(zscript): Split MusicRefresh into MusicRefresh and MusicRefreshFlags[] 679b79c50
  • fix: changed how crossfades interact with F1/F4 9274b2990
  • fix: fademiddleframes in CrossfadeEnhancedMusic() 2fb00213c
  • fix(zq): missing mirrorDMap and loop points from dmap import and export b694fba13
  • fix(zscript): CrossfadeEnhancedMusic() now keeps playing old music on failure and returns a proper result 57c6aa58b
  • fix(zscript): rename expanded Audio->PlaySound() function to PlaySoundEx() e96efb263
  • fix(zscript): GetSoundCompletion() crash when the sound is not allocated edf58c67d
  • docs(zscript): docs for Crossfades and MusicRefresh 589df961c
  • docs(zscript): webdocs for new Audio features 93ec63eea
  • chore: attempt to fix ubuntu compile 0f17db7cc
  • chore: Merge branch 'main' into music-backup 8c3412b96
  • chore: merge main into music branch 11d792fb4

Chores

• modify changelog for recent music additions 0c2a8aeb9

CI

• also show changelog relative to last alpha for nightlies 1025e5c88

Misc.

• support squashing and rewriting commit body for changelogs 7c6430abe