# Functions

A **function** is a block of code that provides a value to your Yarn scripts, which you can use in [`if` statements](/write-yarn-scripts/scripting-fundamentals/flow-control.md), or store in [variables](/write-yarn-scripts/scripting-fundamentals/logic-and-variables.md).

In Yarn Spinner scripts, functions perform two main kinds of task:

* Functions let you get values that change over time, or that depend on other values. For example, the `random` function returns a different random number every time you call it.
* Functions let you get data from your game back into your scripts.

You call a function inside an expression. For example:

```yaml
// Inside an if statement:
<<if dice(6) == 6>>
    You rolled a six!
<<endif>>

// Inside a line:
Gambler: My lucky number is {random_range(1,10)}!
```

## Built-In Functions

Yarn Spinner comes with several **built-in functions** for you to use.

### `visited(string node_name)`

`visited` returns a boolean value of `true` if the node with the title of `node_name` has been entered and exited at least once before, otherwise returns `false`. Will return `false` if `node_name` doesn't match a node in project.

### `visited_count(string node_name)`

`visted_count` returns a number value of the number of times the node with the title of `node_name` has been entered and exited, otherwise returns `0`. Will return `0` if `node_name` doesn't match a node in project.

### `format_invariant(number n)`

`format_invariant` returns a string representation of `n`, formatted using the invariant culture. This is useful for embedding numbers in commands, where the command expects the number to be formatted using the invariant culture. For example, `<<give_gold {$gold}>>`, which might end up as `give_gold 4,51` in German, but `give_gold 4.51` in English, can now be `<<give_gold {format_invariant($gold)}>>`, which will always be `give_gold 4.51`.

### `random()`

`random` returns a random number between 0 and 1 each time you call it.

### `random_range(number a, number b)`

`random_range` returns a random number between `a` and `b`, inclusive.

### `dice(number sides)`

`dice` returns a random integer between 1 and `sides`, inclusive.

For example, `dice(6)` returns a number between 1 and 6, just like rolling a six-sided die.

### `min(number a, number b)`

`min` compares `a` and `b`, and returns the smaller of the two.

### `max(number a, number b)`

`max` compares `a` and `b`, and returns the larger of the two.

### `round(number n)`

`round` rounds `n` to the nearest integer.

### `round_places(number n, number places)`

`round_places` rounds `n` to the nearest number with `places` decimal points.

### `floor(number n)`

`floor` rounds `n` down to the nearest integer, towards negative infinity.

### `ceil(number n)`

`ceil` rounds `n` up to the nearest integer, towards positive infinity.

### `inc(number n)`

`inc` rounds `n` up to the nearest integer. If `n` is already an integer, `inc` returns `n+1`.

### `dec(number n)`

`dec` rounds `n` down to the nearest integer. If `n` is already an integer, `dec` returns `n-1`.

### `decimal(number n)`

`decimal` returns the decimal portion of `n`. This will always be a number between 0 and 1. For example, `decimal(4.51)` will return `0.51`.

### `int(number n)`

`int` rounds `n` down to the nearest integer, towards zero.

{% hint style="info" %}
This is different to `floor`, because `floor` rounds to negative infinity.
{% endhint %}

## Custom Functions

{% hint style="danger" %}
We recommend that you only move into the Yarn Spinner for Unity documentation after learning the fundamentals of Yarn Spinner Scripting.
{% endhint %}

You can create your own commands, so that your scripts can send directions to your game. For more information on how to create them in Unity games, see [Creating Commands and Functions](/yarn-spinner-for-unity/creating-commands-functions.md), in the Yarn Spinner for Unity section of the documentation, and equivalents for other engines.

{% hint style="warning" %}
Functions are not intended to be a way for you to send instructions to your game. For that purpose, you should use [commands](/write-yarn-scripts/scripting-fundamentals/commands.md).

As much as possible, custom functions should be [pure functions](https://en.wikipedia.org/wiki/Pure_function), and have no side effects besides returning a value based on parameters.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.