Does animation need to be stateful?

[pixelzoom]

Some big design questions have come up in #192 during initial instrumentation. This sim has 3 types of animation, and its not clear whether they need to be stateful.

(1) Motion of terms: Terms animate to toolboxes or plates when they are released. These animations are handled via sim-specific code (step methods) called on each frame.

(2) Terms fade out when they sum to zero. This animation is handled by PhET's twixt repo, which is not currently instrumented.

(3) Universal Operations animate to the plates in the Operations and Solve It screens, then fade out when they reach the plates. This animation is handled by PhET's twixt repo.

(4) Game reward, which is provided by vegas RewardNode, and is not currently instrumented.

Do these animations need to be stateful?

If the answer is "yes", this means that common-code work is needed, and it significantly increases the difficult of equality-explorer instrumentation.

If the answer is "no", how do we prevent someone from saving state while animation is in progress?

@samreid @zepumph @arouinfar FYI.

[pixelzoom]

I should mention that these are general issues, and decisions here will likely apply to other sims that use twixt animations and vegas RewardNode.

[pixelzoom]

There are currently 8 TODOs in the code that reference this issue:

//TODO https://github.com/phetsims/equality-explorer/issues/197

[pixelzoom]

@amanda-phet @catherinecarter and I discussed this at 11/8/2022 design meeting. Summary:

• Saving state while animating does not serve any pedagogical purpose, and is probably a mistake if it happens.
• There is currently no way to prevent the instructional designer from making this mistake. The sim does not know that it's animating, and cannot tell Studio to disable buttons (Preview, Download,...) while animating.
• If the user does save during animation, it should be pretty obvious that something is wrong when they test what they've saved. Anything that was animating will be stuck in whatever state it was in when the save occurred.
• The most practical way to address this is probably to document in Client Guide. Tell them when they should not save, give examples, and give examples of what kinds of things will look wrong.
• There are likely other sims that have this problem, but are ignoring it, or haven't thought to address it.

Further discussion is needed with @kathy-phet to come to a conclusion.

[arouinfar]

The most practical way to address this is probably to document in Client Guide.

Agreed! Note that there is now a single PhET-iO Guide shared by all sims, so documentation should be written in a general way. It has a section for Limitations to Customizing State with a list of things that aren't stateful (e.g. transient behavior) so we can add animations to the list.