Improve Timer ergonomics

[CleanCut]

I often use timers to drive animation by converting it to a percentage. The fact that elapsed could exceed duration for non-repeating timers means that I had to check for that everywhere I used them, or the percentage could go negative (which can do various unexpected things, such as flip vector direction). This is a paper cut for me, so I made this PR which:

• Clamps elapsed to the range [0.0, duration]
• Adds tests
• Adds some documentation
• Adds two convenience methods: (percent and percent_left)
  • I was on the fence whether to include these methods in the PR due to the fact that it assumes keeping the size of Timer small is more important than the speed of the calculation. A more speed-optimized approach would store the inverse of duration and do multiplication. Is there a general principle we're following that could inform the approach? Or should we leave the methods out altogether?

[ambeeeeee]

I like how it replaces the fancy logic with easier to understand at-a-glance logic

[CleanCut]

Here's an example from a showcase I'm making that demonstrates using these changes to directly power a shrinking death animation and a punching boxing glove animation. You need to have at least one gamepad connected to your computer to try it out (controls are gamepad-only).

[cart]

Ooh I love the look of that boxing game.

I was on the fence whether to include these methods in the PR due to the fact that it assumes keeping the size of Timer small is more important than the speed of the calculation. A more speed-optimized approach would store the inverse of duration and do multiplication. Is there a general principle we're following that could inform the approach? Or should we leave the methods out altogether?

In this case I prefer the clarity of division over storing / multiplying by the inverse.

Using percentages seems like a common enough requirement for timers that I think its worth including, largely because the function name helps encode intent.

I think this is good to go!

[cart]

Semi-relevant idea that I'd love to discuss with yall (I'm pulling in @amberkowalski because they're also working on timers):

I think it might be a good idea to remove the "auto ticking" timer system.

• Resource-based timers don't auto-tick
• Component-based timers only auto-tick if they aren't wrapped. But I think having multiple timers with different "names" will be common (see @CleanCut's boxing example).

Its a bit inconsistent that only raw Timer components auto-tick and theres no good way to force all timers to tick. I think I'd rather just make ticking explicit everywhere for simplicity.

[cart]

@amberkowalski if we make ticking explicit everywhere, maybe we don't need built in pausing? users could "pause" by not ticking where relevant according to their own context-specific logic.

[CleanCut]

My two cents:

• Making ticking of timers always explicit seems like the sanest option. I didn't even think to look for auto-ticking, and would have been surprised had I run into it. Including an example of how to tick your timer in the docs for Timer should be sufficient.
• I would welcome pause functionality -- it is a useful and typical feature to have built-in to the timers. In its absence, a user who needs to pause is faced with either tightly coupling the pause logic to the ticking logic, or wrapping/reimplementing the Timer with pause logic.

In this case I prefer the clarity of division over storing / multiplying by the inverse.

Using percentages seems like a common enough requirement for timers that I think its worth including, largely because the function name helps encode intent.

🥳 🎉

[cart]

I would welcome pause functionality -- it is a useful and typical feature to have built-in to the timers. In its absence, a user who needs to pause is faced with either tightly coupling the pause logic to the ticking logic, or wrapping/reimplementing the Timer with pause logic.

Good enough for me. @amberkowalski, if you update your pr to account for the changes in this pr I think it'll be merge-ready!

[CleanCut]

* Making ticking of timers always explicit seems like the sanest option. I didn't even think to look for auto-ticking, and would have been surprised had I run into it.  Including an example of how to tick your timer in the docs for `Timer` should be sufficient.

Having said that, having a way to opt-in to auto-ticking could be very convenient. 🤔 But I think I'm just feature creeping now. 😆

[smokku]

Having said that, having a way to opt-in to auto-ticking could be very convenient. But I think I'm just feature creeping now.

Would providing a system that auto-ticks all timers and an example how to include it into the App, count as opt-in?

[cart]

Haha I'm very curious how you would do this across wrapper types without adding some sort of internal shared state

[smokku]

Nyah. Just for the not wrapped ones - like it works now.

We could use the example to put a note reminding users that it ticks only not wrapped Timers and if you want to tick a wrapped one, you need to do it manually.