PLUGIN: FMOD For AGS

[Calin Leafshade]

Hola!

Ok so I thought I'd try and implement Fmod in AGS and here is the result

http://www.thethoughtradar.com/AGS/FMODAGS/AGSfmodbin.zip
(source is available if anyone wants it)

3D sound/reverb works. Heres some basic usage:

Code: ags

// room script file
FmodSound *Sample;
FmodSound *Stream;
FmodChannel *SampleChannel;
FmodChannel *StreamChannel;

function room_AfterFadeIn()
{

Sample = FmodSound.Create("footstep.mp3", eFmodNoLoop, eFmodSpatial3D, eFmodLoadAsSample); //load a footstep as a 3D sample.
Stream = FmodSound.Create("music.mp3",eFmodLoop, eFmodSpatial2D, eFmodLoadAsStream); // load some music as a 2D stream.
StreamChannel = Stream.Play(); //start the music playing
StreamChannel.Volume = 30; //lower the volume (Valid values 0 to 100, default 100).
StreamChannel.Panning = -100; //pan the music hard left (Valid values -100 to 100, default 0).
FmodSetReverbPreset(eFmodReverbRoom); //Set the reverb preset (Default eFmodReverbOff).
FmodSetReverb3DProperties(0, 0, 0, 10, 20); // Set the 3D properties. parameters are x, y, z, mindistance, maxdistance.


SetTimer(1, 37); //lets set a timer!

}

function repeatedly_execute_always(){
  
    int LR = mouse.x - 160;
    int FB = 100 - mouse.y;
    if (LR < -100) LR = -100; //calculate some positions based on mouse coordinates.
  
  if (IsTimerExpired(1)){
    
    SetTimer(1, 37);
    SampleChannel = Sample.Play() //play the footstep.
    if (c != null) c.SetPosition(LR/20, 0, FB/20); //Sets the footstep position in 3D space.
    
  }
  
  if (c != null) Label1.Text = String.Format("%d", SampleChannel.GetPosMS()); // show the position in milliseconds.
  if (IsGamePaused()) Label1.Text = "Paused!"; // All channels will pause if IsGamePaused() returns true.
  
}

A note on 3D space

The units used are metres.

The plugin uses a left-handed coordinate system which means that +X = right, +Y = up and +Z = forwards.

The 3D listener is set at the origin and all 3D coordinates should be relative to that.

(-10, 0, 10) is ten meters to the left, zero metres up and ten meters in front of the listener.
(5,0,-2) is five meters to the right, zero metres up and two metres behind the listener

How is reverb calculated

Code: ags

FmodSetReverb3DProperties(0, 0, 0, 10, 20); // Set the 3D properties. parameters are x, y, z, mindistance, maxdistance.

The line above sets the reverb location and area of effect.

The first three ints are coordinates which indicate the epicentre of the reverbs effect. You should usually set this to the approximate centre of your room relative to the camera (imagine you are looking at the room through a camera and that it what the screen is showing).

The 4th int sets the starting falloff distance of the reverb. This is the distance at which the reverb begins to fall off and no longer apply.
the 5th int sets the end falloff distance for the reverb. This is distance at which the reverb will no longer apply to the 3D sounds you play.

In practice you can usually set the starting falloff to be half the size of your room (the radius of the effect) and the end falloff to some value higher than that.
These values are usually only important when there are multiple reverbs in play, which i havent done yet.

Speaker configurations

The plugin supports any speaker configuration and will use whatever the user has set in windows. (tested with 2.1, 5.1, 4.1 and stereo)
3D sounds will map to the available speakers as if in 3D space and 2D sounds will map to their correct channels (so you can play 5.1 music )

Filenames, Types, Streams and Samples

When running the game from the debugger the plugin will try and load the files relative to the main game directory (the one with game.agf in)
When running the game as a compiled exe the plugin will load the files relative to the folder with the game exe in.

The plugin supports OGG, MP3, WAV and loads others that I haven't tested (MOD, MIDI, AIFF, WMA, CDDA (you can load a CD by passing the drive letter like "D:"))

You should load large files, like music, as streams by passing eFmodAsStream to the CreateSound function.
Small files like SFX should be loaded as samples by passing eFmodAsSample.

Things that *DON'T* work

-Reverb customisation
You can load any of the reverb presets (which should be fine for most uses) but i haven't added functions to customise them yet.
You can also only have 1 reverb at a time.

-Additional DSP
I haven't added other DSP effects like Chorus, Delay, Phaser and stuff yet but I don't really think they are that necessary for most purposes.

LICENSE!! Be aware that FMOD is only free for non-commercial projects!!

TODO
- More DSP options

I think that's everything! Have fun!

[Sslaxx]

What would this have over the standard in-built sound system, with the exception of being able to use external sound files?

[Calin Leafshade]

3D Sound,
5.1 sound
Dynamic Reverb
DSP chain (chorus, phaser, whatever)

[Dualnames]

Bioshock and Starcraft II use this.[irony] They don't know shit. [/irony]

