Difference between revisions of "Dialogue Editor"

Revision as of 08:07, 16 June 2018

TODO: Figure out how to best cover all the missing send_level_message and send_character_message commands.

This is the technical documentation for the dialogue editor. It's used to create scenes with different camera angles, text and poses. It is commonly used to give context and progress the story in a level.

Before reading this article it's recommended that you read the Dialogue article to get a basic understanding of how dialogues work.

General Dialogue Functions

Set Dialogue Name

Command: #name "$"

Example: #name "chat_with_villager"

Sets the name of the current dialogue to whatever is written in $. This can be used by some other hotspots to start the dialogue.

Set Number of Participants

Command: #participants $

Example: #participants 3

Sets the number of participants in the dialogue to the number written in $.

Dialogue

Command: say # "n" "m"

Example: say 1 "Turner" "Hello, I am participant 1 in the dialogue and my name is Turner."

Makes participant # say m while the name tag shows n.

Waiting

Command: [wait $]

Example: say 1 "Turner" "Hmm... [wait 0.5]I should eat some carrots!"

Put somewhere in the middle of a say command to pause the text printing for $ seconds.

Wait For Click

Command: [wait_for_click]

Example: say 1 "Turner" "But why!? [wait_for_click]Why did you burn all the lettuce!?"

Put somewhere in the middle of a say command to pause the text printing until the player left clicks.

Name Tag Color

Command: set_dialogue_color # r g b

Example: set_dialogue_color 2 0.8 0 0.8

When participant # says something, their name tag will have the color specified by the float values in r, g, b (red, green, blue).

Voice

Command: set_dialogue_voice # i

Example: set_dialogue_voice 2 8

Sets the voice of participant # to i.

In the menu bar of the dialogue editor, go to Edit → Preview Voice and click and drag through the slider to hear previews of all the different voices.

Camera Position

Command: set_cam tx ty tz rx ry rz

Example: set_cam 5.0 3.1 2.5 0.0 0.0 0.0

Sets the location of the camera for the next say command to tx, ty, tz (translation x, y, z), and sets the rotation to rx, ry, rz (rotation x, y, z).

You don't need to set this manually in the script because this line will be generated automatically when you move the camera object that is located on the dialogue hotspot by default when editing a dialogue. Keep in mind that when you do this you need to first select the say command in the script that you want to change the camera angle for, as the set_cam line will be put before that line.

However, in some cases it can be very useful to be able to copy a set_cam line from one place to another and things like that.

Character Position

Command: set_character_pos # x y z r

Example: set_character_pos 1 3.0 0.0 5.0 30

Sets the location of participant # to x, y, z, and rotates them around the vertical axis r degrees.

Just like with camera positions you don't need to manually set character positions in the script since the appropriate line of code will be automatically generated when you move one of the character position boxes that can be found by default on each participant's spawn box. As with camera positions, you need to make sure to select the say line that you want to edit before making any changes.

Copying and pasting set_character_pos lines can be useful to reuse positions in cutscenes without having to set them up again.

Pose

Command: send_character_message # "set_animation \"$\""

Example: send_character_message 1 "set_animation \"Data/Animations/r_dialogue_shade.anm\""

Makes participant # play the animation at $. Note that we're using \" to "escape" the " characters.

You don't have to write this line manually because it can be generated for you if you do the following:

Click on the say line in the dialogue that you want the animation to play for
Select the dialogue character position box in the 3D view for the character you want to play an animation
In the dialogue editor's menu bar, press File → Load Pose and load the animation you want

All animations can be found in the ../Overgrowth/Data/Animations/ folder.

Eye, Head & Torso Movement

Command: send_character_message # "$ x y z i"

Example: send_character_message 2 "set_head_target 5.0 3.2 1.1 0.8"

Makes participant # turn their $ towards location x, y, z, with the influence i. If i is 1, it will face as much towards x, y, z as possible, and if it's 0 the command has no effect.

$ Can be set to set_head_target or set_torso_target. set_eye_dir used to work, but currently dosn't.

This command doesn't need to be written manually, because it will be automatically set for the currently selected say line when you move one of the eye, head or torso targets. Scale the targets to change the influence.

Depth of Field

Command: send_level_message "set_camera_dof cs cd cg fs fd fg"

Example: send_level_message "set_camera_dof 0.3 5.0 10.0 0.3 20.0 10.0"

NOTE: The player character needs to be connected to the dialogue for it to work.

cs = Close blur strength
cd = Anything closer than this value will be blurred
cg = How gradual the transition for close dof should be, 0 = infinite blur
fs = Far blur strength
fd = Anything further than this value will be blurred
fg = How gradual the transition for far dof should be, 0 = infinite blur

The depth of field is split into two parts with three parts in each, the close blur and the far blur. First in each part is how strong the blur should be (xs), then at what distance it should end/start (xd), and then how long the transition from/to the blur should be (cg).

Fade to Black

Command: fade_to_black $

Example: fade_to_black 1

$ can be set to 1 to make the view fade to black on the next say command. If you set it to 0 afterwards, you get some visual bugs in the dialogue.

