Guild of Writers

With the newest plugin version, we now have the ability to use our own sounds in our Ages. Our ability to manipulate those sounds is at this point rather limited. This is what we can do as of now:

* create an ambient loop that will play at equal volume everywhere in an Age
* create a looping sound that emanates from a particular point and can be heard up to a defined distance from the emitter
* start and stop sounds using logic triggers. (clickables, detector regions, python)

Things we will be able to do in the future, but cannot yet:

* confine sounds to a region using softvolumes

== Add your sound file to blender ==

In Blender, change one of your views to a "Audio Window". Click the selector to the right of the menus and select "OPEN NEW". Then browse to a sound file and open it. A waveform should show up in the window. The name at the top is the name you will give for the "file" in your alcscript. You can also add a sound by making a "Video Sequence Editor" window and using Add > Audio (RAM), and finding the sound.

If you press Alt-A in the Video Sequence Editor window, Blender will play the sound.

Blender may occasionally "forget" about your sound between save/reload cycles. If the sound is missing when you try to export, you will get an error. Simply re-open the sound to fix the problem.

[[Image:SoundTut.jpg|thumb|right|115px|Example Showing audio and alcscript (note: flags are outdated!)]]

== Creating an emitter ==

Place the cursor where you want your emitter object to be. Use [space] > Add > Empty to create a new empty. In the editing panel (F9), change its name to something useful. This will be the point from which your sound will emit, if you choose to make it a 3D sound. If it will not be a 3d sound, then you don't really need to place it anywhere specific.

Create an [[AlcScript]] with the name of your emitter. You may omit the "- is3dsound" if you want a constant sound, and the "- looping" if you want the sound to only play once and then stop. "- autostart" sets your sound to start automatically on link in, and it appears that uru will save the playing state of your sound between sessions.

 '''<Name of emitter object>''':
     type: soundemit
     sound:
         flags:
           - is3dsound
           - looping
           - autostart
         file: psnlMusicPlayer '''(name of the wav file you imported without the extension)'''
         volume: 1
         type: '''<SoundFX, Ambience, BackgroundMusic, GUISound, NPCVoices>'''
         channel: '''<right, left>'''
         maxfdist: 250 '''(farthest distance from the emitter the sound can be heard. Only affects 3d sounds)'''
         minfdist: 50 '''(inside this distance, the sound is full volume. Only affects 3d sounds)'''

If you plan on having multiple emitters read from the same sound file, you will need to use trigger regions to start and stop them, because only one of them can play at a time.

== Using SoundRegions and Sound Messages ==

You can use a sound region to start and stop a sound emitter. Entering and exiting the region will toggle the sound emitter. To add one, use the scripts window menu Scripts > Add > PyPRP > Add a (Generic) Logic Region to add a region. Then you can either set the text properties: 

 regiontype: soundregion
 soundemitter: '''<Name of sound emitter object>
'''
or use the following [[AlcScript]]:
               
 '''<Name of sound region>''':
     region:
         type: soundregion
         soundemitter: '''<Name of sound emitter object>'''

Note that when the sound region starts a sound emitter, it sets the volume to 1. This value will be an option in later versions. Also note that entering and exiting a sound region merely toggles the sound emitter, and the sound emitter is started at the first crossing of a region boundary. So if you start inside the region, exiting the region will start the sound emitter, and entering will stop it, whereas if you start outside the region, entering will start it, and exiting will stop it. Again, more flexibility will be added to the sound region quickscript in later versions. 

For those who feel like diving into [[AlcScript]] logic scripting, you can use sound messages in your responders for clickables and region triggers instead of using the quickscript regions. The format for a sound message:

 '''<some object>''':
     logic:
         actions:
           - type: responder
             name: SoundResp '''(name or tag for modifier ref)'''
             responder:
                states:
                 - cmds:
                    - type: soundmsg
                      params:
                         receivers:
                          - 0011:'''<Name of emitter object>'''
                         cmds:
                          - play '''(start the sound)'''
                          - stop '''(stop the sound)'''
                          - setvolume '''(set the volume)'''
                         volume: 1 '''(volume only set if setvolume cmd is used)'''
                      waiton: -1
                   nextstate: 0
                   waittocmd: 0
                curstate: 0
                flags:
                 - detect_trigger

== Export ==

Your sound should now be ready, export the Age and check it out. If you don't hear anything, make sure that the sound file (something.wav) is located in the sfx/streamingCache folder in your uru directory '''AND''' that something.ogg is located in the sfx directory. The "fdists" are in Blender units, and should be very large if you are using a 3D sound. Good luck! 

[[Category:Blender tutorial]]
[[Category:AlcScript]]