Add a ProgrammaticTimer class, and generalize Timer functionalities

[fenix-hub]

Before making an issue out of this, since I'm not that much social and I don't have a real implementation for this yet, even though I'd really like to contribute and provide one (and I will, if this goes well), I'd like to open a discussion about this topic: ProgrammaticTimers.

---

Timers are one of the most used and useful functionalities in programming languages and environments, and I'm personally using tons of them in several projects, from little games to generalist apps and even utility softwares.
They allow to run custom schedules in a very simple way thanks to the Godot Engine signaling system, which feels more clean to other programming/scripting languages like Timers and TimerTasks in Java or NodeJS timers/schedules.
However, I've always felt like Timers in Godot don't have that much elasticity and usability they deserve to have, moreover in a scripting language like GDScript, when one needs to setup and use them programmatically. The reason is pretty evident and understandable, since Timers must be handled from the SceneTree gameloop, so the only two options are:

1. creating one manually from a script, "configure" it and add it to the Scene
2. creating one from the SceneTree.create_timer utility method (but this will be a simple one-shot timer)

Either way, we would always end up with a one-shot or an infinite timer. But why not having an intermediate (and, imho, a more theoretically correct one) option? This could be a Scheduled timer, or Fixed, or Rated timer, as you may prefer, which is:

A Timer that expires a fixed (or rated) amount of times

It would mean to have a Timer which can be configured to emit the timeout signal a fixed, configured amount of times, and then just stops.

func _ready():
  var timer: Timer = Timer.new()
  timer.repeat = 3 # repeat the timer only 3 times, then don't count down anymore
  [...]
  add_child(timer)

Eventually, the repeat index could be returned in the signal already fired by a Timer:

[...]
# in the `Timer` class
signal timeout(repeat_idx)

[...]
# in a class connecting the `timeout` signal on a timer, as the previous snippet was illustrating

func _timeout(repeat_idx: int) -> void:
  print("Timer repetition is %d" % repeat_idx)

 # "Timer repetition is 1"
 # "Timer repetition is 2"
 # "Timer repetition is 3"

So, the current Timer could be generalized to such Timer that:
a) for one-shot, the .repeat property is 1 by default
b) for infinite or looping, the .repeat property could be -1 (if we want to create an exclusion condition through a check statement after each increment of the repeat parameter) or either 0 (if we want to create an exclusion condition through a check statement before an increment of the repeat parameter, keeping it 0)

But you can already do this by simply adding something like this:

var repeats: int = 3
var curr_repeats: int = 0

var timer: Timer

func _ready():
  timer = Timer.new()
  timer.timeout.connect(_on_timeout)
  [...]
  add_child(timer)
  
func _on_timeout():
  curr_repeats += 1
  if curr_repeats >= repeats:
    timer.queue_free()
    # or `timer.stop()` /  `timer.paused = true` if we want to use it later?

Yes but the difference is pretty evident ( a. less code to write, less variables to handle, b. the repeat is a property of the timer itself, and should be treated as such - not accessible/editable directly during execution as any other variable in the same scope). Furthermore...
I was previously referring to a ProgrammaticTimer, and the nature of a new possible timer to be programmatic.
Allow me to be not-so precise on the semantics: by programmatic I don't mean to make the Timer class something that could be created/instantiated programmatically (which is something that is almost already possible, but could be further improved with a TimerService class which exposes some methods to return different type of configured timers, in order to call the method once and add the returned timer in the scene); but I mean a Timer that could be configured and scheduled further more than the current Timer, still having the Timer as a class (inheriting from ProgrammaticTimer eventually).
The Fixed/Scheduled/Rated functionality I illustrated before was just one case of possible generalization of the Timers that could easily - with very little effort on the C++ side - already improve the usability.
But some others could be:

• autodisposable: bool property, which is when a Timer will automatically disposed (aka. queue_free()d) when no longer needed (one-shot and multi-shot cases). Would be default: false for Timer
• delay: float property, which is the amount of time in seconds after which the Timer will start counting down, properly affecting the "one-shot" case before the first and only timeout, and the "multi-shot"/"scheduled" and "infinite"/"looping" cases after each repetition. Would be default: .0 for Timer

Also, some more methods of the ProgrammaticTimer, or even better a TimerService exposing some methods as a Factory pattern:

• schedule(wait_time: float, repeats: int, delay: float), will return a new ProgrammaticTimer instance with those property properly configured, in order to add it to the scene and connect to its signal.

func _ready() -> void:
  var timer: ProgrammaticTimer = TimerService.schedule(1.0, 5, 0.3)
  timer.timeout.connect(_on_timeout)
  add_child(timer)
  # will add, and then start, a Timer that will fire the `timeout` event each (1.0 + 0.3) seconds only 5 times, then autodispose

• from_iso(iso8601_string: String) will return a new ProgrammaticTimer instance, properly configured as the previous method, but parsing an ISO8601 String with Repeating Intervals, since it is a standardized way of representing Date+Time intervals with repetitions. If we want to keep the Timer simple, Years, Months, Days, Hours and Minutes could be converted to seconds, precisely accounting the memory limits

func _ready() -> void:
  var timer: ProgrammaticTimer = TimerService.from_iso("R5/PT1.3S")
  timer.timeout.connect(_on_timeout)
  add_child(timer)
  # will do the same as the snippet before, but using an iso8601 string

So, hoping that the functionalities are clearer, about the naming:
a. A ScheduledTimer sounds wrong to name, since a Timer is already Scheduled by nature, and any other reference to a "Schedule" (which is - an activity executed in a timed environment and under precise rules) could be misleading.
b. A FixedTimer could be a correct naming, except for the fact that being "fixed" is only one of the functionalities of such timer, and does not define the timer itself completely
c. Just Timer, accepting the fact that the Timer class should expose such new functionalities, and eventually have a TimerService or the SceneTree itself exposing factory methods to create timers "programmatically".
I'm open for further explainations and discussions.
Thanks everyone.

[Calinou]

I feel this adds a lot of complexity for something that won't be used often. Replacing oneshot with a max_repeats property that can be set to 0 (to get the same behavior as oneshot = true) is the furthest I'd go.

[fenix-hub]

What part is concerning you the most in terms of complexity?

[Calinou]

What part is concerning you the most in terms of complexity?

The ProgrammaticTimer thing seems overly complex to me. Parsing strings at run-time should be avoided when possible for performance reasons (especially for something that may be called often during gameplay), and it's also error-prone as you can only get run-time errors as opposed to compile-time errors.

People have been asking for years to make GDScript rely less on strings, so let's not add more strings again 🙂

[fenix-hub]

Yes I agree, the string parsing was just an overthinking, and something that could be just provided by a script/plugin.

What about the eventual schedule() method? I was thinking that it could be just replaced by improving the create_timer method on the sceneTree: SceneTree.create_timer(time_sec: float, delay: float = 0.0, max_repeats: int = 1, pause_mode_process: bool = false),
so the autodispose property wouldn't even be needed.