Flecs: Timer
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.1 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Timer
C API » Addons

Run systems at a time interval. More...

Collaboration diagram for Timer:

## Classes
struct | EcsTimer
| Component used for one shot/interval timer functionality. More...
struct | EcsRateFilter
| Apply a rate filter to a tick source. More...

## Typedefs
typedef struct EcsTimer | EcsTimer
| Component used for one shot/interval timer functionality.
typedef struct EcsRateFilter | EcsRateFilter
| Apply a rate filter to a tick source.

## Functions
FLECS_API ecs_entity_t | ecs_set_timeout (ecs_world_t *world, ecs_entity_t tick_source, ecs_ftime_t timeout)
| Set timer timeout.
FLECS_API ecs_ftime_t | ecs_get_timeout (const ecs_world_t *world, ecs_entity_t tick_source)
| Get current timeout value for the specified timer.
FLECS_API ecs_entity_t | ecs_set_interval (ecs_world_t *world, ecs_entity_t tick_source, ecs_ftime_t interval)
| Set timer interval.
FLECS_API ecs_ftime_t | ecs_get_interval (const ecs_world_t *world, ecs_entity_t tick_source)
| Get current interval value for the specified timer.
FLECS_API void | ecs_start_timer (ecs_world_t *world, ecs_entity_t tick_source)
| Start timer.
FLECS_API void | ecs_stop_timer (ecs_world_t *world, ecs_entity_t tick_source)
| Stop timer This operation stops a timer from triggering.
FLECS_API void | ecs_reset_timer (ecs_world_t *world, ecs_entity_t tick_source)
| Reset time value of timer to 0.
FLECS_API void | ecs_randomize_timers (ecs_world_t *world)
| Enable randomizing initial time value of timers.
FLECS_API ecs_entity_t | ecs_set_rate (ecs_world_t *world, ecs_entity_t tick_source, int32_t rate, ecs_entity_t source)
| Set rate filter.
FLECS_API void | ecs_set_tick_source (ecs_world_t *world, ecs_entity_t system, ecs_entity_t tick_source)
| Assign tick source to system.
FLECS_API void | FlecsTimerImport (ecs_world_t *world)
| Timer module import function.

## Detailed Description

Run systems at a time interval.

## Macro Definition Documentation

## ◆ FLECS_TIMER_H

#define FLECS_TIMER_H

Definition at line 28 of file timer.h.

## Function Documentation

## ◆ ecs_get_interval()

FLECS_API ecs_ftime_t ecs_get_interval | ( | const ecs_world_t * | world,
|  | ecs_entity_t | tick_source )

Get current interval value for the specified timer.

This operation returns the value set by ecs_set_interval(). If the entity is not a timer, the operation will return 0.

Parameters

  world | The world.
  tick_source | The timer for which to set the interval.

Returns
  The current interval value, or 0 if no timer is active.

## ◆ ecs_get_timeout()

FLECS_API ecs_ftime_t ecs_get_timeout | ( | const ecs_world_t * | world,
|  | ecs_entity_t | tick_source )

Get current timeout value for the specified timer.

This operation returns the value set by ecs_set_timeout(). If no timer is active for this entity, the operation returns 0.

After the timeout expires the EcsTimer component is removed from the entity. This means that if ecs_get_timeout() is invoked after the timer is expired, the operation will return 0.

The timer is synchronous, and is incremented each frame by delta_time.

The tick_source entity will be a tick source after this operation. Tick sources can be read by getting the EcsTickSource component. If the tick source ticked this frame, the 'tick' member will be true. When the tick source is a system, the system will tick when the timer ticks.

Parameters

  world | The world.
  tick_source | The timer.

Returns
  The current timeout value, or 0 if no timer is active.

## ◆ ecs_randomize_timers()

FLECS_API void ecs_randomize_timers | ( | ecs_world_t * | world | ) |

Enable randomizing initial time value of timers.

Initializes timers with a random time value, which can improve scheduling as systems/timers for the same interval don't all happen on the same tick.

Parameters

  world | The world.

## ◆ ecs_reset_timer()

FLECS_API void ecs_reset_timer | ( | ecs_world_t * | world,
|  | ecs_entity_t | tick_source )

Reset time value of timer to 0.

This operation resets the timer value to 0.

Parameters

  world | The world.
  tick_source | The timer to reset.

## ◆ ecs_set_interval()

FLECS_API ecs_entity_t ecs_set_interval | ( | ecs_world_t * | world,
|  | ecs_entity_t | tick_source,
|  | ecs_ftime_t | interval )

Set timer interval.

This operation will continuously invoke systems associated with the timer after the interval period expires. If the entity contains an existing timer, the interval value will be reset.

