---
generated_by: gdlink-build
generated_at: 2026-06-23T12:34:28Z
do_not_edit: true
title: Timer
brick_type: executor
tier: Basic
generated: true
---

# Timer

**Category:** Executor
**Tier:** Basic

## Purpose

Controls a typed Timer variable directly.

## Visual Reference

```{raw} html
<div class="illustration-container"><div class="illustration-box"><div class="box-header">As added to your scene</div><img src="https://gdlink.solventech.ca/guide/assets/images/bricks/timer_executor.png" alt="Timer brick as it appears in the GDLink editor" loading="lazy" style="max-width:100%;height:auto;display:block;margin:0 auto;border-radius:8px;" /></div></div>
```

## Runtime Behavior

- Executes once when activated by a gate.
- Reads the selected `Timer` variable, mutates its saved state, and writes it back.
- `Start` / `Resume` set `running=true, paused=false`.
- `Stop` clears both `running` and `paused`.
- `Pause` sets `paused=true, running=false`.
- `Reset` clears elapsed/capture state and stops the timer.
- `Capture` records the current elapsed time into the timer's lap/split snapshot fields.
- Does not create display text by itself.
- Does not target other scene nodes in this wave; the authored scope + variable name are the address.
- Count Down stores elapsed time internally but display/evaluation uses `duration_seconds - elapsed_seconds`, clamped at zero.

```{raw} html
<div class="illustration-container">
        <div class="illustration-box">
            <div class="box-header">Generated UI Mockup — showing expanded properties</div>
            <div class="real-node brick-executor">
                <div class="real-header">
                    <div class="real-title"><span class="brick-icon-fallback"></span> <span>Timer</span></div>
                    <div class="real-controls"><div class="real-checkbox"></div><div class="real-btn">-</div><div class="real-btn">x</div></div>
                </div>
                <div class="real-inner-panel"><div class="real-row name-row" style="position:relative;"><span class="real-label">Name:</span><div class="real-input" style="color:#666; font-style:italic;">Label this brick...</div><div class="real-port" style="left:-15px;"></div></div><div class="real-row"><span class="real-label">Operation:</span><div class="real-input-dropdown">Start</div></div><div class="real-row"><span class="real-label">Scope:</span><div class="real-input-dropdown">Local</div></div><div class="real-inline-row" style="margin-top:4px;"><div class="real-inline-btn" style="background:#2f343d;">Verbose</div></div></div>
            </div>
        </div>
    </div>
```

## Properties

| Property | Type | Default | Notes |
|---|---|---|---|
| Operation | option | Start | Timer operation to perform when this brick activates |
| Scope | option | Local | Where the Timer variable lives |
| Timer | variable_name |  | Timer variable to control |
| Verbose | bool | False | Log the timer command to console (controlled by ladybug button) |

## Example Use Cases

**Race Timer HUD**
```text
Timer Variable:
  Name = race_timer
  Mode = Count Up

Start Button / Delay -> Gate -> Timer(Start, Local, race_timer)
Reset Button / Delay -> Gate -> Timer(Reset, Local, race_timer)
Lap Button / Delay -> Gate -> Timer(Capture, Local, race_timer)

Label Executor:
  Variable = race_timer
  Scope = Local
  Target Node = RaceTimerLabel
```

**Control UI Countdown**
```text
UI Click(StartButton) -> Gate -> Timer(Start, Local, ui_countdown)
UI Click(ResetButton) -> Gate -> Timer(Reset, Local, ui_countdown)
Variable(Local, ui_countdown, timer_field=remaining_seconds, Less or Equal, 0) -> Gate -> Scene(Load Scene, GameOver)
Label(Set, variable=ui_countdown) drives the HUD text.
```