Attributes

Attributes are variables that store information about your story’s state. You can use them to track things like player choices, scores, inventory, character relationships, and any other data that changes as the story progresses.

Setting attributes

Using directives

The simplest way to set an attribute is using the @set directive:

@set score = 1000
@set player_name = Alice

If the value is a number, it will be stored as a number. Otherwise, it will be stored as a string.

For boolean (true/false) values, to set as true:

@set has_key

and to set as false:

@set not has_key

or alternatively:

@unset has_key

For number values, you can increase or decrease by 1:

@inc score
@dec health

Or increase or decrease by other amounts:

@inc score 100
@dec health 5

Setting from links

You can set attribute values directly from section and passage links using a comma-separated list of assignments:

You can also use increment (+=) and decrement (-=) operators in link attributes:

Conditional attribute changes

The @set, @inc, @dec, and @unset directives run when a section or passage loads—they always execute regardless of any {{#if}} conditions in the text.

If you want to change an attribute conditionally (only when an {{#if}} condition is true), use the helper versions instead:

{{#if (seen "helped the wizard")}}
{{inc "reputation"}}
The wizard remembers your kindness.
{{else}}
The wizard eyes you suspiciously.
{{/if}}

The available helpers are:

{{set "attribute" value}} — set an attribute to a value
{{unset "attribute"}} — set an attribute to false
{{inc "attribute"}} — increase a number attribute by 1
{{inc "attribute" 5}} — increase by a specific amount
{{dec "attribute"}} — decrease by 1
{{dec "attribute" 3}} — decrease by a specific amount

These helpers produce no visible output—they only modify the attribute. The key difference from the @ directives is that they execute at render time, so they respect {{#if}} conditions.

Reading attributes

You can display the value of an attribute using {{name}} (if the attribute name is all one word), or {{get "attribute name"}} for multi-word attributes or when the attribute name comes from an expression.

You chose {{gender}}.
Your full name is {{get "player name"}}.

Both {{attribute}} and {{get "attribute"}} always return the latest value, even if the attribute was just modified by a helper in the same section.

The main use for {{get}} is when you need to read an attribute whose name is stored in another variable. This enables dynamic attribute lookup:

In this example, {{get room}} looks up the value of room (e.g., “kitchen”), then uses that as the name of another attribute to retrieve (getting the description stored in the kitchen attribute).

You can also read a value using JavaScript:

    var gender = squiffy.get("gender");

Comparing attributes

Squiffy provides comparison helpers for working with attribute values in conditionals.

Equality comparisons

Use {{eq}} to check if two values are equal, and {{ne}} to check if they’re not equal:

Numeric comparisons

For number values, you can use:

{{gt a b}} — greater than (a > b)
{{gte a b}} — greater than or equal (a >= b)
{{lt a b}} — less than (a < b)
{{lte a b}} — less than or equal (a <= b)

Logic helpers

You can combine conditions using logic helpers:

{{and ...}} — returns true if all arguments are truthy
{{or ...}} — returns true if any argument is truthy
{{not value}} — negates a boolean value

Tracking sections and passages

The `{{seen}}` helper

You can check if the player has visited a section or passage using the {{seen}} helper:

You can also use JavaScript:

    if (squiffy.story.seen("passage3")) {
        alert("You have seen passage3!");
    }

The `{{at}}` helper

The {{at}} helper checks if you’re currently at a specific section. It can take a single section name or an array of section names.

This helper is particularly useful in master sections or passages (see Master sections and passages), where you want to display different content depending on which section the player is in. It can also be useful when embedding text from another section.

Embedding text

You can embed text from another section, or from a passage in the current section, using {{embed "section or passage name"}}.

This is useful for reusing descriptions or text that appears in multiple places:

Creating links with helpers

In addition to the standard link syntax, you can create links programmatically using the {{section}} and {{passage}} helpers.

The `{{section}}` helper

Creates a link to a section with optional custom text and attribute settings:

{{section "section_name" text="Link text" set="attribute=value, count+=1"}}

The `{{passage}}` helper

Creates a link to a passage with optional custom text and attribute settings:

{{passage "passage_name" text="Link text" set="visited=true"}}

Here’s a complete example showing how attributes can work together to create a food ordering system:

Using attributes in JavaScript

You can interact with attributes using JavaScript in any section or passage:

Setting values

    squiffy.set("attribute_name", value);
    squiffy.set("score", 100);
    squiffy.set("has_key", true);

Getting values

    var score = squiffy.get("score");
    var hasKey = squiffy.get("has_key");

Example with JavaScript

Advanced: Arrays and complex data

You can use the {{array}} helper to create arrays for use with other helpers like {{random}}, {{rotate}}, and {{at}}:

{{random (array "option1" "option2" "option3")}}
{{at (array "section1" "section2" "section3")}}

See Dynamic text for more information on using arrays with dynamic content helpers.