Timers and counters

Delay execution and count events with awaitable promises.

Overview

Timers let MAST scripts wait for a real-time or simulation-time duration before continuing. Two time bases are available:

Real time (delay) — wall-clock seconds; unaffected by simulation speed.
Simulation time (delay_sim) — scaled by the engine's simulation clock.

Counters (count_goal) are awaitable promises that resolve once a named counter reaches a target value. Increment the counter with increment_count; reset it with reset_count.

All timer and counter functions are designed to be used with await in MAST:

await delay_sim(seconds=5)
await count_goal("enemies_killed", 10)

Quick example

MAST pyMAST

== timed_event ==
    log("Reactor will detonate in 30 seconds!")
    await delay_sim(seconds=30)
    log("The reactor has detonated!")
    explode_player_ship(station_id)
    ->END

== count_kills ==
    await count_goal("kills", 5)
    log("You have destroyed 5 enemies.")
    ->END

//signal/enemy_destroyed
    increment_count("kills")

from sbs_utils.procedural.timers import delay_sim, delay, count_goal, increment_count, reset_count

# Wait 10 simulation seconds before continuing
await delay_sim(seconds=10)

# Wait 5 real seconds
await delay(seconds=5)

# Count-based gate
await count_goal("patrols_complete", 3)

# Increment from signal handlers or events
increment_count("patrols_complete")
reset_count("patrols_complete")

Real time vs simulation time

Function	Time base	Pauses with sim?
`delay(seconds)`	Wall clock	No
`delay_sim(seconds)`	Simulation clock	Yes

API

`clear_counter(id_or_obj, name)`

Remove a named counter from an agent.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Counter name.	required

Example

clear_counter(SHIP_ID, "docked")

`clear_timer(id_or_obj, name)`

Clear a named timer so it is no longer set.

After clearing, is_timer_set returns False and is_timer_finished returns True.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Timer name.	required

Example

clear_timer(SHIP_ID, "cooldown")

`delay_app(seconds=0, minutes=0)`

Suspend the current task for a duration measured in real application time.

Application time is not affected by game pause.

Parameters:

Name	Type	Description	Default
`seconds`	`int`	Duration in seconds. Defaults to 0.	`0`
`minutes`	`int`	Additional duration in minutes. Defaults to 0.	`0`

Returns:

Name	Type	Description
`Delay`	`Delay`	A promise that resolves when the time has elapsed.

Example

await delay_app(seconds=3) "Three real seconds have passed (even if paused)."

`delay_sim(seconds=0, minutes=0)`

Suspend the current task for a duration measured in simulation time.

Simulation time can be paused (e.g. when the game is paused).

Parameters:

Name	Type	Description	Default
`seconds`	`int`	Duration in seconds. Defaults to 0.	`0`
`minutes`	`int`	Additional duration in minutes. Defaults to 0.	`0`

Returns:

Name	Type	Description
`Delay`	`Delay`	A promise that resolves when the time has elapsed.

Example

await delay_sim(seconds=5) "Five simulation seconds have passed."

`delay_test(seconds=0, minutes=0)`

Suspend a task for use in unit tests (not real-time).

Uses DelayForTests which counts poll iterations rather than wall or sim time, so tests run fast without sleeping.

Parameters:

Name	Type	Description	Default
`seconds`	`int`	Simulated duration in seconds. Defaults to 0.	`0`
`minutes`	`int`	Additional simulated minutes. Defaults to 0.	`0`

Returns:

Name	Type	Description
`DelayForTests`		A promise that resolves after enough poll ticks.

`format_time_remaining(id_or_obj, name)`

Return the time remaining on a timer as a M:SS string.

Returns an empty string when the timer has expired or is not set.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Timer name.	required

Returns:

Name	Type	Description
`str`		Formatted remaining time, e.g. `"1:30"`, or `""` if expired.

Example

gui_text("Time: {format_time_remaining(SHIP_ID, 'mission')}")

`get_counter_elapsed_seconds(id_or_obj, name, default_value=None)`

