| Next revision | Previous revision |
| dragengine:modules:dragonscript:simpleconversation [2025/03/13 23:00] – created dragonlord | dragengine:modules:dragonscript:simpleconversation [2025/08/11 12:50] (current) – [snippet] dragonlord |
|---|
| ====== Simple Conversation ====== | ====== Simple Conversation ====== |
| |
| Simple conversations provide a quicker and easier way to create simple conversations compared to the [[conversation editor]]. In contrary to regular conversations simple conversations are created using XML files. Yet they are still regular conversations bug using an XML syntax which and a converter which creates regular conversations for you. It is important to note that simple conversations already require a regular conversation to be present. The reason is that simple conversation reuse various definitions present inside regular conversations like camera shots, gestures, look-at targets as well as pre-made topics for reuse. In the examples below it is expected such a regular conversation is present and contains the required camera shots, gestures and look-at targets. | <WRAP center 100%> |
| | <WRAP center box 1050px> |
| | {{ youtube>W6Pd6kT94Ro?1000x591 }} |
| | <WRAP centeralign>\\ |
| | Video explaining what simple conversation are, what they can be used for and how they are created. Shown using Epsylon game project which uses simple conversation a lot.</WRAP> |
| | </WRAP> |
| | </WRAP> |
| | |
| | Simple conversations provide a quicker and easier way to create simple conversations compared to the [[gamedev:deigde:editors:conversation|IGDE Conversation Editor]]. In contrary to regular conversations simple conversations are created using XML files. Yet they are still regular conversations but using an XML syntax and a converter which creates regular conversations for you. It is important to note that simple conversations already require a regular conversation to be present. The reason is that simple conversation reuse various definitions present inside regular conversations like camera shots, gestures, look-at targets as well as pre-made topics for reuse. In the examples below it is expected such a regular conversation is present and contains the required camera shots, gestures and look-at targets. |
| |
| Conversations in general compose of a series of actors speaking with camera angle changes in between. Furthermore actors do mouth animation, perform gestures, perform facial animation and looking at the currently speaking actor or other targets. For the majority of conversations the same type of camera shots are used with the same delays. This process can be sped up by generating actor speaking and camera changes according to common rules. Also speaking gestures or automatically looking at whatever actor is speaking is a common task that can be automated. All this is done by the simple conversation system to make conversations faster to build for which you do not need full control. | Conversations in general compose of a series of actors speaking with camera angle changes in between. Furthermore actors do mouth animation, perform gestures, perform facial animation and looking at the currently speaking actor or other targets. For the majority of conversations the same type of camera shots are used with the same delays. This process can be sped up by generating actor speaking and camera changes according to common rules. Also speaking gestures or automatically looking at whatever actor is speaking is a common task that can be automated. All this is done by the simple conversation system to make conversations faster to build for which you do not need full control. |
| </code> | </code> |
| |
| The text ''technical things'' has been now replaced with a conversation system tag. [[behavior_ctrrbBindings|ECBCTRRBindings]] allows to adds rules which allow to replace such text in conversations with dynamic content. Depending on what kind of information you need to add these tags can be complex with parameters and what not else. Trying to use speech animation to speak them does not make sense. To solve this problem ''t'' tags (or long ''tag'' with attribute ''anim'') exist. They wrap such tags and tell the simple conversation system what text they should use instead of them for conversation purpose. The example would then look like this: | The text ''technical things'' has been now replaced with a conversation system tag. [[behavior_ctrrbindings|ECBCTRRBindings]] allows to adds rules which allow to replace such text in conversations with dynamic content. Depending on what kind of information you need to add these tags can be complex with parameters and what not else. Trying to use speech animation to speak them does not make sense. To solve this problem ''t'' tags (or long ''tag'' with attribute ''anim'') exist. They wrap such tags and tell the simple conversation system what text they should use instead of them for conversation purpose. The example would then look like this: |
| |
| <code xml> | <code xml> |
| ==== Translations ==== | ==== Translations ==== |
| |
| With the simple conversation working one last thing to do sooner or later is translations to make the game available to people speaking a different language. Regular conversations require using [[language packs]]. This is the typical way translations are done. For large conversations this can be cumbersome to use. | With the simple conversation working one last thing to do sooner or later is translations to make the game available to people speaking a different language. Regular conversations require using language packs. This is the typical way translations are done. For large conversations this can be cumbersome to use. |
| |
| Simple conversation provide a nifty way to handle this. You can create a second simple conversation file which you load only if a specific language is used in your game. You load then first the original simple conversation and then the translated one. By calling SimpleConversation.importTranslation() you can then import the translated simple conversation and "patch" the original simple conversation with it. | Simple conversation provide a nifty way to handle this. You can create a second simple conversation file which you load only if a specific language is used in your game. You load then first the original simple conversation and then the translated one. By calling SimpleConversation.importTranslation() you can then import the translated simple conversation and "patch" the original simple conversation with it. |
| ====== File Format (*.desconvo) ====== | ====== File Format (*.desconvo) ====== |
| |
| The simple conversation file format is recognized by the LoadSimpleConversation script class. The file is an XML file with a simple structure to define a simple conversation using XML. | The simple conversation file format is recognized by the LoadSimpleConversation script class. The file is an XML file with a simple structure to define a simple conversation using XML. See [[https://lordofdragons.github.io/dragengine/artifacts/xmlschema/dragengine/latest/simpleConversation.xsd|XML Schema]] for use with editors like VSCode. |
| |
| <uml> | <uml> |
| * ''noCamera'': Do not change camera. | * ''noCamera'': Do not change camera. |
| * ''noCameraNoDelay'': Do not change camera and use 0 second delay for speak. | * ''noCameraNoDelay'': Do not change camera and use 0 second delay for speak. |
| | * ''sound'': Path of sound file to play. This is typically used to play voice audio but can be also used for uttering and mumbling if no voice audio is used. Optional. |
| </WRAP>|0..N|-| | </WRAP>|0..N|-| |
| |a|<WRAP>Short version of ''actor'' tag. Attributes: | |a|<WRAP>Short version of ''actor'' tag. Attributes: |
| * ''i'': Same as ''id'' attribute of ''actor'' tag. Optional. | * ''i'': Same as ''id'' attribute of ''actor'' tag. Optional. |
| * ''m'': Same as ''mode'' attribute of ''actor'' tag. Optional | * ''m'': Same as ''mode'' attribute of ''actor'' tag. Optional |
| | * ''s'': Same as ''sound'' attribute of ''actor'' tag. Optional |
| </WRAP>|0..N|-| | </WRAP>|0..N|-| |
| |gesture|<WRAP>Add gesture to play back. Replaces gestures defined in active actor definition. Attributes: | |gesture|<WRAP>Add gesture to play back. Replaces gestures defined in active actor definition. Attributes: |
| * ''group'': Run regular conversation topic from group ''group''. Otherwise runs simple conversation snippet. Optional. | * ''group'': Run regular conversation topic from group ''group''. Otherwise runs simple conversation snippet. Optional. |
| * ''random'': For use with simple conversation only. Select random number in the range from ''0'' to ''random-1''. Then runs snippet with this number appended to the snippet identifier. Hence if the text content is ''snippet identifier|v'' and the randomly chosen number is ''2'' then the snippet to run is ''snippet identifier|v2''. Optional. | * ''random'': For use with simple conversation only. Select random number in the range from ''0'' to ''random-1''. Then runs snippet with this number appended to the snippet identifier. Hence if the text content is ''snippet identifier|v'' and the randomly chosen number is ''2'' then the snippet to run is ''snippet identifier|v2''. Optional. |
| | * ''createSideLane'': Run snippet in a new side lane instead of the current lane. Allowed values: ''true'', ''false''. Optional. Default is ''false''. |
| | |
| | By default conversation snippet actions are run in place of this tag. The action after the snippet runs once the snippet finished. If the ''createSideLane'' attribute is used with a value of ''true'' the snippet actions are run in a new side lane and the action after the snippet runs next. Snippets in side lanes run in parallel to the main conversation lane. This allows to create complex conversations or cutscenes where mutliple concurrent action happen without needing to properly craft a sequence of actions. Side lanes are like co-routines just that they can not be awaited. Instead they end once their last action is finished. This makes it easy to create a side lane at any time in a conversation, no matter if from inside the main lane or another side lane. Furthermore side lanes have full access to the same conversation playback state as main lanes. This allows to synchronize events between them as you are used to. |
| </WRAP>|0..N|-| | </WRAP>|0..N|-| |
| |music|Switch music using name from content text.|0..N|empty string| | |music|Switch music using name from content text.|0..N|empty string| |
| </WRAP>|0..N|-| | </WRAP>|0..N|-| |
| |p|Short version of ''pause'' tag.|0..N|-| | |p|Short version of ''pause'' tag.|0..N|-| |
| | |time|Works similar to ''pause'' tag but instead of adding a relative delay the delay is the difference between the requested absolute time (since the start of the snippet) relative to the already accumulated times/delays. This allows to define actions to be run at absolute times which is useful for cutscenes.|0..N|-| |
| |endActorSpeak|End last actor speech line. Required to apply ''pause'' tag to the next tag instead of the speec line.|0..N|-| | |endActorSpeak|End last actor speech line. Required to apply ''pause'' tag to the next tag instead of the speec line.|0..N|-| |
| |music|Switch music using name from content text.|0..N|empty string| | |music|Switch music using name from content text.|0..N|empty string| |
