PlaySoundPosEx.cog

This cog plays a sound at one of 4 locations, either a thing, surface, sector or a free vector position. But it only plays the sound when the source location is within earshot of the viewport. Note, I say viewport because this will also work if the camera view is seperate from the player.
The other features of this cog is that it pitches the sound according to the reletive moving speed between the viewport and the sound's source location, pitches the sound down to half its speed when one or the other is underwater, reduces the volume when the thing emitter isn't in view, and the ability to control this cog remotely from another cog.

When loaded into the level you'll find the following symbols you can set:

• audio(sound): The sound that you wish to play.


• thingLocation(thing): The sound will emit from this thing.


• playFromThing(int): Set to 1 if you want the sound to play from this thing. Otherwise no sound will play from the thing.
  If set to 0, then might as well set the thingLocation to -1.


• surfLocation(surface): The sound will emit from the center of this surface.


• playFromSurface(int): Set to 1 if you want the sound to play from this surface. Otherwise no sound will play from the surface.
  If set to 0, then might as well set the surfLocation to -1.


• sectorLocation(sector): The sound will emit from the center of this sector.


• playFromSector(int): Set to 1 if you want the sound to play from this sector. Otherwise no sound will play from the sector.
  If set to 0, then might as well set the sectorLocation to -1.


• Location(vector): The sound will emit from this "floating pointing".


• playFromVector(int): Set to 1 if you want the sound to play from this location. Otherwise no sound will play from here. Please enter a vector value here even if not used, like (0/0/0) (center of world).


• vol(flex): Sets the volume at which the sound is to be played at.


• mindist(flex): Sets the minimum distance from the position at which the sound can be heard at full volume.


• maxdist(flex): Sets the maximum distance from the position at which you can hear the sound.


• sndflags(int): Sets the sound flags for the sound. Do note that you may need to convert the Hexadecimal values to Decimals values when entering in these values. If the loop flag (0x1) is not set, then you must manually start the sound by sending it a user5 message. More on messages further down.
  
  The above values are the same as if you used the actuall PlaySoundPos/Thing verbs.


• extrapitch(flex): Gives the sound an initial pitch from the beginning, for when you want a rumble to sound extra low (super huge machinary), or a motor to sound extra high (buzz saw). A value of 1.0 is normal.


• waterpitchfactor(flex): This will multiply the pitch of the sound when the viewport or the thing is underwater.
  A value of 0.5 will half the pitch and depending on the sound may sound like it's being muffled, but may just sound ugly. Avoid using music with this.


• speedfactor(flex): This will affect the pitching factor relative to passing objects. If one has a ship that flies by extra fast, chances are that the passing pitch can go too far one way or another. Increasing this value will make the passing pitch not go as far.


• echo_cog(int): This allows you to link this cog to any other cog, like maybe an echo cog, or some other event linked to this sound.
  Leave as -1 if not used.


• trigID(int): This is an ID for the echo_cog. Sending a number from 0 to -7 (negative 7) will call user0 to user7. Sending a positive number will send a trigger instead with the number as the ID. Parameters sent are as follows:
  0. The audio. GetParam(0)
  1. A combination of volume + looping. If the value is negative, the sound is looping. GetParam(1)
  2. The maxdist value. GetParam(2)
  3. A combination of the 2 pitches (normal and watered). GetParam(3)
     The waterpitchfactor is multiplied by 100 000 and then added to the extrapitch.
     This is done because JK can't handle pitches higher than 4 or lower than 0.01.
     To retrieve the waterpitchfactor, divide the value by 100000 (GetParam(3)/100000).
     To retrieve the extrapitch, modulate the value by 4 (GetParam(3)%4).

One can also control the cog remotely by using triggers and messages. You will have to be familiar with SendMessageEx() and SendTrigger().

• SendMessageEx(PlaySoundPosEx.cog number, user0, 0, 0, flex fade_time, flags emitter);
  Using this will silence one or more of the emitters.
  fade_time: This will fade the sound out over the specified period (in seconds).
  emitter: This is a flag of the different emitters you can affect.
  • 0x0 = All sounds are turned on
  • 0x1 = Turn off the thingLocation.
  • 0x2 = Turn off the surfLocation.
  • 0x4 = Turn off the sectorLocation.
  • 0x8 = Turn off the free/vector Location.
  If you wish to use triggers instead, then the syntax looks as follows:
  SendTrigger(-1, PlaySoundPosEx.cog number, 0, 0, flex fade_time, flags emitter);
  Notice the cog is being used as the trigger ID. This is done because the cog tests to see if the GetSourceRef() is GetSelfCog() (aka, the cog number like when assigning a seperate cog).



• SendMessageEx(PlaySoundPosEx.cog number, user1, 0, flex volume, flex mindist, flex maxdist);
  Using this will change the volume properties of the sound. See the symbols on vol, mindist and maxdist.
  If you wish to use triggers instead, then the syntax looks as follows:
  SendTrigger(-1, PlaySoundPosEx.cog number, 1, flex volume, flex mindist, flex maxdist);



• SendMessageEx(PlaySoundPosEx.cog number, user2, 0, flags sound_flags, flex extrapitch, flex waterpitchfactor);
  Using this will change the sound flags, the extrapitch, and the waterpitchfactor of the sound.
  Do note that if the flags do change, the sound will be restarted.
  If you wish to use triggers instead, then the syntax looks as follows:
  SendTrigger(-1, PlaySoundPosEx.cog number, 2, flags sound_flags, flex extrapitch, flex waterpitchfactor);



• SendMessageEx(PlaySoundPosEx.cog number, user3, 0, flex volume, flex duration, 0);
  Using this will change the volume over a period of time.
  volume: The new volume to be reached.
  duration: The time it takes to reach it.
  The last parameter isn't used.
  Do note that any special volume processing in this cog will be paused for the duration of the "fade".
  If you wish to use triggers instead, then the syntax looks as follows:
  SendTrigger(-1, PlaySoundPosEx.cog number, 3, flex volume, flex duration, 0);



• SendMessageEx(PlaySoundPosEx.cog number, user4, 0, flex pitch, flex duration, 0);
  Using this will change the pitch over a period of time.
  pitch: The new pitch to be reached.
  duration: The time it takes to reach it.
  Again the last parameter isn't used.
  Do note that any special pitch processing in this cog (like the passing car effect) will be paused for the duration of the "fade".
  If you wish to use triggers instead, then the syntax looks as follows:
  SendTrigger(-1, PlaySoundPosEx.cog number, 4, flex pitch, flex duration, 0);



• SendMessageEx(PlaySoundPosEx.cog number, user5, 0, 0, flex fade_time, sound);
  Using this will change the sound the cog is playing.
  fade_time: The time it will take to fade out the previous sound.
  sound: The new sound that will be playing.
  If you wish to use triggers instead, then the syntax looks as follows:
  SendTrigger(-1, PlaySoundPosEx.cog number, 5, 0, flex fade_time, sound);