Return the number of seconds elapsed since a counter was started.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Counter name.	required
`default_value`	`optional`	Value returned if the counter was never started. Defaults to None.	`None`

Returns:

Type	Description
	float \| None: Seconds elapsed, or `default_value` if not set.

Example

elapsed = get_counter_elapsed_seconds(SHIP_ID, "docked", 0) if elapsed > 60: "Docking complete."

`get_time_remaining(id_or_obj, name)`

Return the number of whole seconds remaining on a timer.

Returns 0 when the timer has expired or is not set.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Timer name.	required

Returns:

Name	Type	Description
`int`		Seconds remaining, or `0` if expired or not set.

Example

secs = get_time_remaining(SHIP_ID, "mission") if secs < 60: "Less than a minute remaining!"

`is_timer_finished(id_or_obj, name)`

Return whether a timer has expired. Returns True if the timer is not set.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Timer name.	required

Returns:

Name	Type	Description
`bool`		`True` if the timer has expired or was never set.

Example

if is_timer_finished(SHIP_ID, "repair"): "Repair bay ready."

`is_timer_set(id_or_obj, name)`

Return whether a named timer exists on an agent.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Timer name.	required

Returns:

Name	Type	Description
`bool`		`True` if the timer has been set (even if already expired).

Example

if not is_timer_set(SHIP_ID, "cooldown"): set_timer(SHIP_ID, "cooldown", seconds=10)

`is_timer_set_and_finished(id_or_obj, name)`

Return whether a timer was explicitly set and has since expired.

Unlike is_timer_finished, returns False when the timer was never set. Use this to distinguish "timer done" from "timer never started".

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Timer name.	required

Returns:

Name	Type	Description
`bool`		`True` only if the timer was set and has now expired.

Example

if is_timer_set_and_finished(SHIP_ID, "cooldown"): clear_timer(SHIP_ID, "cooldown") "Weapons ready!"

`set_timer(id_or_obj, name, seconds=0, minutes=0)`

Start a named countdown timer on an agent.

Records the expiry tick in the agent's inventory. Use is_timer_finished or get_time_remaining to check progress.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The agent to set the timer on.	required
`name`	`str`	Unique timer name for this agent.	required
`seconds`	`int`	Duration in seconds. Defaults to 0.	`0`
`minutes`	`int`	Additional duration in minutes. Defaults to 0.	`0`

Example

set_timer(SHIP_ID, "repair", seconds=30) if is_timer_finished(SHIP_ID, "repair"): "Repairs complete!"

`start_counter(id_or_obj, name)`

Record the current sim tick as the start of a named counter.

Use get_counter_elapsed_seconds to read how many seconds have passed since the counter was started.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	Agent ID or object.	required
`name`	`str`	Counter name.	required

Example

start_counter(SHIP_ID, "docked")

later...

secs = get_counter_elapsed_seconds(SHIP_ID, "docked")

`timeout(seconds=0, minutes=0)`

Create a timeout promise measured in real application time.

Identical to delay_app. Typically passed to await comms(timeout=…) or similar constructs that accept a timeout promise.

Parameters:

Name	Type	Description	Default
`seconds`	`int`	Duration in seconds. Defaults to 0.	`0`
`minutes`	`int`	Additional duration in minutes. Defaults to 0.	`0`

Returns:

Name	Type	Description
`Delay`	`Delay`	A promise that resolves when the time has elapsed.

Example

await comms(timeout=timeout(seconds=30))

`timeout_sim(seconds=0, minutes=0)`

Create a timeout promise measured in simulation time.

Identical to delay_sim. Simulation time can be paused.

Parameters:

Name	Type	Description	Default
`seconds`	`int`	Duration in seconds. Defaults to 0.	`0`
`minutes`	`int`	Additional duration in minutes. Defaults to 0.	`0`

Returns:

Name	Type	Description
`Delay`	`Delay`	A promise that resolves when the time has elapsed.

Example

await comms(timeout=timeout_sim(minutes=2))