Characters

Characters in VNKit are images that stand on the stage, in front of the background. You show them, move them between slots, and change their image as the story goes on.

Naming your images

VNKit finds a character’s image from the words you give it. In <<show fred "green happy">>, the words are fred, green and happy. The first word is the character.

VNKit looks in your Resources folders for the image, trying these names in order and using the first one it finds:

fred/green/happy
fred-green-happy
fred green happy
green/happy
green-happy
green happy

The first three join the words with /, -, and spaces. The last three do the same without the character’s name, for images that aren’t named after their character.

The file extension doesn’t matter, as long as Unity can import the file as a Sprite. The simplest layout is a folder for each character, with a file for each pose:

Resources/Capsley/neutral.png
Resources/Capsley/happy.png
Resources/Capsley/sad.png

Three of Capsley’s images, one file for each pose.

With these, <<show capsley happy>> shows Capsley/happy.png.

Showing a character

<<show character pose seconds>> shows a character’s image:

<<show capsley happy 0.5>>

Showing Capsley’s happy image over half a second.

If the character isn’t on stage yet, they appear in the slot you last moved them to, or in centre if you haven’t moved them.
If the character is already on stage, their image changes and they stay in their slot.

Slots

Characters stand in slots across the stage. There are five:

Slot	Position across the stage
`far_left`	0.1
`left`	0.28
`centre`	0.5
`right`	0.72
`far_right`	0.9

The slots in a new Configuration asset. 0 is the left edge of the stage, and 1 is the right edge.

A character stands with the middle of their feet on their slot’s position. If a character is too wide to fit there, they’re moved in until they’re fully on the stage.

There are also two slots just off the edges of the stage, off_left and off_right, for characters walking on and off.

Choosing where a character appears

To bring a character on in a particular slot, move them there first, then show them:

<<move fred left>>
<<show fred happy 0.5>>

Bringing Fred on in the left slot.

To have a character walk on from the side, show them off the stage, then move them on:

<<move dragon off_right>>
<<show dragon neutral>>
<<move dragon right 1>>

The Dragon walking on from off_right.

Changing the slots

The slots are set in the Slots list on your Configuration asset. Each slot has a Name, and a Position from 0 to 1. You can move the slots, rename them, and add your own. A project could add a slot called doorway at 0.4, and write:

<<move capsley doorway>>

Moving Capsley to a slot called doorway.

off_left and off_right are always there, and aren’t in the list.

Moving a character

<<move character slot seconds>> moves a character to a slot:

<<move fred right 0.5>>

Moving Fred to the right slot over half a second.

You can name the character, or the slot they’re in. <<move left right>> moves whoever is in the left slot to right.

If the slot already has a character in it, that character is moved off the stage and removed.

Changing a character

Command	What it does
`<<hide character seconds>>`	Removes the character from the stage.
`<<fade_out character seconds>>`	Fades the character out. They stay in their slot.
`<<fade_in character seconds>>`	Fades the character back in.
`<<pop character seconds>>`	Makes the character pop, to draw attention to them. Needs a duration.
`<<shake character seconds>>`	Shakes the character. Needs a duration.
`<<flip character seconds>>`	Flips the character horizontally.
`<<flip_vertical character seconds>>`	Flips the character vertically.

Commands for changing a character on stage.

All of these take a character’s name or a slot. If Fred is in the left slot, <<shake left 1>> and <<shake fred 1>> do the same thing.

Character size

Characters are scaled to fit the stage. <<scale character size>> makes a character’s images bigger or smaller, where 1 is the normal size:

<<scale d 0.5>>

Making d half the normal size.

scale uses the character’s name from your Yarn script, set with the character Command. If the character is on stage, they change size straight away.

How characters animate

How characters appear, change, move and leave is set on the Basic Animator component, on VNKit’s Stage prefab. The duration you give a Command says how long the animation takes.

Setting	Used when	Starts as
Show New Character Animation	A character appears in an empty slot.	Fade
Update Existing Character Animation	A character on stage changes image.	None
Replace Character Animation	A character appears in a slot someone else is in.	Move
Change Character Position Animation	A character moves to another slot.	Move
Remove Character Animation	A character is hidden.	Fade
Move In Direction	A character moves onto the stage with the Move animation.	Up
Move Out Direction	A character moves off the stage with the Move animation.	Down
Deemphasised Colour	A character isn’t emphasised.	A mid grey

The Basic Animator’s settings.

Each animation can be Move, Fade, or None.

Emphasis

When a character speaks, they’re emphasised, and every other character on stage is dimmed to the Deemphasised Colour. You don’t need any Commands for this.

To emphasise characters yourself, use emphasise and deemphasise:

<<emphasise capsley witch>>
<<deemphasise dragon 0.5>>
<<emphasise all>>

Emphasising and dimming characters.

<<emphasise names>> emphasises the named characters, and dims everyone else.
<<deemphasise names>> dims the named characters, and emphasises everyone else.
all emphasises or dims every character.

A duration, and nowait, can go after the names.

Changing images with hashtags

Instead of a show before a line, you can put a hashtag on the line:

c: Can I interest you in some yarn? #happy

A line that shows Capsley/happy.

When a character has a line with a hashtag on it, VNKit adds the hashtag to the character’s image name, and shows that image. Here, the image name is Capsley, so the line shows Capsley/happy. Hashtags that don’t match an image are ignored.

A character’s image name is their display name, from the character Command. If you haven’t used character for them, it’s the name before the colon. If their images are named something else, set the image name with the images Command:

<<character s Sylvie>>
<<images s "sylvie green">>
s: Hi there! #smile

Sylvie, whose images are named sylvie green.

Here, #smile shows sylvie green smile. You can also set the image name in the Image Name field on a character’s Character Data.

Alternative images

<<alias_sprite original alternative>> adds an image that’s used instead of another. If you add more than one alternative for an image, VNKit picks one of them at random each time the original is used:

<<alias_sprite "capsley angry" "capsley very angry">>
<<alias_sprite "capsley angry" "capsley regular angry">>
<<show capsley angry>>

Two alternatives for capsley angry.

Characters between nodes and backgrounds

By default, characters stay on stage when the story moves to another node, and when the background changes. scene is the exception: it removes every character before it changes the background.

The Image Presenter on VNKit’s Stage prefab can change this:

Hide Images On Node Change removes every character when a node ends. A node with the header PersistVNImages: true keeps its characters on stage anyway.
Hide Images On Background Change removes every character when the background changes.

Next step Backgrounds and Stages Backgrounds, the size of the stage, and using more than one stage.

Mark this page as complete Completed!

Previous Writing Commands Next Backgrounds and Stages