@@ Line 1: / Line 1: @@
-'''TODO: Need to verify this is all accurate, up to date, and complete. Also needs to carefully describe what lines you need to have selected in the editor for it to work properly (animations, object and camera positioning, etc, are very sensitive to which line is selected)'''
+'''TODO: Figure out how to best cover all the missing send_level_message and send_character_message commands.'''
-The dialogue editor is used to create scenes with different camera angles, text and poses. It is commonly used to give context and progress the story in a level.
+This is the technical documentation for the dialogue editor. It's used to create scenes with different camera angles, text and poses. It is commonly used to give context and progress the story in a level.
-== Getting Started ==
+Before reading this article it's recommended that you read the [[Dialogue]] article to get a basic understanding of how dialogues work.
-=== Write the dialogue ===
+== General Dialogue Functions ==
-Create a text file in your mods Dialogues folder (../Overgrowth/Data/Dialogues) and write the dialogue in it like this.
- #name "Mirage"
+=== Set Dialogue Name ===
- #participants 1
+Command: <code>#name "$"</code>
- say 1 "Thorn" "You there!"
- say 1 "Thorn" "Do you have any..[wait 0.4] water?"
-* The '''#name "Mirage"''' is the name of the scene. This is given to a dialogue hotspot on so it knows which dialogue to activate.
+Example: <code>#name "chat_with_villager"</code>
-* The '''#participants 1''' is how many characters there are in the scene. The numbered boxes above the dialogue object are connected to spawn points to decide which character is which in this scene.
-* '''say''' at the beginning of a line is used to make someone say something.
-* The '''1''' is the ID of the participant that should say the dialogue, this decides who moves their mouth when the dialogue appears.
-* '''"Thorn"''' is which name should appear for the dialogue
-* The text within the quotes at the end of the line is the dialogue itself.
-* The '''[wait 0.4]''' will make the dialogue text pause for 0.4 seconds before continuing to display the next text.
-Save and close the file.
+Sets the name of the current dialogue to whatever is written in <code>$</code>. This can be used by some other hotspots to start the dialogue.
-=== Set up the scene ===
+=== Set Number of Participants ===
-Open up your level in the game, go to the '''Dialogue''' tab in the ribbon and click '''Load Dialogue'''. Select the dialogue file you created and click in your level to spawn it there.
+Command: <code>#participants $</code>
-There is a small box above the dialogue object that you just created. Select this object and alt-click on a character to tell the game that the participant with ID 1 is that character.
+Example: <code>#participants 3</code>
-Select the box and press '''Edit Selected''', bringing up the text of the dialogue on the screen. Use the arrow up and down keys to select what line in the scene you want to edit. Now press '''Toggle Recording''', which creates a few more useful objects in our scene:
+Sets the number of participants in the dialogue to the number written in <code>$</code>.
-* Camera (with accompanying preview window)
+=== Dialogue ===
-* Torso control
+Command: <code>say # "n" "m"</code>
-* Head control
-* Eye control
-Move the camera to choose where the camera will be when the dialogue reaches the selected line, scale it to zoom in or out. Move the torso, head and eye controls to choose where the character's torso, head and eye should be pointing at that point. You need to scale up the torso and head controls for them to have any effect.
+Example: <code>say 1 "Turner" "Hello, I am participant 1 in the dialogue and my name is Turner."</code>
-Press '''Load Pose''' and find the files with names that start with '''r_dialogue''', find one that you think might fit and load it to make the character take that pose when the scene loads.
+Makes participant <code>#</code> say <code>m</code> while the name tag shows <code>n</code>.
-Press '''Preview Dialogue''' to test the scene. When you're happy, click '''Toggle Recording''' again to turn it off and press '''Save Dialogue''' to save your changes to the scene.
+=== Waiting ===
+Command: <code>[wait $]</code>
-=== Trigger the scene ===
+Example: <code>say 1 "Turner" "Hmm... [wait 0.5]I should eat some carrots!"</code>
-Now we have the scene set up, but we don't have anything that triggers it yet. We can use a dialogue hotspot to make that happen. So go to the '''Home''' tab and press '''Load Item''', go to the '''Hotspots''' tab, click the '''Start Dialogue''' hotspot and click on the ground in your level. This should spawn a wireframe cube with a green sign icon in.
-The dialogue will trigger when the player enters this hotspot, so place it where it will trigger when you want it to. Just make sure the player spawn is not inside of the hotspot, as that won't work when the level is restarted.
+Put somewhere in the middle of a say command to pause the text printing for <code>$</code> seconds.
-Press '''U''' with the hotspot selected and change the '''Dialogue''' property to be the same as the '''#name''' setting in the dialogue you want to trigger. If you've followed this example, that would be '''Mirage'''. If you don't want the dialogue to automatically trigger when you enter the hotspot, uncheck the "Automatic" checkbox.
+=== Wait For Click ===
+Command: <code>[wait_for_click]</code>
-Now save your level, start playing, enter the hotspot, and the dialogue should trigger!
+Example: <code>say 1 "Turner" "But why!? [wait_for_click]Why did you burn all the lettuce!?"</code>
+Put somewhere in the middle of a say command to pause the text printing until the player left clicks.
+=== Name Tag Color ===
+Command: <code>set_dialogue_color # r g b</code>
+Example: <code>set_dialogue_color 2 0.8 0 0.8</code>
+When participant <code>#</code> says something, their name tag will have the color specified by the float values in <code>r, g, b</code> (red, green, blue).
+=== Voice ===
+Command: <code>set_dialogue_voice # i</code>
+Example: <code>set_dialogue_voice 2 8</code>
+Sets the voice of participant <code>#</code> to <code>i</code>.
+In the menu bar of the dialogue editor, go to ''Edit → Preview Voice'' and click and drag through the slider to hear previews of all the different voices.
+=== Camera Position ===
+Command: <code>set_cam tx ty tz rx ry rz</code>
+Example: <code>set_cam 5.0 3.1 2.5 0.0 0.0 0.0</code>
+Sets the location of the camera for the next <code>say</code> command to <code>tx, ty, tz</code> (translation x, y, z), and sets the rotation to <code>rx, ry, rz</code> (rotation x, y, z).
+You don't need to set this manually in the script because this line will be generated automatically when you move the camera object that is located on the dialogue hotspot by default when editing a dialogue. Keep in mind that when you do this you need to first select the <code>say</code> command in the script that you want to change the camera angle for, as the <code>set_cam</code> line will be put before that line.
+However, in some cases it can be very useful to be able to copy a <code>set_cam</code> line from one place to another and things like that.
+=== Character Position ===
+Command: <code>set_character_pos # x y z r</code>
+Example: <code>set_character_pos 1 3.0 0.0 5.0 30</code>
+Sets the location of participant <code>#</code> to <code>x, y, z</code>, and rotates them around the vertical axis <code>r</code> degrees.
+Just like with [[#Camera_Position|camera positions]] you don't need to manually set character positions in the script since the appropriate line of code will be automatically generated when you move one of the character position boxes that can be found by default on each participant's spawn box. As with camera positions, you need to make sure to select the <code>say</code> line that you want to edit before making any changes.
+Copying and pasting <code>set_character_pos</code> lines can be useful to reuse positions in cutscenes without having to set them up again.
+=== Pose ===
+Command: <code>send_character_message # "set_animation \"$\""</code>
+Example: <code>send_character_message 1 "set_animation \"Data/Animations/r_dialogue_shade.anm\""</code>
+Makes participant <code>#</code> play the animation at <code>$</code>. Note that we're using ''\"'' to "escape" the <code>"</code> characters.
+You don't have to write this line manually because it can be generated for you if you do the following:
+# Click on the <code>say</code> line in the dialogue that you want the animation to play for
+# Select the dialogue character position box in the 3D view for the character you want to play an animation
+# In the dialogue editor's menu bar, press ''File → Load Pose'' and load the animation you want
+All animations can be found in the ''../Overgrowth/Data/Animations/'' folder.
+=== Eye, Head & Torso Movement ===
+Command: <code>send_character_message # "$ x y z i"</code>
+Example: <code>send_character_message 2 "set_head_target 5.0 3.2 1.1 0.8"</code>
+Makes participant <code>#</code> turn their <code>$</code> towards location <code>x, y, z</code>, with the influence <code>i</code>. If <code>i</code> is <code>1</code>, it will face as much towards <code>x, y, z</code> as possible, and if it's 0 the command has no effect.
+<code>$</code> Can be set to <code>set_head_target</code> or <code>set_torso_target</code>. <code>set_eye_dir</code> used to work, but currently dosn't.
+This command doesn't need to be written manually, because it will be automatically set for the currently selected <code>say</code> line when you move one of the eye, head or torso targets. Scale the targets to change the influence.
+=== Depth of Field ===
+Command: <code>send_level_message "set_camera_dof cs cd cg fs fd fg"</code>
+Example: <code>send_level_message "set_camera_dof 0.3 5.0 10.0 0.3 20.0 10.0"</code>
+'''NOTE:''' The player character needs to be connected to the dialogue for it to work.
+* cs = Close blur strength
+* cd = Anything closer than this value will be blurred
+* cg = How gradual the transition for close dof should be, 0 = infinite blur
+* fs = Far blur strength
+* fd = Anything further than this value will be blurred
+* fg = How gradual the transition for far dof should be, 0 = infinite blur
+The depth of field is split into two parts with three parts in each, the close blur and the far blur. First in each part is how strong the blur should be (<code>xs</code>), then at what distance it should end/start (<code>xd</code>), and then how long the transition from/to the blur should be (<code>cg</code>).
+=== Fade to Black ===
+Command: <code>fade_to_black $</code>
+Example: <code>fade_to_black 1</code>
+<code>$</code> can be set to 1 to make the view fade to black on the next <code>say</code> command. If you set it to 0 afterwards, you get some visual bugs in the dialogue.
+[[Category: Overgrowth]]
+[[Category: Modding]]

Difference between revisions of "Dialogue Editor"

Revision as of 08:07, 16 June 2018

Contents