The timer is synchronous, and is incremented each frame by delta_time.

The tick_source entity will be a tick source after this operation. Tick sources can be read by getting the EcsTickSource component. If the tick source ticked this frame, the 'tick' member will be true. When the tick source is a system, the system will tick when the timer ticks.

Parameters

  world | The world.
  tick_source | The timer for which to set the interval (0 to create one).
  interval | The interval value.

Returns
  The timer entity.

## ◆ ecs_set_rate()

FLECS_API ecs_entity_t ecs_set_rate | ( | ecs_world_t * | world,
|  | ecs_entity_t | tick_source,
|  | int32_t | rate,
|  | ecs_entity_t | source )

Set rate filter.

This operation initializes a rate filter. Rate filters sample tick sources and tick at a configurable multiple. A rate filter is a tick source itself, which means that rate filters can be chained.

Rate filters enable deterministic system execution which cannot be achieved with interval timers alone. For example, if timer A has interval 2.0 and timer B has interval 4.0, it is not guaranteed that B will tick at exactly twice the multiple of A. This is partly due to the indeterministic nature of timers, and partly due to floating point rounding errors.

Rate filters can be combined with timers (or other rate filters) to ensure that a system ticks at an exact multiple of a tick source (which can be another system). If a rate filter is created with a rate of 1 it will tick at the exact same time as its source.

If no tick source is provided, the rate filter will use the frame tick as source, which corresponds with the number of times ecs_progress() is called.

The tick_source entity will be a tick source after this operation. Tick sources can be read by getting the EcsTickSource component. If the tick source ticked this frame, the 'tick' member will be true. When the tick source is a system, the system will tick when the timer ticks.

Parameters

  world | The world.
  tick_source | The rate filter entity (0 to create one).
  rate | The rate to apply.
  source | The tick source (0 to use frames)

Returns
  The filter entity.

## ◆ ecs_set_tick_source()

FLECS_API void ecs_set_tick_source | ( | ecs_world_t * | world,
|  | ecs_entity_t | system,
|  | ecs_entity_t | tick_source )

Assign tick source to system.

Systems can be their own tick source, which can be any of the tick sources (one shot timers, interval times and rate filters). However, in some cases it is must be guaranteed that different systems tick on the exact same frame.

This cannot be guaranteed by giving two systems the same interval/rate filter as it is possible that one system is (for example) disabled, which would cause the systems to go out of sync. To provide these guarantees, systems must use the same tick source, which is what this operation enables.

When two systems share the same tick source, it is guaranteed that they tick in the same frame. The provided tick source can be any entity that is a tick source, including another system. If the provided entity is not a tick source the system will not be ran.

To disassociate a tick source from a system, use 0 for the tick_source parameter.

Parameters

  world | The world.
  system | The system to associate with the timer.
  tick_source | The tick source to associate with the system.

## ◆ ecs_set_timeout()

FLECS_API ecs_entity_t ecs_set_timeout | ( | ecs_world_t * | world,
|  | ecs_entity_t | tick_source,
|  | ecs_ftime_t | timeout )

Set timer timeout.

This operation executes any systems associated with the timer after the specified timeout value. If the entity contains an existing timer, the timeout value will be reset. The timer can be started and stopped with ecs_start_timer() and ecs_stop_timer().

The timer is synchronous, and is incremented each frame by delta_time.

The tick_source entity will be a tick source after this operation. Tick sources can be read by getting the EcsTickSource component. If the tick source ticked this frame, the 'tick' member will be true. When the tick source is a system, the system will tick when the timer ticks.

Parameters

  world | The world.
  tick_source | The timer for which to set the timeout (0 to create one).
  timeout | The timeout value.

Returns
  The timer entity.

## ◆ ecs_start_timer()

FLECS_API void ecs_start_timer | ( | ecs_world_t * | world,
|  | ecs_entity_t | tick_source )

Start timer.

This operation resets the timer and starts it with the specified timeout.

Parameters

  world | The world.
  tick_source | The timer to start.

## ◆ ecs_stop_timer()

FLECS_API void ecs_stop_timer | ( | ecs_world_t * | world,
|  | ecs_entity_t | tick_source )

Stop timer This operation stops a timer from triggering.

Parameters

  world | The world.
  tick_source | The timer to stop.

## ◆ FlecsTimerImport()

FLECS_API void FlecsTimerImport | ( | ecs_world_t * | world | ) |

Timer module import function.

Usage:

ECS_IMPORT(world, FlecsTimer)
ECS_IMPORT
#define ECS_IMPORT(world, id)
Wrapper around ecs_import().
Definition module.h:119

Parameters

  world | The world.