Once

Learn about once statements, which let you specify content that only runs once.

ESC
↑↓ Navigate ↵ Open esc Close

Once

Sometimes it’s useful to create lines of dialogue that can only ever be displayed once.

You can use a once statement to denote content that can only be run once. When the script reaches a once statement, it checks to see if it’s run before. If it has, it skips over it.

You can use once statements to make sure that the player never sees certain content more than once. For example, you might want a character to never introduce themselves to the player twice.

There are two main ways you can use a once statement.

You can wrap some lines in <<once>> and <<endonce>>:

Yarn 
title: Start
---
<<once>>
  // The guard will introduce herself to the player only once. 
  Guard: Hail, traveller! Well met.
  Guard: I am Alys, the guard!
<<endonce>>
===
Lines wrapped in <<once>> and <<endonce>>.

You can also use an <<else>> clause within the <<once>> statement, which will be run if the relevant <<once>> content has already been seen:

Yarn 
title: Start
---
<<once>>
  Guard: Hail, traveller! Well met.
<<else>>
  Guard: Welcome back.
<<endonce>>
===
A once statement with an else.

You can also add an if to the once to run content a single time, but only when a certain condition is true. In all other cases, it will be skipped (or the else content will be run, if there is any):

Yarn 
title: Start
---
<<once if $player_is_adventurer>>
  // The guard knows the player is an adventurer, so say this line, 
  // but only ever once!
  Guard: I used to be an adventurer like you, but then I took an arrow in the knee.
<<else>>
  // Either the player is not an adventurer, or we already saw the 
  // 'arrow in the knee' line.
  Guard: Greetings.
<<endonce>>
===
A once if statement.

You can add <<once>> to a line, or options:

If you add once (or once if) to a line, that line will only appear once, and will be skipped over every other time it’s encountered:

Yarn 
title: Start
---
Guard: Who are you? <<once>> // Show this line only one time
Guard: Go on, get lost!
===
A line with once.

Similarly, if you add it to an option, that option will only be selectable once, and will be marked as unavailable after it’s been selected.

Yarn 
title: Start
---
-> What's going on? <<once>>
	Guard: The kingdom is under seige!
-> Where can I park my horse? <<once if $has_horse>>
	Guard: Over by the tavern.
-> Lovely day today!
	Guard: Uh huh.
-> I should go.
	Guard: Please do.
===
Options with once and once if.

once statements are useful when you want to show long, detailed content the first time it’s encountered, but you don’t want to show it every time. This means that players don’t need to mash the ‘skip line’ button over and over when they realise that they’re starting to see a long run of lines they’ve already seen:

Yarn 
title: Start
---
<<once>>
	// Show long, character-establishing lines the first time
	Guard: There's nothing new to report!
	Guard: I've been at this post for hours, and I'm so bored.
	Guard: I can't wait for the end of my watch.
<<else>>
	// Show a more condensed version all other times
	Guard: Nothing to report!
<<endonce>>
===
A long version the first time, and a short version after that.
once statements keep the information about whether they’ve been run or not in a variable that’s stored in your Dialogue Runner’s Variable Storage, like any other variable. The variable isn’t directly accessible from your Yarn scripts.

Putting it together

This longer example uses once on lines, in a <<once>> statement with an <<else>>, and with once if:

Yarn 
title: Start
---
<<declare $caves = false>>
<<declare $castle = false>>
<<declare $gold = 0>>

Narrator: You make your way into a new town... <<once>>
Narrator: Where are you heading? 
    -> Caves! <<if !$caves>>
        <<jump Caves>>
    -> Ruined castle! <<if !$castle>>
        <<jump Castle>>
    -> Leave town. <<if $castle and $caves>>
===

title: Caves
---
<<once>>
    Narrator: You make your way into the forboding caves.
<<else>>
    Narrator: The blackness of the caves beckons...
<<endonce>>
Narrator: Go deeper?
    -> Yes.
        Narrator: You push deeper into the black.
        Narrator: You find a pile of gold!
        <<set $gold = $gold + 100>>
        Narrator: You return to town with your riches.
            <<set $caves = true>>
            <<jump Start>>
    -> No.
        Narrator: The caves are scary. <<once>>
        Narrator: Back to town!
            <<jump Start>>
===

title: Castle
---
Narrator: You wander into the ruined castle...
Narrator: With your gold, you'd best keep your wits about you. <<once if $gold > 0>>
Narrator: Unfortunately, there's nothing of interest here...
<<set $castle = true>>
Narrator: You head back to town!
<<jump Start>>
===

title: Leave
---
Narrator: You wander off, in search of your next adventure.
===
once used across several nodes.
Previous Flow Control Next Smart Variables