[Calin Leafshade]

I'll admit its something of a niche thing and for most people the standard sound system is fine (with the exception of the sound stuttering which seems to be giving a lot of projects serious problems)

But if you want to do something special with the sound system for your game then why not!

[xenogia]

I'll try this out tonight.  This will resolve my stutters within Face of Corruption under AGS.

[LimpingFish]

This is exactly the kind of thing I can get excited about! Hooray!

Once it gets fully implemented, I'll be all over this like filth on a hobo.

[Shane 'ProgZmax' Stevens]

I may be remembering this wrong, but I believe CJ said once, long ago, that AGS used a very early version of FMOD before they started requiring licensing fees for commercial use.

Forgive me if I'm wrong, but doesn't FMOD still require a license for using it commercially?  This is the main point of contention I've always had with it, anyway.

[Calin Leafshade]

Yes it does, as noted in the OP.

I would probably prefer to use OpenAL but it's a little out of my confidence bracket c++ wise.

FMOD is free for non-commercial use though so most AGS users would be able to get a kick out of 5.1, reverb, spatial audio and other, largely pointless features in their games.

One could argue that creating a plugin with a restrictive license is a pointless exercise but no one else seems all that eager to use the plugin API so I might as well use my limited C++ skillz to do something with it even if those skills preclude commercial titles.

Maybe my effort will prompt some of the real programmers to do something.

EDIT: I should qualify 'no one else seems all that eager' as 'very few people' and I didnt mean to belittle the work of those who *have* done stuff with the api.

[Dualnames]

Forgive me if I'm wrong, but doesn't FMOD still require a license for using it commercially?  This is the main point of contention I've always had with it, anyway.

http://www.fmod.org/index.php/sales

Yep, it pretty much does.

[Calin Leafshade]

Save states added. Games restore correctly now.

[Calin Leafshade]

Ok well the plugin is basically finished and working now. I just need to tidy some stuff up and thoroughly test it.

Would people please test this game and tell me if it errors/reverb doesnt work/whatever

http://www.thethoughtradar.com/AGS/FMODAGS/513DSoundTest.zip

[LimpingFish]

Working fine for me. Reverb on/off, no problems.

[Calin Leafshade]

Plugin released. See original post.

[Calin Leafshade]

Any bug reports/feedback would be appreciated if anyone has used it.

[Shane 'ProgZmax' Stevens]

I'm curious, Calin; does your plugin avoid the sometimes-annoying issue ags has with audio playback when skipping or transitioning cutscenes, ie, the note repetition as the audio engine stalls out briefly.  This is noticeable most recently with Gemini Rue, for instance.  I'm curious because at least for freeware titles I might use this as an alternative to avoid that issue until it's properly resolved.

[Calin Leafshade]

Yes, That issue is fully resolved with the plugin (as far as i can tell)

You can avoid all the 3D sound stuff by simply creating your music/sound as a 2D sound. Then it behaves almost exactly the same as AGS's built in audio but without the stuttering.

[bbalint85]

Yes, That issue is fully resolved with the plugin (as far as i can tell)

You can avoid all the 3D sound stuff by simply creating your music/sound as a 2D sound. Then it behaves almost exactly the same as AGS's built in audio but without the stuttering.

Wow, that's actually a pretty cool sideeffect, I'll definitely try this!  

Edit: I tried this, works fine! A few things:
-the sample code above has some errors, a missing ; and c should be SampleChannel
-can you give us some list of functions? for example how can I seek in the music?
-can I provide filepaths in the function? I tried FmodSound.Create("\AudioCache\au000040.mp3".., also /, \\, and I only get an error message (error:23) maybe It should be handled somehow...

Great work by the way, I'm looking forward to use it!

[Calin Leafshade]

-the sample code above has some errors, a missing ; and c should be SampleChannel

nice spot, thanks.

-can you give us some list of functions? for example how can I seek in the music?

I think most functions above are listed except for the seek one which is something like
channel.SeekPosMS(int timeInMillisecons); (might not be exactly right)
Auto complete is your friend.

-can I provide filepaths in the function? I tried FmodSound.Create("\AudioCache\au000040.mp3".., also /, \\, and I only get an error message (error:23) maybe It should be handled somehow...

Yes error checking does need to be handled better, I will look into it. (error 23 is file not found)
the format for filenames is "Folder/File.Extension".
Note that there is no leading slash and they are forward slashes.

Also I would advise that you create your own folder for media and dont use the audiocache. The audiocache is an internal folder used in AGS and you cant guarantee that the files will remain in there with the same names.

[bbalint85]

Yes error checking does need to be handled better, I will look into it. (error 23 is file not found)
the format for filenames is "Folder/File.Extension".
Note that there is no leading slash and they are forward slashes.

Also I would advise that you create your own folder for media and dont use the audiocache. The audiocache is an internal folder used in AGS and you cant guarantee that the files will remain in there with the same names.

Sure, it was just for testing purposes. Now everything works, thanks!