Added a Loop tween to Tweens factory class. Supports looping by count…

[Ali-RS]

… or duration.

[Ali-RS]

I noticed there is an edge case using modulo. For example in the below case:

Tween countingLoop = Tweens.loopCount(3, Tweens.delay(1), Tweens.callMethod(this, "countingLoop"));

the call method will never run because in t % delegateLength the result will not include delegateLength itself. So delegate tween will never get a chance to complete before it restarts.

@pspeed42 do you have any idea?

[Ali-RS]

Another question!

Suppose this example:

Tween countingLoop = Tweens.loopCount(3, Tweens.callMethod(this, "countingLoop"));

the length of delegate tween is 0. Should this be considered a valid input or should it throw an exception saying duration can not be 0? What is the expected behavior here?

[Ali-RS]

I noticed there is an edge case using modulo

I found an alternative way that bypasses the module problem. Before I commit that I would like everyone to take a look at it:

private static class Loop implements Tween, ContainsTweens {

        private final Tween[] delegate = new Tween[1];
        private final double length;
        private int numLoopDone;

        public Loop(Tween delegate, double length) {
            if (length <= 0) {
                throw new IllegalArgumentException("Loop length must be greater than 0");
            }

            this.delegate[0] = delegate;
            this.length = length;
        }

        @Override
        public double getLength() {
            return length;
        }

        @Override
        public Tween[] getTweens() {
            return delegate;
        }

        @Override
        public boolean interpolate(double t) {
            if (t < 0) {
                return true;
            }

            double loopTime;
            double delegateLength = delegate[0].getLength();
            if (delegateLength > 0) {
                loopTime = t - (numLoopDone * delegateLength);
            } else {
                loopTime = delegateLength;
            }

            boolean running = delegate[0].interpolate(loopTime);
            if (!running) {
                numLoopDone++;
            }

            return t < length;

            // The reason I am not using modulo time (t % delegateLength) to determine loop time
            // is because using modulo the result will not include `delegateLength` itself.
            // So delegate tween will never get a chance to complete before it restarts.
            // For example consider this test:
            // Tweens.loopCount(3, Tweens.delay(1), Tweens.callMethod(this, "someMethod"));
            // Here the call method tween would never run if I used modulo time. - Ali-RS:2022-8-19
        }

        @Override
        public String toString() {
            return getClass().getSimpleName() + "[delegate=" + delegate[0] + ", length=" + length + "]";
        }
    }

[pspeed42]

Yeah, looping is not as straight forward as one might originally think when pass 1's 'length' is the same as pass 2's '0'.

Think about it this way, what would happen if you put those two sequences together into one parent sequence? Would the first "someMethod" always get called? ...I think it would because sequence should be keeping track of the last time to the current time and advance everything. Loop will have to do similar.

[pspeed42]

And another fun part of tweens is that we let them run forwards or backwards in time. So any loop-edge detection needs to go both ways.

if( t >= length ) catch up delegate forward
if( t < 0 ) catch up delegate backwards

...both of which would depend on what the last 't' was.

[Ali-RS]

Loop will have to do similar.

Sorry, not sure I am understanding it right! Are you saying that fast-forwarding a loop should try to interpolate the loops left behind as well? For example, let's say I want to loop a tween 3 times and the tween length is 1 second. So it will take 3 seconds to run in regular cases but if I fast forward it 2 seconds it will only do one loop in my implementation and will leave the last two loops behind. Are you saying that it should try to run those first two loops as well?

[pspeed42]

I mean, technically, yes. I could probably even contrive some examples where it matters though I don't know how common it would be. Thinking of parallel tweens where one is a loop of one second and the other is a loop of five seconds and they both moving something forward. If you jump 4 seconds and don't run the 1 second loop enough times then something might not match up anymore. (Admittedly this is a squishy way to create a set of animations.)

To be honest, I haven't drilled much into this problem or your solution. I'm just pointing out the how sequence deals with its children and making sure they always see their 'length' can be used as a guide for how to deal with the child of a loop also.

And that it should work in both directions because so far JME allows reversing.

If loop(child) ends up behaving the same as sequence(child, child, child, child, child, etc.) then you're probably doing things right.

[Ali-RS]

Got that, I agree with you, will try to redesign it in the same fashion a sequence works. Thank you so much for helping.

[Ali-RS]

Ok, updated it with the new design. Basically it is a copy-paste from Sequence tween.

Regarding t<0, time won't be negative, AnimLayer will wrap negative times (speed < 0) to the [0, length) range using modulo. And yes we have the modulo problem there as well which will cause a tween not fully complete:(

jmonkeyengine/jme3-core/src/main/java/com/jme3/anim/AnimLayer.java

