Smart Variables

Learn about using smart variables that determine their value at run-time.

ESC
↑↓ Navigate ↵ Open esc Close

Smart Variables

Smart variables in Yarn Spinner are variables whose value comes from an expression. Unlike regular variables that only change when explicitly set, smart variables recalculate their value every time they’re accessed, based on the expression that defines them.

Why Use Smart Variables?

  1. Code Readability: They make your dialogue scripts more readable by using meaningful names instead of complex conditions.
  2. Centralised Logic: Define a condition once and use it throughout your game.
  3. Maintenance: When game mechanics change, you only need to update the smart variable declaration, not every place it’s used.
  4. Abstraction: They hide complex game state checks behind simple, descriptive names.

Examples

To create a smart variable, use the <<declare>> command followed by a variable name (with the $ prefix) and assign it an expression rather than a static value. The expression can use mathematical operations, logical comparisons, or reference other variables.

For example: <<declare $is_powerful = $strength > 50 && $magic_ability >= 20>>.

This smart variable is worked out again each time it’s read, so your dialogue responds to changes in $strength or $magic_ability without additional code.

Example 1: Character Relationships

Yarn 
title: Start
---
<<declare $player_is_friends_with_sam = $sam_relationship_score > 50>>

<<if $player_is_friends_with_sam>>
  Sam: Hey buddy! Good to see you again.
<<else>>
  Sam: Oh, it's you. What do you want?
<<endif>>
===
A smart variable for a character relationship.

Example 2: Item Availability

Yarn 
title: Start
---
<<declare $has_enough_materials = $wood >= 5 && $nails >= 10>>
<<declare $has_required_skill = $carpentry_level >= 3>>
<<declare $can_build_chair = $has_enough_materials && $has_required_skill>>

<<if $can_build_chair>>
  Craftsman: You've got everything you need to build that chair now.
<<else>>
  <<if !$has_enough_materials>>
    Craftsman: You'll need more materials first.
  <<else>>
    Craftsman: Your carpentry skills aren't quite there yet.
  <<endif>>
<<endif>>
===
Smart variables for item availability.
flowchart BT
  chair_wood["$wood"]
  chair_nails["$nails"]
  chair_level["$carpentry_level"]
  chair_materials(["$has_enough_materials<br>$wood #gt;= 5 #amp;#amp; $nails #gt;= 10"])
  chair_skill(["$has_required_skill<br>$carpentry_level #gt;= 3"])
  chair_build(["$can_build_chair<br>$has_enough_materials #amp;#amp; $has_required_skill"])
  chair_wood --- chair_materials
  chair_nails --- chair_materials
  chair_level --- chair_skill
  chair_materials --- chair_build
  chair_skill --- chair_build
The variables in Example 2. The rounded boxes are smart variables, each worked out from the variables below it every time it’s used, so $can_build_chair always reflects the current $wood, $nails and $carpentry_level.

Example 3: Time-Based Events

Yarn 
title: Start
---
<<declare $is_evening = $game_hour >= 18 && $game_hour < 22>>
<<declare $town_shops_open = !$is_holiday && $game_hour >= 9 && $game_hour < 18>>

<<if $is_evening && !$town_shops_open>>
  Innkeeper: Most shops are closed now, but you're welcome to stay here for the night.
<<endif>>
===
Smart variables for time-based events.

Benefits in Complex Games

Smart variables help most when you have conditions that you check frequently or that combine multiple factors. They’re useful for:

  • Tracking complex character states
  • Monitoring game world conditions
  • Representing player achievements or quest status
  • Creating dialogue that responds to multiple game systems
Previous Once Next Enums