Character Event

The character event is used for characters that have portraits. It allows joining, leaving and updating them and configuring how they appear in the game.

📜 Content

Text Syntax

# Basic join event
join MyCharacter center
# Specifying a portrait and shortcode parameters
join MyCharacter (SomePortrait) center [animation="Bounce In"]
# Character with a space in the name and a portrait that's inside a group
join "My Character" (Special/Crazy) center
# Specifying the transform manually
join MyCharacter pos=x0.5y1 size=y400px rot=20`

# Basic leave event
leave MyCharacter
# Specifying shortcode parameters
leave MyCharacter [animation="Fade Down"]
# Leaving all joined characters
leave --All--

# Update that animates the character
update MyCharacter [animation="Tada" length="2" wait="true"]
# Update that changes the position (and tweens it)
update MyCharacter left [move_time="1" move_trans="Elastic" move_ease="In"]
# Update that changes the portrait
update MyCharacter (OtherPortrait) [fade_time="0.5"]

The Main Settings

Action Setting | Join / Leave / Update

The character event knows three modes Join, Leave and Update.

Join events will add a character. They require a position/transform to be given and will use In-Animations.

Leave events will remove one or all characters. They ignore most settings and will use Out-Animations.

Update events allow you to change stuff, like the position or portrait. They can also be used to animate the character. They have a few settings that Join and Leave don't use: Fade and Fade Time, Move Time, Move Trans and Move Ease. Also the Update event will only change a setting if it has been set, so if no portrait is given the previous portrait is kept, same for the position, etc.

Text Syntax: The mode is set by starting the event with either join, leave or update

Character Setting

The character that is going to be used. In Leave-mode this can be --All-- characters.

Text Syntax: join MyCharacter , leave "My Character", leave --All--

Right after join/leave/update put the character identifier. If the identifier contains a space, you have to put the identifier in quotes.

Portrait Setting

Text Syntax: After the character identifier put the portrait in (brackets): join MyCharacter (MyPortrait)

The portrait that should be used. If none is given, Join mode will use the characters default portrait, while Update mode will just not change the portrait.

Portraits that are in groups have to be specified by full path: Group/SubGroup/Portrait

The portrait setting can be an expression inside {curly brackets}, for example a variable: {PlayerPortrait}. The experssion will be evaluated and interpreted as a string that should be the name/path of a portrait.

Position/Transform Setting

This setting defines where on screen your character is positioned. When you character is joined it will be put in a brand new PortraitContainer, which you can then change the position, size and rotation of with the transform setting. There are two ways to do so:

  • Using a preset "position" you can easily copy the tranform of one of the PortraitContainers defined in your style by using one of it's identifiers. By default dialogic provides 5 of these preset positions, named "leftmost", "left", "center", "right", "rightmost".

  • Using transform commands you can position, size and rotate the container with more control. For example pos=x0.5y1 size=y400px rot=20.

Using a Preset Positions

Moving the container to a preset position is as easy as writing the name of that position.

In the default "5-Portraits" style layer the defined positions are leftmost,left, center, right, rightmost.

Note

If you want more/other preset positions you will have to create a custom portrait layer. You then have to change the position names that will be suggested in the timeline editor in the Settings>Portraits.

Using Transform Commands

There are three transform commands: pos= (position), size= and rot= (rotation).

Position and size can be specified like this: x0.5 y1, x100px y1% By default x and y are interpreted as relative to the viewport size, meaning 0.5 means half the width/height of the window.

Position defines the ORIGIN of the portrait (usually the bottom center). This means a position of x0.5 y1 will position the portrait like this:

When first joining a character, the position, size and rotation will be copied from the first portrait preset found. This means if you just want to vary the position along the x axis, a simple pos=x0.3 is usually enough and all the other values will be correct by default.

Rotation is given in degrees. The portrait rotates around it's origin (usually the bottom center)!

The Other Settings

In the text editor these settings are all stored as parameters in the shortcode at the end of the event.

E.g. join MyCharacter center [animation="Bounce" length="1" mirrored="true" ]

Animation Setting

Text Syntax: animation="Bounce"

The animation setting allows you to set an animation that should be used. The selection of animations is different depending on the mode.

If no animation is given, Join and Leave will fallback to defaults that can be set in Settings>Portraits, while Update won't play any animation.

The animation name is quite forgiving meaning Fade Up, fade up in fade In Up will all point to the right animation (assuming this is a join event).

You can add animations to dialogic with extensions: Creating Extensions

Animation Length Setting

Text Syntax: length="2" / length="0.5"

If an animation is set, this defines the length of the animation in seconds.

Animation Wait Setting

Text Syntax: wait="true" / wait="false"

If an animation is set, this defines, whether to wait for the animation to finish before going to the next event.

Animation Repeat Setting

Text Syntax: repeat="2"

The animation repeat setting (exclusive to the Update mode) allows repeating the animation multiple times.

Fade Setting

Text Syntax: fade="Fade"

The fade setting (exclusive to the Update mode and only relevant if the portrait changes) defines the Crossfade animation that is used to fade from the last portrait to the next. If none is given it will fall back to a default that can be set in Setting>Portraits.

Fade Length Setting

Text Syntax: fade_length="0.5"

Defines the length of the fade in seconds.

Z-Index Setting

Text Syntax: z_index="2"

The z-index allows you to sort your characters. It is not using godot's z-index and instead sorting the characters manually!

Mirror Setting

Text Syntax: mirrored="true"

Allows mirroring the portrait.

Move Settings

Text Syntax: move_time="0.8" / move_trans="Elastic" / move_ease="In Out"

On Update events that change the position you can set the time (in seconds), transition and easing used to tween from the old to the new position.

Easings: In, Out, In Out Out In

Transitions: Linear, Sine, Quint, Quart, Expo, Elastic, Cubic, Circ, Bounce, Back, Spring

See this Easing Cheat Sheet for something more visual.

Extra Data Setting

Text Syntax: extra_data="something"

The extra data is given to the portrait scene and allows communicating with the portrait scene directly from the timeline. It can be evaluated from the _set_extra_data(data:String) method on custom portraits.