APIs to enable custom tickers

[felthy]

Potential solve for #39:

• New exports from Theatre.core in both bundles:
  • disableDefaultTicker(): disables the default core ticker, so you can schedule ticks yourself
  • enableDefaultTicker(): re-enables the default core ticker
  • ticker: the core ticker, so you can call ticker.tick(time) from your scheduler
• Equivalents also added to Theatre.studio for the studio ticker
• Export Ticker from Theatre.core, and support supplying custom ticker to getProject() and studio.initialize()

[CLAassistant]

All committers have signed the CLA.

[AriaMinaei]

Hey @felthy, thanks for the PR!

I've been thinking about this feature. One thing our current setup is not accounting for is not running ticker.time() when there is nothing to update on the screen, especially when the tab is supposed to be idle. @ivanreese mentioned that this is important for preserving battery-life.

Because of that, it's better we hold off on this feature until we get an API that accounts for the idle state.

[felthy]

Hi @AriaMinaei, thanks for reviewing this, and thanks for putting out such a great library!

I don’t think that’s a concern for this PR, for a few reasons:

• If I choose to use disableDefaultTicker(), then it becomes my responsibility to call ticker.time() or not. Consider how theatre.is could help me decide; it could expose an additional method (say, ticker.required()) for me to call. But if I’m calling that, theatre.js could just as well perform that check itself inside ticker.time(). Therefore the additional api is not required.
• If I’m using the default behavior, then theatre.js is responsible, so how theatre.js handles it internally has no bearing on this new API.
• In the latter case, theatre.js is correctly using requestAnimationFrame(), which allows the browser to throttle or halt callbacks when the tab is inactive, or for any other reason.

What do you think?

We’re already using this at Active Theory so we can schedule theatre.js’ updates within our renderer’s scheduler. We also use it to enable more advanced effects like blending between two positions on the same sequence.

[vezwork]

Update: we are actively discussing this internally. We are considering making fundamental changes to the ticker API, so we want to keep this PR open until we figure that out.

Thanks @felthy for the great explanation and comments and thanks to both @felthy and @donmccurdy for the discussion.

[AndrewPrifer]

I have an alternative solution here: https://github.com/theatre-js/theatre/pull/230, curious about all your opinions @felthy @donmccurdy.

[vercel[bot]]

@felthy is attempting to deploy a commit to the Theatrejs Team on Vercel.

A member of the Team first needs to authorize it.

[felthy]

An important use case for us is flushing animation updates synchronously on demand (discussed in more detail in this comment).

When there are multiple active projects, flushing updates for a single project must not affect other projects.

To support this use case, I've exposed the Ticker constructor so that user code can create one Ticker per project:

ticker = new Theatre.core.Ticker();
project = Theatre.core.getProject(name, { state: savedState, ticker });
// ... to flush animation updates for this project:
ticker.tick()

[AriaMinaei]

After a few iterations (#230 and #374) this PR is merged via d6498585295962c55a6d412e74ad7f65af86adb7. Will add to the release notes. Thank you @felthy!