Frictional Game Wiki

<h1>Dialog Handler</h1> <div class="level1"> </div> <h2>Overview</h2> <div class="level2"> <p> The dialog handler is a used to create dialog that support basic branching behavior. If you want to do straight forward dialogs that have no branching at all, you might as well just call the Voice Handler directly. But if there are some branching, even simple like breaking the dialog if the player stop looking at a character, then the Dialog Handler is what you want. </p> </div> <h2>Basic functioning</h2> <div class="level2"> <p> The dialog is setup just before it is a about to get played, so there is not special init (other than what you do for the <a href="/doku.php?id=hpl3:game:voicehandler" class="wikilink1" title="hpl3:game:voicehandler">voice handler</a>). You begin by calling Dialog_Begin() which makes the initial preparations and allows you to call the other functions. After that it is time to add a branch using Dialog_AddBranch. You can then use Dialog_AddSubject to add voice subjects to that branch. Once you add a new branch, then those subjects will belong to the newly added branch. When all branches and subjects are added, call Dialog_End to run the dialog. Dialog_End will also check which characters are used in this dialog, and by using Dialog_CharacterIsActive you can check which are currently in the middle of a dialog. </p> <p> Example: </p> <pre class="code c++">Dialog_Begin<span class="br0">(</span><span class="br0">)</span><span class="sy0">;</span> Dialog_AddBranch<span class="br0">(</span>"A"<span class="br0">)</span><span class="sy0">;</span> Dialog_AddSubject<span class="br0">(</span>"AdamEnter1"<span class="br0">)</span><span class="sy0">;</span> Dialog_AddSubject<span class="br0">(</span>"AdamEnter2"<span class="br0">)</span><span class="sy0">;</span> Dialog_AddBranch<span class="br0">(</span>"B"<span class="br0">)</span><span class="sy0">;</span> Dialog_AddSubject<span class="br0">(</span>"AdamLeave"<span class="br0">)</span><span class="sy0">;</span> Dialog_End<span class="br0">(</span><span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> This will create two branches, "A" and "B". The first contains "AdamEnter1" and "AdamEnter2", and the other "AdamnLeave". When Dialog_End() is called, "A" will begin playing, starting with "AdamEnter1" as it was the first added. If you want to start with some other branch, just supply its name as a parameter for Dialog_End(), like this:<br/> </p> <pre class="code c++">Dialog_End<span class="br0">(</span>"B"<span class="br0">)</span> </pre><p> </p> <p> <span class='np_break'> </span> This would start with branch "B" instead. </p> <p> Also of interest is that you can make one branch go directly to another by supplying the next dialog as a second parameter, like this:<br/> </p> <pre class="code c++">Dialog_AddBranch<span class="br0">(</span>"A"<span class="sy0">,</span> "B"<span class="br0">)</span> </pre><p> </p> <p> <span class='np_break'> </span> Now when "A" is done, "B" is started. This might seem a bit pointless at first, but is really useful when you add branching events (more on that soon). </p> </div> <h2>Branch Events</h2> <div class="level2"> <p> These events are needed in order to get the branching behaviors you are after. Events are added after having added subject and will belong that subject. They can in two types <code>LineEvents</code> and <code>EndEvent</code>. The first type is checked after each voice line has completed playing. The second is checked when the entire subject is over. </p> <p> The existing functions carry this syntax:<br/> <code>Dialog_Add[type]_[condition]</code> <em>(more on conditions in a few lines)</em><br/> Some examples for functions:<br/> </p> <pre class="code c++"><span class="kw4">void</span> Dialog_AddLineEvent_Callback<span class="br0">(</span><span class="kw4">const</span> tString<span class="sy0">&</span>in asCallbackFunc<span class="sy0">,</span> <span class="kw4">const</span> tString<span class="sy0">&</span>in asNewBranch<span class="br0">)</span> <span class="kw4">void</span> Dialog_AddEndEvent_PlayerNotLookingOrOutOfRange<span class="br0">(</span><span class="kw4">const</span> tString<span class="sy0">&</span>in asNewBranch<span class="br0">)</span> </pre><p> </p> <p> <span class='np_break'> </span> Note that if asNewBranch is _ckgedit_QUOT<u>ckgedit>, then the dialog does not jump to a new branch but just stops. The different conditions available are:<br/> <b>OutOfRange</b><br/> This is true if the player is out of range, as set in Voice_SetSource(..) with the PlayerListeningRange parameter. This applies to all characters in the dialog with a proper source entity and is only true if all of them are out of range. <b>PlayerNotLooking</b><br/> This is true when the player is no longer looking at the source entity set with Voice_SetSource(..). This applies to all characters in the dialog with a proper source entity and is only true if all of them are not looked at. <b>Variables</b><br/> The functions for this these are: SetVar, IncVar, VarIsSet, VarEquals, VarGreater and VarLesser.<br/> This is a very simple variable system where each variables carries an integer value. It is very nice to use to check if some information has been mentioned, by simply doing SetVar("Info") and then deciding on branch depending on if some info is set or not.<br/> Currently variables only support the type <code>EndEvent</code>.<br/> Note that setting variables never results in a branching, so make sure to declare these before any branching event. <b>Callback</b><br/> This is a custom callback that can be used to let what ever code determine if there should be a branch or not. The syntax is:<br/> <code>bool MyFunc(const tString&in asBranch, const tString&in asBranchSubject, int alLineIndex, const tString&in asNewBranch)</code><br/> asNewBranch is very handy when you do not want too many callbacks function to provide similar functionality. For example if the branch should be determined by the name of a cat, then you can do a function like this: <code c++>bool MyFunc(const tString&in asBranch, const tString&in asBranchSubject, int alLineIndex, const tString&in asNewBranch) { return asNewBranch == msSomeSavedVariableOfCatName; } </code> <span class='np_break'> </span> The declared events can then look like this: <code c++> Dialog_AddLineEvent_Callback(</u>GESHI_QUOT<u>MyFunc</u>GESHI_QUOT<u>, </u>GESHI_QUOT<u>Snoopy</u>GESHI_QUOT<u>); Dialog_AddLineEvent_Callback(</u>GESHI_QUOT<u>MyFunc</u>GESHI_QUOT<u>, </u>GESHI_QUOT<u>Shaggy</u>GESHI_QUOT<u>); </code> <span class='np_break'> </span> Now for some full test source. Lets say that we have a dialog that should stop playing whenever the player stops looking at the character, then we do like this: <code c++> Dialog_Begin(); Dialog_AddBranch(</u>GESHI_QUOT<u>A</u>GESHI_QUOT<u>); Dialog_AddSubject(</u>GESHI_QUOT<u>AdamEnter1-2</u>GESHI_QUOT<u>); Dialog_AddEndEvent_PlayerNotLooking(</u>GESHI_QUOT<u>B</u>GESHI_QUOT<u>); Dialog_AddBranch(</u>GESHI_QUOT<u>B</u>GESHI_QUOT<u>); Dialog_AddSubject(</u>GESHI_QUOT<u>AdamLeave</u>GESHI_QUOT<u>); Dialog_End(); </code> <span class='np_break'> </span> ===== Response selection ===== The dialog system allow the player to choose different option that will determine how the outcome of a dialog. After a subject has finished playing the DialogHandler will send a message to put in the game in "Response Mode" (more information on this at the end of this section) and the player will have to make a choice before the dialog continues. Each of the choices are called <code>ResponseOptions</code> and it is possible to set up conditions for if they should be present nor not, as well as declare events that happen if the ResponseOption is chosen. ResponseOptions are added after having added a subject and uses the function Dialog_AddResponseOption(..). As noted above, <code>BranchEvents</code> can also be added after a subject, and if there are both <code>ResponseOptions</code> and <code>BranchEvents</code> after a subject, the BranchEvents are checked first and then the ResponseOptions are handled. So for instance: <code c++> Dialog_AddBranchAndSubject(</u>GESHI_QUOT<u>A</u>GESHI_QUOT<u>); Dialog_Dialog_AddResponseOption(</u>GESHI_QUOT<u>AdamEnter1-2</u>GESHI>_); </p> <p> </code> <span class='np_break'> </span> </p> </div>