Sound Entities in Level Editor

[AGP]

I successfully added one of the pre-exsisting Amnesia sounds files to my map and when I loaded the custom story story to the game, the sound played (as the player start area is right by where I placed the sound entity). I was wondering, is the entity activated when the player approaches it? I'm not quite sure what the controls in the level editor are/how they are used and was hoping someone might be willing to explain it. =)

[Your Computer]

Each sound has a minimum and maximum range that the player has to be in to hear the sound. These can be overridden by adjusting the sound entity's parameters.

[TheGreatCthulhu]

Yeah. Also, from my experience, when using Sound entities, the playback is started as soon as the level loads - but it can be heard only if you are in range. If it's not a looping sound, it will simply stop when it reaches the end of the audio clip, after which you can play it again using this script function:

Code: (Select All)

void FadeInSound(string& soundEntityName, float fadeInTime, bool playStart);

The documentation doesn't say what the third parameter does, and I wasn't able to figure it out, so just pass either true or false.

If it's a looping sound, it will loop during your time in the level.

You can stop both types of sounds using the StopSound(/* ...params omited... */ ) script function (see the wiki for details).


All that said, you'll have more flexibility with this:

Code: (Select All)

void PlaySoundAtEntity(
    string& internalSoundResourceID,
    string& soundFileName,
    string& targetEntity,
    float fadeInTime,
    bool rememberPlaybackState   // restores playback for looping sounds when the lvl is revisited
);

Using that function, you don't have to use Sound entity objects, you can simply refer to a sound file, and easily create audio feedback for collisions and other events - but then you can't set the range where the sound will be audible (the settings from the sound file will be used).

[AGP]

Okay. Great. Thank you. =D

I didn't script for the sound in the hps file. Would the script go under void OnStart or void OnEnter? I'm only about a week into making this and have no prior experience with this sort of thing so I'm not quite sure what I'd be doing with this script.

Also, the sound file name is 05_event_door_bang.snt if that helps.

[TheGreatCthulhu]

OK, then first things first.
The OnStart() function is called by the engine the first time the player enters a map. The game then invokes OnEnter(), but OnEnter() is also called every time the player comes back to the map (if level design allows for backtracking). OnLeave() is called every time the player exits the map.
(BTW, don'g get confused when I write FuntionName() - I just use the () as a way of quickly
distinguishing functions from other names, like variables and such, when
talking about it in forums; the actual parameter list is ommited, if
any.)

Now, this isn't very useful in itself for the purposes of scripting sounds, except that you can call PreloadSound() there (in OnEnter() func). But, what you can do there is hook up functions that are going to respond to various events, usually collisions.

Normally, you'd have a Script Area placed in the map, in a strategic location, and then play a sound when the player collides with it, or maybe you'd check for a collision with an entity, or something along those lines.

Let's say you have a passageway, and you want some scary sound to play when the player emerges from it. You'd place a script area named at the end of the passageway (so that the player must hit it). Let's also say you named it "AreaScarySound".

In the corresponding script file, in OnStart(), you'd then call the AddEntityColideCallback() function to tell the script what should happen on player-ScriptArea collision.

Now, this may look intimidating now, but bear with me, it's rather simple.
This is the declaration of the AddEntityColideCallback() function (note: this is the declaration, so this is not how you call it, this just describes the format of the function; also white space doesn't matter here - I formatted the code in this way so that it's easier to read):

Code: (Select All)

void AddEntityCollideCallback(
    string& parentColliderName,
    string& childColliderName,
    string& callbackFunction,
    bool deleteCallbackAfterCall,
    int whenToCall
);

The parentColliderName and childColliderName are simply the names of the objects you want the engine to check for collisions. The callbackFunction parameter is the important one: it's a name of another function in your script that should be called when the collision is detected (known as the "callback" function). It can be any function, but it has to have a certain "format" - I'll come back to that in a moment. The deleteCallbackAfterCall parameter can be either true or false. If true, the callback function will be called only after the first collision; if false, the callback will be invoked every time a collision is detected.
The last parameter tells the engine when exactly the callback should be called during a collision event; value of 1 means only on enter (when they first overlap), -1 means only on leave (when they stop overlapping), and 0 means on both.

The callback function is defined by you elsewhere in the file, and it has this format:

Code: (Select All)

void YourFuncName(string &in parent, string &in child, int state)

All of it's parameters are input parameters, and are passed in by the engine when the function is called (on a collision event), so that you can use them to check some things. The state parameter here has the same meaning as the whenToCall parameter above, except it can only be 1 (enter), or -1 (leave).

So, how it all looks when you put it together?

Code: (Select All)

void OnStart()
{
    AddEntityCollideCallback("Player", "AreaScarySound", "PlayScarySound", true, -1);
    // other stuff omitted...
}

// other functions omitted...

void PlayScarySound(string &in parent, string &in child, int state)
{
    PlaySoundAtEntity("id.my.scary.sound", "general_wind_whirl.snt", "Player", 0.5f, false);
}

Aaaand - that's it.

A few comments. Note that the 3rd parameter to AddEntityCollideCallback() is the name of the callback function, as you defined it below. It has to match exactly - even in casing, since the script language is case-sensitive (you can't write, say "playSCARYSounD"). The next parameter behind it is set to true, so the callback will be invoked only once, and -1 tells the engine that the callback is called when the Player leaves the script area's volume.
The other function, PlaySoundAtEntity(), takes string as a first parameter, that will be used as an internal id of the sound resource. You can put there anything you want; later on, you can use it in the StopSound() function to tell it which sound should be stopped (if it's a looping sound). The next parameter is the sound you want to be played - here in the example I used ""general_wind_whirl.snt", which comes with Amnesia.

That's pretty much it.

[AGP]

Thanks TheGreatCthulhu! Got it working and it sounds scary as hell! =D I appreciated the help a lot.

First map pretty much completed and on to the second!