hpl3:game:voicehandler
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
hpl3:game:voicehandler [2012/07/11 10:17] nebej [Sound] |
hpl3:game:voicehandler [2015/09/17 10:53] (current) ian.thomas [File Format] |
||
|---|---|---|---|
| Line 9: | Line 9: | ||
| ====== Setup ====== | ====== Setup ====== | ||
| - | Before calling a subject the source of the sound should be set up. This is done with SetVoiceSource() in cVoiceHandler, or better the helper function Voice_SetSource(). This sets up the entity (which can be something moving) which will emit the voice coming from the specified character. It will also set up the distance that the voice can be heard. Do this in OnEnter in the map script file. | + | Before calling a subject the source of the sound should be set up. This is best done inside the VoiceHandler editor itself, but can also be done using the helper function Voice_SetSource(). This sets up the entity (which can be something moving) which will emit the voice coming from the specified character. It will also set up the distance that the voice can be heard. If using the function, it's best to do this in ''OnEnter'' in the map script file. |
| ====== Properties ====== | ====== Properties ====== | ||
| Line 21: | Line 21: | ||
| Name of the character | Name of the character | ||
| - | **AutoGenVoice**\\ | + | **EntryType**\\ |
| - | If the voices should be autogenerated (jrpg style). | + | The type of the sounds (and extrasounds) that are played for this character. Is either World, WorldClean or GUI. |
| - | **AutoGenVoiceFile**\\ | + | **Volume** \\ |
| - | The sample that should be played when the character speaks. | + | Volume of the sound files. Gets multiplied with other volume properties. |
| + | |||
| + | **ReverbVolume** \\ | ||
| + | The amount of reverb used for the sounds. Gets multiplied with other ReverbVolume properties. | ||
| - | **AutoGenVoiceSoundFreq**\\ | ||
| - | Determines the frequences (times per second) that AutoGenVoiceFile is played. | ||
| ===== Scene ===== | ===== Scene ===== | ||
| Line 42: | Line 43: | ||
| This is the priority for a voice to into focus, meaning that is subtittles are shown and any other voice playing gets its volume lowered. To beat a currently playing voice, FocusPrio must be higher.\\ | This is the priority for a voice to into focus, meaning that is subtittles are shown and any other voice playing gets its volume lowered. To beat a currently playing voice, FocusPrio must be higher.\\ | ||
| When a subject starts playing it is checked if another sound is playing and FocusPrio determines if the new subject gets into focus. Also when a subject stops playing a certain amount of time is waited (default 2 seconds) and then there is a check to see if there is any playing voice that should come into focus. If there are many playing, FocusPrio determines which one. The reason for waiting a litte while is in case there is a conversiation in one scene containing many subjects, and if so it would not sound good if the focus was constantly switched (ie unrelated subtitles popping up for a second). | When a subject starts playing it is checked if another sound is playing and FocusPrio determines if the new subject gets into focus. Also when a subject stops playing a certain amount of time is waited (default 2 seconds) and then there is a check to see if there is any playing voice that should come into focus. If there are many playing, FocusPrio determines which one. The reason for waiting a litte while is in case there is a conversiation in one scene containing many subjects, and if so it would not sound good if the focus was constantly switched (ie unrelated subtitles popping up for a second). | ||
| + | |||
| + | |||
| + | **Volume** \\ | ||
| + | Volume of the sound and effect files. Gets multiplied with other volume properties. | ||
| + | |||
| + | **ReverbVolume** \\ | ||
| + | The amount of reverb used for the sounds. Gets multiplied with other ReverbVolume properties. | ||
| + | |||
| ===== Effect ===== | ===== Effect ===== | ||
| This defines certain effect that should be played on the voice, be that echo, noise or whatnot. \\ | This defines certain effect that should be played on the voice, be that echo, noise or whatnot. \\ | ||
| Line 63: | Line 72: | ||
| ===== Subject ===== | ===== Subject ===== | ||
| A subject is what you call when you want to voice to be played. A subject is the basic data structure of the voice data and it contains sound files, subtitle texts and various options.\\ | A subject is what you call when you want to voice to be played. A subject is the basic data structure of the voice data and it contains sound files, subtitle texts and various options.\\ | ||
| - | A subject contain one or more **Lines** (more on these below). Depending on current state and settings, one (or none) of these lines will be played when a certain subject is called. | + | A subject contain one or more **Lines** (more on these below). Normally all of these lines will be played in order, but if UseSingleRandomLine is true, only one will. |
| **ID**\\ | **ID**\\ | ||
| Line 71: | Line 80: | ||
| Name of the subject | Name of the subject | ||
| - | **Prio**\\ | + | **UseSingleRandomLine**\\ |
| - | The priority of the subject. This will depend if a subject voice will be blocked when another voice in the same scene is already playing. If prio is higher than the one currently played, the current is stopped and the new one plays. | + | If only a single random line should be used. If more than 2 lines, it is made sure that the a line is never picked two times in a row. |
| - | **BlockedAction**\\ | ||
| - | This is what happens in case a line is already playing, is part of the same scene and the new line has same or lower Prio has the current. Possible values are:\\ | ||
| - | Enqueue: The line is queued and played as soon as the currently played (and any other already queued lines) has finished playing.\\ | ||
| - | Skip: The line is not played. If this happens it counts as a playback and thus affects MaxPlaybacks (see below).\\ | ||
| - | StandBy. The line is not played, but neither does it count as a playback. It is as if a Voice Subject was never called to be played.\\ | ||
| - | |||
| - | |||
| - | **RandomizeOrder**\\ | ||
| - | If the Lines should be chosen randomly. If false, the line declared first plays first. | ||
| - | |||
| - | **Trigger**\\ | ||
| - | This is the trigger that the subject responds to. This can either be a standard trigger (as outlined [[hpl3:game:eventdb#standard_triggers|here]]) or it can be a custom trigger. A custom trigger is either created through script or with the ResponseTrigger property (see Line properties below). | ||
| - | |||
| - | **Criteria**\\ | ||
| - | This is the criteria that needs to be correct for the subject to played. Remember that if several Subjects (triggered by the same Trigger) all have matching criteria, then the Subject with the most Critera is the one that is played. This makes it possible to have default trigger responses by having no Criteria at all, and these will only be used when no other subject match their criteria.\\ | ||
| - | More info on syntax and such [[hpl3:game:eventdb#criteria|here]] | ||
| - | |||
| - | **Actions**\\ | ||
| - | Actions are used to set change the facts in the working memory of the event database. This memory is then checked with evaluating Criteria and therefore the contents of the actions help decide what Subjects are picked. The actions are out at the moment the voice starts playing (meaning when the subject is picked and OutputDelay has passed). Note that should the voice not play the actions are still carried out!\\ | ||
| - | More info on syntax and such [[hpl3:game:eventdb#actions|here]] | ||
| - | |||
| - | **OutputDelay**\\ | ||
| - | This is the delay between an event being picked by a trigger and the voice being played and actions performed. | ||
| - | **CharacterId**\\ | ||
| - | Id of character connected to the subject. | ||
| - | |||
| **SceneId**\\ | **SceneId**\\ | ||
| Id of scene connected to the subject. | Id of scene connected to the subject. | ||
| Line 113: | Line 96: | ||
| Internal Id | Internal Id | ||
| - | **The name of the line**\\ | + | **CharacterId**\\ |
| - | Name of the line | + | Id of character connected to the line. |
| - | **MaxPlaybacks**\\ | ||
| - | Max number of times this line can be played. If 0, then the number of times is unlimited. | ||
| - | |||
| - | **ResponseTrigger**\\ | ||
| - | When the line has finished playing, this custom trigger is sent back into the event system (which the voice handler uses).\\ | ||
| - | This makes a for a very nice way of linking subjects in a dynamic way. An example:\\ | ||
| - | When "Subject A" has finished playing it can send "RespondToA" as a trigger. Both subjects B and C than then have "RespondToA" as their trigger and the subject with the mpst fitting criteria will be picked (if any). For instance subject B might have the Criteria "Bananas>2" as a Criteria, while C's Criteria is empty (""). This means that after Subject A has been playing AND the fact Bananas is over 2, then Subject B will start playing. If the fact Bananas is not above 2, then Subject C will play. Note that when "Bananas>2" is true, both subject match, but since the one with the most matching criteria (1 vs 0) is picked, Subject B is wins and is played.\\ | ||
| ===== Sound ===== | ===== Sound ===== | ||
| - | |||
| This is the lowest level data structure for a subject. It contains properties for the voice, (opitonal) effect sound, and subtitle. | This is the lowest level data structure for a subject. It contains properties for the voice, (opitonal) effect sound, and subtitle. | ||
| + | The file name for the voice sound is generated based on the names of the higher level structures. The syntax is:\\ | ||
| + | ''[map]'' /''[scene]'' _''[subject]'' _''[line index in 3 digits]'' _''[character]'' _''[sound index in 3 digits]'' | ||
| - | The file name for the voice sound is generated based on the names of the higher level strucutres. The syntax is:\\ | + | Here is an example:\\ |
| - | //[scene]_// //[character]// _//[subject]// _//[line]// _//[sound index in 3 digits]// | + | //01_01_castle/SwordFight_ShowMercy_002_Arthur_001// \\ |
| + | This would be a voice sound being said in the map //"01_01_castle"// (no file extension!), in the Scene //"SwordFight"//. The subject is //"ShowMercy"//, it is the second line, it is being said by //"Arthur"// and it is his first sound for that line. | ||
| + | The lang file entry for the text is also generated, with this syntax:\\ | ||
| + | Category: Voices_''[map]'' \\ | ||
| + | Entry: ''[scene]'' _''[subject]'' _''[line index in 3 digits]'' _''[character]'' _''[sound index in 3 digits]'' (apart from no folder name, it is exactly the same as for the voice file!) | ||
| - | Example, the firs sound of a subject can be:\\ | + | Finally, if "AutogenerateLangFiles" in "Main" is set to true in the user settings, then the lang file entries will be autogenerated with the text specified in the sound's properties. |
| - | Arthur_Camelot_AngryAtMerlin_Insults_001 | + | |
| + | **Text** \\ | ||
| + | The text for the voices, not really saved by added to a lang file (if AutogenerateLangFiles is true i settings, see above) | ||
| - | The lang file entry for the text is also generated, with this syntax:\\ | + | **HasVoice** \\ |
| - | Category: "Voices"\\ | + | If the sound has a voice at all. This is only meaningful false if there is an Effect filed specificed. |
| - | Entry: //[scene]_// //[character]// _//[subject]// _//[line]// _//[sound index in 3 digits]// (exactly the same as for the voice file!) | + | |
| + | **Volume** \\ | ||
| + | Volume of the sound and effect file. Gets multiplied with other volume properties. | ||
| - | Finally, if "AutogenerateLangFiles" in "Main" is set to true in the user settings, then the lang file entries will be autogenerated with the text specified in the sound's properties. | + | **ReverbVolume** \\ |
| + | The amount of reverb used for the sounds. Gets multiplied with other ReverbVolume properties. | ||
| + | **VoiceOffset** \\ | ||
| + | Number of seconds before voice starts to play. | ||
| - | **Text** \\ | + | **TextOffset** \\ |
| - | The text for the voices, not really saved by added to a lang file (if AutogenerateLangFiles is true i settings, see above) | + | Number of seconds before the subtitles show up. |
| + | **ExtraEffectOffset** \\ | ||
| + | Number of seconds before the effect file starts to play. | ||
| - | **HasVoice** \\ | + | **ExtraEffectFile** \\ |
| - | If the sound has a voice at all. This is only meaningful false if there is an Effect filed specificed. | + | File path to an extra sound file that is played along with the voice. |
| + | **EndsAfterExtraEffect** \\ | ||
| + | If the sound should end when the extra sound file is done playing (and not the voice). | ||
| - | **Volume** \\ | + | **EndPadding** \\ |
| - | Volume of the sound and effect file. | + | Number of seconds of padding in the length of voice file. If this is over 0, then that means the next sound will start that many seconds earlier (while the current sound is still playing). |
| + | ====== Use with AI ====== | ||
| - | **VoiceOffset** \\ | + | When using voice with AI it is best always through the [[http://wiki.frictionalgames.com/hpl3/game/scripting/entity_components#barkmachine|BarkMachine component]] using ''BarkMachine_PlayVoice(...)''. That way it is sure to be played in the right place even if there are multiple agents that use voices from the same character. When using the BarkMachine, the source set up directly before the line is played. |
| - | Number of seconds before voice starts to play. | + | |
| + | The voices for all agents should also have "AgentBark" as scene, this way it makes it possible to see to that there is only one dialog line from an Agent at a time. Should there be some special line that does not apply to this, then by all means do not do this. | ||
| - | **TextOffset** \\ | + | If you want to have longer specific dialog on agents, then the best way to set that up is to have the piece of a dialog as a single subject with two unique Characters attached to the lines. Then set up these characters as voice sources specifically in the script and start the dialog using ''Voice_Play''. The scene must be AgentBark as described above and the prio must be less than what the default barks use. What then happens is that the dialog will continue until some AI event triggers default sounds to be played and the specific dialog will automatically be stopped. |
| - | Number of seconds before the subtitles show up. | + | |
| + | ====== Best Practices ====== | ||
| - | **EffectOffset** \\ | + | Here are a few practices that should be used when adding voices in the game: |
| - | Number of seconds before the effect file starts to play. | + | |
| + | **- Sound effects are between *:s **\\ | ||
| + | When adding sound effects, like *gasp*, *pants*, *cries*, etc then always put them between *:s. This way we can easily remove them for people that do not want the hearing impaired option. | ||
| - | **EffectFile** \\ | + | **- Pure sound effects is a separate line**\\ |
| - | File path to an effect file that is played along with the voice. | + | When implementing a subject that contains parts where there is only (non character related) sound effects playing you shall add this as Line on its own. The character containing it shall be called "_SoundEffect". If the sound effects need to come from special position in the world, then do add a "_" followed by a prefix to the name, for instance "_SoundEffect_Trees" (this should be pretty rare though and these sort of effects are better added through callback functions, but there might be some rare instance that require it). |
| + | Important note is that this only meant for sound effects that are not specific to a character voice. Examples:\\ | ||
| + | Do **NOT** use it for: *cough*, *clears throat*, *spits*, etc.\\ | ||
| + | **DO** use it for: *steps are heard coming down the stairs*, *large metal door opens*, *Anne carefully steps on the creaking floor*, etc.\\ | ||
| - | **EndsAfterEffects** \\ | + | **- All protagonist dialog come from the character "Player"**\\ |
| - | If the sound should end when the effect file is done playing. | + | Make sure that all the dialog that the player is supposed to say outloud comes from the character "Player", as this allow the game to not play breathing, etc when a voice over from the player character is playing. |
| + | **- Use proper prefix for subjects**\\ | ||
| + | Have prefixes on the subjects that give some hint where they belong and make it easier to sort. For instance a blackbox subject should start with "Blackbox_", eg "Blackbox_FriedRobot". Another examples would be a situation that many subjects belong. Say Simon meets a farmer and there is a lot of subjects related to this, then use the prefix "SimonMeetsFarmer_", eg "SimonMeetsFarmer_Intro". | ||
| - | **EndPadding** \\ | + | This is also true for special characters, for instance when a certain character speak in a recording. So for instnace a character that appears in a SOMA blackbox message (that does not come from a world position), should have "Blackbox_" as prefix, eg "Blackbox_Amy". |
| - | Number of seconds of padding in the length of voice file. If this is over 0, then that means the next sound will start that many seconds earlier (while the current sound is still playing). | + | |
| + | **- Write temp dialog in square brackets**\\ | ||
| + | If you add some writing that is only temporary then add this between square brackets. Also briefly summarize what is supposed to be going on, or what the is supposed to be expressed. Examples:\\ | ||
| + | [Player gets his finger caught in bear trap]\\ | ||
| + | [Hint that the screw needs to be bigger]\\ | ||
| + | |||
| + | If you need to have further info that feels wrong to show in-game then you can add extra info under the line direction, but make sure to start the line with INFO:, so it is not confused with proper line direction. Examples:\\ | ||
| + | INFO: The player tries to hold the pain inside.\\ | ||
| + | INFO: The solution is to use the file on the screw, can have slight hint for that.\\ | ||
| ====== File Format ====== | ====== File Format ====== | ||
| + | |||
| + | (You shouldn't need this - everything can be edited using the VoiceHandler exe!) | ||
| <code xml> | <code xml> | ||
hpl3/game/voicehandler.1342001874.txt.gz · Last modified: 2012/07/11 10:17 by nebej
