# Time

## Use Cases:

* Racing games
* Poison system
* Damage over time systems 
* Crafting timers
* Areas upgrading and degrading over time for management or resource gathering
* Preparation time at cooking stations
* Lock outs 
* Puzzles

{% hint style="warning" %}
Set **Broadcast Type** to *All* or *Rules* to send messages from objects to the Rules System.
{% endhint %}

{% hint style="info" %}
Use the **Math** rule to increase or decrease a paused timer. 

Reduce a numerical variable with a negative value.
{% endhint %}

## Start Timer

{% tabs %}
{% tab title="About" %}

#### **Time events, delay interactions and more with timers!**

The **Start Time** rule allows creators to create descending timers that will send a message once they reach 0. This allows for more dynamic timed and delayed events. Close a door if a player is too slow to reach it, Spawn new waves of enemies after a certain time or simply delay a reaction to a players interaction.

<figure><img src="https://331512196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F83PS3g9zpWmq73xzlwFn%2Fuploads%2FmLMI4UdW0NYVpJ930u9I%2Fimage.png?alt=media&#x26;token=cd40a235-1da4-4377-a44d-53a8629e98dd" alt="" width="330"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Details" %}
**Required Message**&#x20;

The message to activate this tree. Every time this message is broadcast the tree will be triggered.

**Time variable**&#x20;

This will define which **Variable** of the type **Time** will be modified by this rule.

**Duration**&#x20;

There are three modes to define how much time will be on the timer after it starts

* **Variable** will allow you to define an existing variable to modify the timer. This variable can be modified elsewhere using the **Roll a Random Number, Add/Subtract number** or **Set number value** Rules. A dropdown menu will appear to select a variable.
* **Fix value** will allow you to set up a constant value. An input field will appear to enter the number value.
* **Message Argument** will allow you to use an argument sent within the message. The message has to be created with an argument of the number type for it to be selectable here. A dropdown menu will appear to select the message argument.

**Message to stop the rule**&#x20;

If the timer needs to be stopped prematurely it can be done using this message.

**Message to send**&#x20;

The message that is sent out when the timer is finished.
{% endtab %}
{% endtabs %}

## Stopwatch

{% tabs %}
{% tab title="About" %}

#### **Keep track of individual players' times in a race.**

With the **Stopwatch** rule it is possible to create an ascending stopwatch. It will run until it is stopped and the timer can trigger messages by using the [**Compare Time**](#compare-time-1) rule.

<figure><img src="https://331512196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F83PS3g9zpWmq73xzlwFn%2Fuploads%2FStYaeq0YcXl8Oyr8ccZ9%2Fimage.png?alt=media&#x26;token=b125c592-0c24-47f6-a815-07cedf32df3c" alt="" width="325"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Details" %}
**Required message**&#x20;

The message to activate this tree. Every time this message is broadcast the tree will be triggered.

**Time variable**&#x20;

This will define which **Variable** of the type **Time** will be modified by this rule.

**Message to stop**&#x20;

With this message the Stopwatch can be stopped, for example when crossing a finish line.
{% endtab %}
{% endtabs %}

## Pause time

{% tabs %}
{% tab title="Pause Time" %}

#### **Set up breaks and give players some time to catch their breath during a race.**

With the **Pause time** rule you can pause and unpause a running time variable. It is also possible to react to a timer being paused or unpaused by sending a message each time the state changes.

<figure><img src="https://331512196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F83PS3g9zpWmq73xzlwFn%2Fuploads%2Ft9DajhMfUmDfGZUwge3T%2Fimage.png?alt=media&#x26;token=a5b3081f-a837-4e89-883b-bad2b28cf813" alt="" width="330"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Details" %}
**Required Message**&#x20;

The message to activate this tree. Every time this message is broadcast the tree will be triggered.

**Time variable**&#x20;

This will define which **Variable** of the type **Time** will be modified by this rule.

**Pause State**&#x20;

There are three modes to define how much time will be added to the timer:

* **Variable** will allow you to define an existing variable to modify the timer. This variable can be modified elsewhere using the **Set true/false value** rule. A dropdown menu will appear to select a variable.
* **Fix value** will allow you to set up a constant value. An checkbox will appear to toggle the value.
* **Message Argument** will allow you to use an argument sent within the message. The message has to be created with an argument of the true/false type for it to be selectable here. A dropdown menu will appear to select the message argument.

{% hint style="info" %}
A true value (a ticked checkbox) will cause the timer to be paused, while a false value will un-pause the timer.
{% endhint %}

**Message to send**

This message can be send out after the timer is paused or un-paused. This is an optional field an can be set to *none*.
{% endtab %}
{% endtabs %}

## Set time value

{% tabs %}
{% tab title="About" %}

#### **Reset timers to restart races or reuse timer variables.**

The **Set Time value** rule is an easy way to set the timer to a specific value without having to calculate anything. The timer can be set to new values or be set to zero if a race is over or lost.

<figure><img src="https://331512196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F83PS3g9zpWmq73xzlwFn%2Fuploads%2FwR9CBCX9UTB1oYb3RtJJ%2Fimage.png?alt=media&#x26;token=6e7fdec8-7cd3-414c-a6f3-3b3f4b5be27f" alt="" width="375"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Details" %}
**Required message**&#x20;

The message to activate this tree. Every time this message is broadcast the tree will be triggered.

**Time variable**&#x20;

This will define which **Variable** of the type **Time** will be modified by this rule.

**New time value**&#x20;

There are three modes to define the value the time will set to:

* **Variable** will allow you to define an existing variable to modify the timer. This variable can be modified elsewhere using the **Roll a Random Number, Add/Subtract number** or **Set number value** Rules. A dropdown menu will appear to select a variable.
* **Fix value** will allow you to set up a constant value. An input field will appear to enter the number value.
* **Message Argument** will allow you to use an argument sent within the message. The message has to be created with an argument of the number type for it to be selectable here. A dropdown menu will appear to select the message argument.
  {% endtab %}
  {% endtabs %}


---

# 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.sandbox.game/en/creator/game-maker/docs/game-rules/time.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.