feat!: New `AlternatePattern` argument for `SequenceEffect` #3322

TheMaverickProgrammer · 2024-09-24T23:01:44Z

This PR fixes math in MoveToEffect so that negative progress did not reflect the direction of the delta offset vec.
Corrected progress getter overload in SequenceEffect to correctly map to the progress when _index < 0.
Added onStart() in recede() initial condition so that effects like MoveToEffect can recalculate their initial data.
Removed unnecessary math in DurationEffectController to avoid potential negative zeros.
Introduced a new type AlternatePattern which allows users to include or exclude the last effect in the sequence when the pattern reverses. NOTE: When playing forward, the last effect is List.last, but in reverse it is List.first.
Default value is now AlternatePattern.repeatLast.
Made the TiledGame example project more aesthetically interesting.
- The camera now pans to all 4 corners WRT the bounds of the loaded map and uses the new AlternatePattern feature along with all the new fixes.

I have followed the Contributor Guide when preparing my PR.
I have updated/added tests for ALL new/updated/fixed functionality.
I have updated/added relevant documentation in docs and added dartdoc comments with ///.
I have updated/added relevant examples in examples or docs.

TO DISCUSS

I have skipped the test checkbox until I had a review and we could discuss these changes.
We may need to consider an onEnd() for Effects. Or provide onStart() with an initial progress value to calculate from.

Breaking Change?

Yes, this PR is a breaking change.
No, this PR is not a breaking change.

Related Issues

I looked but didn't immediately see anyone reporting these issues. I discovered them myself.

…the direction of the delta offset vec. Corrected progress getter overload in SequenceEffect to correctly map to the progess when _index < 0. Added onStart() in the initial conidition of ecede() so that effects like MoveEffect can recalculate their initial data. Removed unnecessary math in DurationEffectController to avoid potential negative zeros. Replaced �lternate boolean for SequenceEffect with a new type AlternatePattern which allows users to include or exlude the last effect in the sequence when the pattern reverses. Default value is now AlternatePattern.none. Updated all SequenceEffect examples and tests to reflect changes. Made the TiledGame example project more aesthetically interesting. The camera now pans to all 4 corners WRT the bounds of the loaded map and uses the new AlternatePattern feature along with all the new fixes.

…ing so that is fixed.

spydon

Good idea, it needs tests and docs though.
EDIT: Ah you already wrote that in the PR description.

examples/lib/stories/effects/sequence_effect_example.dart

spydon · 2024-09-25T05:07:30Z

packages/flame/lib/src/effects/move_to_effect.dart