Lines 201 to 205 in f0b7a96

	// wrap negative times to the [0, length] range:
	if (time < 0.0) {
	double length = action.getLength();
	time = (time % length + length) % length;
	}

[Ali-RS]

Yeah, looping is not as straight forward as one might originally think when pass 1's 'length' is the same as pass 2's '0'.

I noticed it produces a small 1 frame glitch when I used this to loop BlendAction. I found out it is because that action.interpolate(length) and action.interpolate(0) are running in the same frame on the same action. I noticed when I add a one-frame space the glitch goes away. Should there be a one-frame space between those calls?

[pspeed42]

I'm probably not the one to ask because I've never been able to get a looping animation to work without a single-frame hitch even before.

[Ali-RS]

I mean generally speaking it does not make sense to render the last and the first frame of the animation at the same time. One of the frames will be lost and will not be displayed.

[Ali-RS]

Adding this at the end of the while loop fixed the issue.

                if (t - baseTime < delegate[0].getLength()) {
                    // Finished skipping completed loops, continue the new loop
                    // from the next frame.
                    break;
                }

this is how the while loop looks:

            // Skip any that are done
            while (!delegate[0].interpolate(t - baseTime)) {
                // Time to go to the next loop
                baseTime += delegate[0].getLength();
                current++;
                if (current >= loopCount) {
                    return false;
                }

                if (t - baseTime < delegate[0].getLength()) {
                    // Finished skipping completed loops, continue the new loop
                    // from the next frame.
                    break;
                }
            }

Inside the while, it will skip all finished loops in the same frame, and when it detects that there is no more loop to skip it will continue to the next loop from the next frame.

Please let me know if you think otherwise.

[Ali-RS]

The other way is to use an if statement instead of while so it will skip just one loop at a time.
Let me know if you prefer this.

[pspeed42]

Cool you got it working. I'm going to ramble for a second.

I was thinking about one of my earlier statements about t=0 being the same as t=1... and upon reflection, maybe that sort of shouldn't be true in the general case. Except when we think of 0 and 1 like boundaries.

Loops are weird. And since I've never gotten regular animation looping working, I can't say for sure if JME is handling it correctly or not. t=0 should be the first frame. t=1 should be the last frame... where last frame != first frame.

Then I think about a tween that moves and object from point A to point B. t=0 means the object is at point A. t=1 means the object is at point B. I need to reach 1 to be right at B.

But if I chain another tween from B back to A, that transition from one tween to another is a little weird.

It's kind of like texture coordinates. We rarely hit even boundaries, we're always in the middle.

So t moves along at some pace, forwards or backwards and we sample where we want to be. The problem comes when we delegate to children and they won't know that we crossed a boundary... so we have to force give them the 0 or the 1. (Maybe we went from 0.8 to 1.1 and so will switch to the next tween but the old tween still needs to see its 1... or it might miss something. As the decorator, we don't know.) And maybe in that case, we need to be honest with the child and send it the 1.1... let it clamp or not. But then if it's looping it will start its next loop when it shouldn't.

What a mathematical mess. If you have something working then I defer to you at this point. I feel like there is a hole and we just keep working around it.

[pspeed42]

And probably ignore all of that. Thinking about it as I walked away most things are fine. t comes like a heartbeat and it's fine to catch up the 'in between stuff' because ultimately we end up where we need to be when 't' finally resolves itself. Even in the A -> B -> A case I talked about. 't' itself may never hit 1.0 but we still need to pass it to the first tween and then we'll continue on. That kind of animation will be continuous and no weird hitches.

I'm pretty well convinced that there is a bug with how tweens interact with the skinned animation. t=0 and t=1 should both be the same frame for things to work properly. (So I was 100% wrong about that above.) Because there is no between 1 and 0. 1 is the loop. I don't know if the code works that way or not.

Also, I feel like the thing that automatically blends from one pose to another is independent of any tween/action 't' but I can't prove it.

Edit: and I'm 3 hours overdue for bed so I may come back in the morning and see that all of this is crazy... but I know my previous response is bonkers. This one I can at least prove on paper the first parts. :)

[Ali-RS]

Thanks for the input. Further investigating, I noticed using the loop tween for regular ClipAction does not have this issue so I believe that the Loop tween works fine and I guess it is something specific to BlendAction that does not like about Loop tween calling the interpolate method twice in a single frame at the loop end.

(I am working on improving BlendAction to support smart stretching, and I need to use a loop tween for this. I might end up creating a customized loop tween (using modulo) for this case. I will make a forum topic about this improvement soon)

[Ali-RS]

Unless there's substantial discussion, I plan to integrate this in about 24 hours.