Quick start

So, you want to use Phonix, here is a guide to get you started in no time!

Setting up

So, for Phonix to be operational there are a few things we must do.

First, we want to create a object that is persistent and initialize it at the start of out game, inside this object there are 2 things we need to do, first is to call PhonixTick() in the end step event, this function must be called every frame in order for Phonix to run smoothly, and the second is to create a group that we'll be using later on to organize our sounds, we'll do that in the create event of our object(keep in mind that the second step is optional, if you do not wish to have groups you can simply leave the group argument undefined and it will default to the "master" group).

//Create event 
PhonixCreateGroup("testGroup", 1);

//End step event
PhonixTick();

Playing sounds

After that we'll want to play some sounds, so in the create event of a object that plays sounds we'll want to create a pattern, we'll do that using one of the following functions: PhonixCreateSingle(), PhonixCreateQueue(), PhonixCreateRandom(), to view the required arguments as well as differences between patterns, click here.

//Create event
newPattern = PhonixCreateSingle(musicTrack1, false, 5000, 2000, "testGroup");

What I have done above is created a new single pattern that will be playing musicTrack1, won't be looping, will have a fade in of 5000 milliseconds, a fade out of 2000 milliseconds, and will be part of the "testGroup" group that we created previously.

Note: after using the PhonixPlay() function, the pattern is no longer required, so if you do not wish to use it anymore you can safely discard it by setting newPattern = -1.

Now, onto actually playing the sound:

//Step event
if(keyboard_check_pressed(vk_enter)){
  soundID = PhonixPlay(newPattern, 0);
}

With the code above, when we press enter the newPattern pattern will be played, and it will return a struct of a sound player, through this struct we can further manipulate the sound that is being played.

Congratulations, you just got a sound playing in your game using Phonix!

Stopping/Pausing

So, we got the sound playing, cool, but now we wish to stop it before it finishes, for that we will use 1 of 2 functions: PhonixStop() or PhonixStopNow(). The key difference between the two is that when using PhonixStop() there will be a 2 seconds(2000 millisecond) fade out before the sound if considered as finished, however if PhonixStopNow() is called, the sound will be stopped immediately and there will be no fadeout.

Also, it's worth noting that there are a couple of way to utilize the functions above, and that is with either a soundID, a specific group name, or "master" group name which will stop all sounds currently playing.

//Step event
if(keyboard_check_pressed(vk_space) && PhonixValueIsValid(soundId)){
  PhonixStop(soundID);//Stops only this instance of the sound
}

if(keyboard_check_pressed(vk_space) && PhonixValueIsValid(soundId)){
  PhonixStop("testGroup");//Stops all currently playing sound instances whose patterns belong to the "testGroup" group
}

if(keyboard_check_pressed(vk_space) && PhonixValueIsValid(soundId)){
  PhonixStopNow("master");//Stops ALL currently playing sound instances immediately regardless of their fade out values 
}

The PhonixPause() and PhonixResume() function work the same as PhonixStop(), meaning that a fade in/fade out will be applied.

Playing 3D sounds

Now that you know how to play regular sounds, it's time to learn how to play 3D sounds! These sounds can be very useful when you wish to convey to player which direction a sound is coming from, so lets see how to play them!

Listener

Playing 3D sound requires a bit more preparation then playing normal sounds, mainly we'll need a listener, currently Phonix supports only 1 listener. So, to create a listener we'll be using the PhonixCreateListener() function.

//Create event of out player
listener = PhonixCreateListener(x, y);

You can further manipulate the listener using these methods.

3D sounds

So now that we have out listener set up, it's time to play 3D sounds, playing 3D sounds isn't much different from playing normal sounds, it just requires a few more arguments:

//Step event
if(keyboard_check_pressed(vk_enter)){
  soundID = PhonixPlay(newPattern, 0, 125, 225, 0, 50, 100, 1);
}

The code above looks very similar to the code for playing normal sounds, we just added a few arguments, so what does the following code do? Well, we are again playing newPatter, but this time we're playing it at coordinates x = 125, y = 225, z= 0(for 2D games you generally want to keep the z coordinate at 0) and we're setting the falloff_ref = 50, falloff_max = 100 and falloff_factor = 1.

And that's it, you now have 3D sounds in your game!