@@ -40,7 +40,7 @@ class MoveToEffect extends MoveEffect {
  @override
  void apply(double progress) {
    final dProgress = progress - previousProgress;
-    target.position += _offset * dProgress;
+    target.position += _offset * dProgress.abs();


Hmm, is this really correct?

After thinking about it some more yesterday I think the issue wasn't the reflected vector itself, but rather that the direction vector was incorrect when the camera has a viewport-aware bounds behavior. This causes it to never reach its destination and so the reflective vector is incorrect. That's why taking the absolute value was ok after I added the step to recalculate the vector.

The camera won't be the only component that may never complete its effect with regards to MoveToEffect so this matter should be resolved in the PR imo.

But this will potentially overshoot the destination right? And also it won't be matching the time anymore?
If you are at 0.99 progress and the delta progress is -0.02 when the effect is going forward it should have moved 0.03 "steps", since it'll start going back again, but with this it will simply move to 1.01.

I'm not sure I'm understanding your question precisely, but it seems that you've noticed the possibility of under-fitting the expected step amounts, time-wise. Yes this does happen with the viewport-aware behavior as described (the camera cannot exceed the bounds, and therefore never arrives to its destination). ATM with the changes I've added, I have not seen any noticeable problems.

Simply put; I don't think it will always be at the expected place at each time step when abs is used, that was what I tried to describe in the last comment, the delta doesn't become correct. If it overshoots its destination it should start going back, in the cases where it is alternating.

progress will be decrementing dt units from 1.0 during the reverse phase of the alternating pattern, while previousProgress retains the progress+dt value from before. Therefore dProgress = progress - previousProgress would be negative, which we don't want to use. It's better to recalculate the starting position and use positive scalars instead.

But it'll surely overshoot the end value then?

Hi. No it never does for this effect or any as far as I can tell. The same math could have overshot in the reverse direction when dProgress was negative.

In the case that dProgress becomes negative it is supposed to go backwards. Say that the previous progress is 0.9 and it it supposed to move backwards to 0.8, then dProgress should be -0.1, not 0.1.
Try running only the the MoveToEffect with alternate: true.

Hi. A negative progress value for this effect specifically is not only unintuitive but also does not solve the MoveToEffect starting vector issue.

spydon · 2024-09-25T05:10:08Z

packages/flame/lib/src/effects/sequence_effect.dart

+enum AlternatePattern {
+  none(0),
+  includeLast(1),
+  excludeLast(2);


If infinite (or N runs) is used together with alternate, shouldn't the first also be excluded on runs that are after the first and not the last?

It already behaved this way. Only the last one was ever being repeated.

I've corrected the default pattern behavior. The alternating pattern now plays both the first and last Effect elements in the list, instead of just the last element as it did before this PR. This default behavior is AlternatePattern.repeatLast. The term "last" used here is relative to the playback direction.

To avoid playing first and last Effects twice-in-a-row when the sequence reverses, AlternatePattern.doNotRepeatLast is appropriate.

…o skip start element whendoNotRepeatLast is true and the pattern is playing in reverse.

TheMaverickProgrammer · 2024-11-05T01:42:11Z

There's still the topic to discuss: I'm in favor of providing onStart() with an initial progress value to calculate the starting conditions from since MoveEffect can be affected by bounds checks.

packages/flame_tiled/example/.gitignore

spydon · 2024-11-07T09:26:01Z

packages/flame/lib/src/effects/sequence_effect.dart

    if (alternate) {
      totalDuration *= 2;
+
+      if (alternatePattern == AlternatePattern.doNotRepeatLast) {
+        totalDuration -= effects.first.controller.duration ?? 0;


How come the first one is removed here too? 🤔

Hi. This has been explained in the PR, code comments, and here:
#3322 (comment)

spydon · 2024-11-07T09:32:04Z

packages/flame/lib/src/effects/sequence_effect.dart

@@ -136,7 +197,7 @@ class _SequenceEffectEffectController extends EffectController {
  }

  @override
-  double get progress => (_index + 1) / n;
+  double get progress => (_index < 0 ? -_index : _index + 1) / n;


Can you explain this a bit? In what cases is the _index negative? This doesn't seem like it would follow how progress works for the rest of the effects.

The way the SequenceEffect has been written for some time now is that it uses a negative _index to determine if the pattern is in its reverse phase. To be clear, I did not write it this way. This code was like this when I started this PR,

spydon · 2024-11-07T09:37:57Z

packages/flame/lib/src/effects/move_to_effect.dart

@@ -40,7 +40,7 @@ class MoveToEffect extends MoveEffect {
  @override
  void apply(double progress) {
    final dProgress = progress - previousProgress;
-    target.position += _offset * dProgress;
+    target.position += _offset * dProgress.abs();


In the case that dProgress becomes negative it is supposed to go backwards. Say that the previous progress is 0.9 and it it supposed to move backwards to 0.8, then dProgress should be -0.1, not 0.1.
Try running only the the MoveToEffect with alternate: true.

TheMaverickProgrammer · 2024-11-07T16:16:36Z

@spydon

In the case that dProgress becomes negative it is supposed to go backwards. Say that the previous progress is 0.9 and it it supposed to move backwards to 0.8, then dProgress should be -0.1, not 0.1.
Try running only the the MoveToEffect with alternate: true.

Please try running the tiled_example/lib/main.dart example with from my PR and compare it with the same example in upstream after adding the ViewportAwareBounds to the camera in the upstream version. From our conversation, this issue seems to be missed and it's crucial to understanding the problem that is being addressed with the addition to onStart() in the recede() function and using a non-negative duration value.

spydon · 2024-11-07T19:01:58Z

I'll give it a proper try when I'm back home again next week!

spydon · 2024-12-10T15:46:41Z

@TheMaverickProgrammer I haven't had the time to test it properly yet unfortunately (forgot that it was on my table 😅), but there is a test failing, could you have a look at that first?

 test/effects/sequence_effect_test.dart 271:9

TheMaverickProgrammer · 2024-12-11T04:27:49Z

@TheMaverickProgrammer I haven't had the time to test it properly yet unfortunately (forgot that it was on my table 😅), but there is a test failing, could you have a look at that first?
 test/effects/sequence_effect_test.dart 271:9

The test failing is related to the issue at hand. I have thought a lot about it and can propose a quick solution but it's not ideal: There can be a MoveTo effect and a MoveToWithCorrection effect. The latter can be used for components that may not arrive at their destination and need to be adjusted when the effect begins. This new effect would update its deltas every time onStart() is invoked (see PR for the additional callsite for onStart()) and the former effect would simply cache its delta the first time onStart() is ran. This way the test can pass and then this MoveToWithCorrection component can be used on components like the Camera when ViewportAwareBounds behavior is used.

spydon · 2024-12-11T13:16:13Z

There can be a MoveTo effect and a MoveToWithCorrection effect.

Hmm, I'm not too fond of that idea, it feels like a less clean API.
How come that it currently passes the test? I didn't think MoveToEffect had any correction built in to it, since it wasn't designed to stack with multiple effects of the same type (like MoveByEffect is)?

TheMaverickProgrammer · 2024-12-11T15:01:47Z

There can be a MoveTo effect and a MoveToWithCorrection effect.

Hmm, I'm not too fond of that idea, it feels like a less clean API. How come that it currently passes the test? I didn't think MoveToEffect had any correction built in to it, since it wasn't designed to stack with multiple effects of the same type (like MoveByEffect is)?

Because in the PR I said I added a new callsite to onStart() for effects in order to allow MoveTo effect to recalculate its starting position whenever it was unable to ensure its component arrived to its destination. This edge case happens in the camera with viewport aware bounds behavior but can potentially happen for other effects/behaviors that dictate a component's position.

TheMaverickProgrammer changed the title ~~feature!: AlternatePattern for SequenceEffect. fix: bad math in MoveToEffect.~~ feature!: AlternatePattern for SequenceEffect (and fix wrong math in MoveToEffect). Sep 24, 2024

TheMaverickProgrammer changed the title ~~feature!: AlternatePattern for SequenceEffect (and fix wrong math in MoveToEffect).~~ feat!: AlternatePattern for SequenceEffect (and fix wrong math in MoveToEffect). Sep 24, 2024

Removed unnecessary abs(). Forgot to revert recede() after local test…

dd1fc7b

…ing so that is fixed.

spydon reviewed Sep 25, 2024

View reviewed changes

spydon changed the title ~~feat!: AlternatePattern for SequenceEffect (and fix wrong math in MoveToEffect).~~ feat!: AlternatePattern for SequenceEffect (and fix wrong math in MoveToEffect) Sep 25, 2024

spydon changed the title ~~feat!: AlternatePattern for SequenceEffect (and fix wrong math in MoveToEffect)~~ feat!: New AlternatePattern argument for SequenceEffect Sep 25, 2024

TheMaverickProgrammer marked this pull request as draft September 25, 2024 18:06

TheMaverickProgrammer added 7 commits November 4, 2024 12:48

Merge branch 'main' of https://github.com/TheMaverickProgrammer/flame

d107787

Merge branch 'main' into feature/improved_sequence_effect

faa32b9

renamed enum to be clearer. Restored �lternate boolean. Added logic t…

d05e3ee

…o skip start element whendoNotRepeatLast is true and the pattern is playing in reverse.

better documentation. code cleanup.

ed63c41

comment cleanup

ece8953

restore tests

6dd88a1

linter did not recognize word 'numberline'

2ea5e9f

spydon reviewed Nov 5, 2024

View reviewed changes

packages/flame_tiled/example/.gitignore Show resolved Hide resolved

spydon reviewed Nov 7, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: New `AlternatePattern` argument for `SequenceEffect` #3322

feat!: New `AlternatePattern` argument for `SequenceEffect` #3322

TheMaverickProgrammer commented Sep 24, 2024 •

edited

Loading

spydon left a comment •

edited

Loading

spydon Sep 25, 2024

TheMaverickProgrammer Sep 25, 2024

spydon Oct 4, 2024

TheMaverickProgrammer Nov 5, 2024

spydon Nov 5, 2024

TheMaverickProgrammer Nov 6, 2024 •

edited

Loading

spydon Nov 6, 2024

TheMaverickProgrammer Nov 6, 2024 •

edited

Loading

spydon Nov 7, 2024

TheMaverickProgrammer Nov 7, 2024 •

edited

Loading

spydon Sep 25, 2024 •

edited

Loading

TheMaverickProgrammer Sep 25, 2024 •

edited

Loading

TheMaverickProgrammer Nov 5, 2024 •

edited

Loading

TheMaverickProgrammer commented Nov 5, 2024

spydon Nov 7, 2024

TheMaverickProgrammer Nov 7, 2024

spydon Nov 7, 2024

TheMaverickProgrammer Nov 7, 2024 •

edited

Loading

spydon Nov 7, 2024

TheMaverickProgrammer commented Nov 7, 2024 •

edited

Loading

spydon commented Nov 7, 2024

spydon commented Dec 10, 2024 •

edited

Loading

TheMaverickProgrammer commented Dec 11, 2024

spydon commented Dec 11, 2024

TheMaverickProgrammer commented Dec 11, 2024

feat!: New AlternatePattern argument for SequenceEffect #3322

Are you sure you want to change the base?

feat!: New AlternatePattern argument for SequenceEffect #3322

Conversation

TheMaverickProgrammer commented Sep 24, 2024 • edited Loading

TO DISCUSS

Breaking Change?

Related Issues

spydon left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TheMaverickProgrammer Nov 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TheMaverickProgrammer Nov 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TheMaverickProgrammer Nov 7, 2024 • edited Loading

Choose a reason for hiding this comment

spydon Sep 25, 2024 • edited Loading

Choose a reason for hiding this comment

TheMaverickProgrammer Sep 25, 2024 • edited Loading

Choose a reason for hiding this comment

TheMaverickProgrammer Nov 5, 2024 • edited Loading

Choose a reason for hiding this comment

TheMaverickProgrammer commented Nov 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TheMaverickProgrammer Nov 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TheMaverickProgrammer commented Nov 7, 2024 • edited Loading

spydon commented Nov 7, 2024

spydon commented Dec 10, 2024 • edited Loading

TheMaverickProgrammer commented Dec 11, 2024

spydon commented Dec 11, 2024

TheMaverickProgrammer commented Dec 11, 2024

feat!: New `AlternatePattern` argument for `SequenceEffect` #3322

feat!: New `AlternatePattern` argument for `SequenceEffect` #3322

TheMaverickProgrammer commented Sep 24, 2024 •

edited

Loading

spydon left a comment •

edited

Loading

TheMaverickProgrammer Nov 6, 2024 •

edited

Loading

TheMaverickProgrammer Nov 6, 2024 •

edited

Loading

TheMaverickProgrammer Nov 7, 2024 •

edited

Loading

spydon Sep 25, 2024 •

edited

Loading

TheMaverickProgrammer Sep 25, 2024 •

edited

Loading

TheMaverickProgrammer Nov 5, 2024 •

edited

Loading

TheMaverickProgrammer Nov 7, 2024 •

edited

Loading

TheMaverickProgrammer commented Nov 7, 2024 •

edited

Loading

spydon commented Dec 10, 2024 •

edited

Loading