Music.zh

Foreward
Music.zh is a header for ZScript that contains functiosn for the handling of audio, and music files. In particular, it has ffcs and functions for the use of boss music, special enemy music, and similar, using MIDI files, enhanced music files, or both.

Here is an updated version of Music.zh, v1.3.1 (mirror on Pastebin), that fixes a minor bug, and a demo quest that demonstrates how to use the enhanced music ffc for bosses, with included NSFs as a ZIP file.

This version also adds some additional, (unproven) ffc scripts, and cleans up some functions. If you were using an older version, the return type on the function PlayEnhMusicFile(int filename_message, int trk) has changed from float, to bool, but I added a legacy conversion function for such cases. The function itself works slightly differently, though, so you may need to check that scripts using it still work as you intend them to work.

As of v1.3.1, Music.zh includes a global function ( WandSound(int sfx) ) and a demo global active script that allows you to assign a sound to the wand, for slashing, or stabbing, that will play even if the magic projectile does not fire; and this sound is separate from the firing sound.

The demo quest features most components of this header, including the following:

• ffc script playMIDI : Plays an arbitrary MIDI on a given screen.
• ffc script NPC_MIDI : Plays a MIDI while an enemy with a specific ID is on-screen
• ffc script NPC_Music : Plays an enhanced music file, while an enemy with a specific ID is on-screen.
• ffc script BossMusic : Set up MIDIS for a boss theme, victory jingle, and post-boss-death music.
• ffc script BossMusicEnhanced_InternalStrings : Use Message Strings to supply the filenames, for boss music with many configuration options.
• ffc script music_zh_spawnnpc : Spawns an arbirary NPC on collision with the ffc, at the screen coordinates of flag 37 (NPC ID 0).
• global script Music_ZH_Global_Active : A demonstration of the WandSound(int sound) function.

I will continue working on it as time permits, and possibly create a demo for the rest of its features. For the moment, most of the requests that I have had have related to the enhanced boss music functions, so that is what you will find in the demo.

Feel free to submit functions for inclusion if you wish, or to make suggestions, if you feel that it is lacking.

One aspect of NPC_MIDI and NPC_Music is unproven: They are designed to restore enhanced music on a DMap that has it, when they npc dies; and this is untested. The behaviour is as follows:

Code:

---

                int enh_music[256] = {0};
                Game->GetDMapMusicFilename(Game->GetCurDMap(), enh_music);
               
                int enh_trk = Game->GetDMapMusicTrack(Game->GetCurDMap());
                for ( q[0] = 0; q[0] < 256; q[0]++ ) { if ( enh_music[q] == ' ' ) enh_music[q] = 0; } //kill the space.
                bool enhanced =  ( enh_music[0] != 0 ); //is the dmap music enhanced?

---

I will need to validate what happens here, but it should be correct.

This header requires string.zh for ZC v2.50.3RC1 and lower.