Parallel actions

[chrisk-7777]

Hello 👋 - awesome engine!

I've been trialing porting a few projects across and really enjoying it so far.

One part has me a bit stumped. Is it possible to have actions operate in parallel?
In the following example, the Actor will be knocked back 100px then return to the original position.

  async takeDamage(): Promise<void> {
    this.actions.clearActions();
    await this.actions
      .moveBy(vec(100, 0), 500)
      .moveBy(vec(-100, 0), 500)
      .toPromise();
  }

However, if I want to also fade the Actor at the same time, is that possible with the current API?
(*Edit: I'm just using fade as an arbitrary example, it could be move, flash, etc)

Something like:

  async takeDamage(): Promise<void> {
    this.actions.clearActions();
    await this.actions
      .moveBy(vec(100, 0), 500)
      .moveBy(vec(-100, 0), 500)
      .fade(0, 2000, 0) // where the third argument is the absolute offset - ie: the start of the "timeline"
      .toPromise();
  }

I know this is potentially a hugggggge can of worms.

The best example I know of is https://greensock.com/docs/v3/GSAP/Timeline , specifically the position parameter.

Alternatively, is using an external tween engine on top of Excalibur an option? GSAP can technically tween any object value, the only downside I could imagine is GSAP's internal ticker is not in sync with Excalibur. But, maybe this is "ok" as long as there is zero expectation that the Actors under the "influence" of GSAP are not physics driven

[eonarheim]

Hi @chrisk-7777

Thanks for the kind words, glad you are enjoying excalibur so far!

Parallel actions are something we've wanted for a while and recently just implemented and merged! #2322 These bits are pretty fresh so any feedback is very welcome.

This feature is only available in the npm alpha packages at the moment, 0.27.0-alpha.472 should have the latest build.

With the parallel actions alpha you might do something like this (One warning about async/await with `toPromise(), it will block until the action is complete so you might want to use the callback form depending on what you're doing):

class MyActor extends ex.Actor {
  constructor() {
    super({
      x: 50,
      y: 50,
      width: 100,
      height: 100,
      color: ex.Color.Green
    });
  }

  async takeDamage(): Promise<void> {
    const knockBackSequence = new ex.ActionSequence(this, ctx => {
      ctx.moveBy(ex.vec(100, 0), 500)
      ctx.moveBy(ex.vec(-100, 0), 500)
    });
    
    const fadeSequence = new ex.ActionSequence(this, ctx => {
      // ctx.delay(100); // optionally delay 100 milliseconds
      ctx.fade(0, 1000);
    });
    const parallel = new ex.ParallelActions([knockBackSequence, fadeSequence]);
    // oops runAction() doesn't return the ActionContext will fix soon
    this.actions.runAction(parallel);
    await this.actions.toPromise();
  }
}

var myActor = new MyActor();
game.add(myActor);
myActor.takeDamage();

Timelines

Wow greensock is pretty cool! I'll need to check it out! The timelines idea in their docs is very interesting, potentially for excalibur.

External tweening

To your question about an external tweening engine, it might be possible! I'd say you're right on the mark with the excalibur clock, but it might be okay as long as the Actor in question isn't being actively managed by any actions/collisions/velocity/acceleration/etc that would fight with the external tween. I'd be really interested to hear your findings about using an external tween.

[chrisk-7777]

Wow, what fantastic timing. That's great, I'll checkout the latest and give it a spin and let you know if I hit any issues.

I'll also report back with any findings on the external tweening.

Thanks for your help 👍

[chrisk-7777]

Thanks again @eonarheim . I wanted to loop back on the findings about using the external tween engine.

It actually worked quite well, with the full disclaimer that I'm tweening actors outside of any kind of physics. Basically just positions, rotations, and even tint (btw - thanks for adding tint a few days ago!)

A simple tween with gsap + excalibur:

A few notes:

• I'm still learning excaliburs animation system, so I might be misusing .reset() + .graphics.use()
• gsap then() just converts it into a promise
• leap + return are small custom methods I tacked on to gsap's timeline to reduce some boiler plate

  private async attackAnimation(targetPosition: Vector): Promise<void> {
    return gsap
      .timeline()
      .leap(this, { x: targetPosition.x + 30, y: targetPosition.y })
      .wait({}, { duration: 0.1 })
      .call(() => {
        this.animations.attack.reset();
        this.graphics.use(this.animations.attack);
        this.weapon.swing();
        this.scene.camera.shake(3, 3, 500);
      })
      .wait({}, { duration: 0.4 })
      .call(() => {
        this.weapon.reset();
        this.graphics.use(this.animations.walk);
      })
      .return(this, { x: 200, y: 100 })
      .then();
  }

Tweening a sprite tint

This is a bit more advanced, but gsap can tween colors. Typically this applies to a DOM element, but I'm passing it a POJO and then hooking into the update callback to update the sprite tint.

It's a little more verbose, but still works well imo. I could probably clean it up by saving out some of the timelines like the gyrate.

  private async dieAnimation(): Promise<gsap.core.Timeline> {
    const graphic = this.graphics.current[0].graphic;
    const value = { color: '#ffffff' };
    const endColor = '#ff0000';

    return gsap
      .timeline()
      .add(
        // Tween from zero tint to full red tint
        gsap.to(value, {
          color: endColor,
          duration: 0.5,
          onUpdate: () => {
            if (value.color.startsWith('rgb')) {
              graphic.tint = Color.fromRGBString(value.color);
            }
          },
        })
      )
      .to(graphic, { opacity: 0, duration: 2.5 }, 0)
      .add(
        // Gyrate left and right
        gsap
          .timeline({ repeat: 10, yoyo: true })
          .to(this.pos, { x: '-=1', duration: 0.1 })
          .to(this.pos, { x: '+=2', duration: 0.1 }),
        0
      )
      .then();
  }

External tweens, is it worth it?

I also wrote the above basic tween using Excalibur parallel actions. Both were equally fluent and expressive.
The Excalibur actions seem more than enough for probably 99% of things.

Demo time

A video of the basic tween (the attack animation) and the color tween (the death animation) can be seen below.

Another disclaimer, I've been building out this game in React + JavaScript for a little while, started to port it to Godot about a month ago, then stumbled across Excalibur about a week ago which is tempting me back to JS/TS land.
In short, the graphics are from one of my existing, but WIP, projects.
I'm not sure why I gave that disclaimer, but I'm on a few Discords where I show my work and they might be like "wait, weren't you porting to Godot!?"

CleanShot.2022-06-05.at.22.07.18.mp4

[eonarheim]

Wow this is so cool, I love the battle animation! Thanks for sharing, it's definitely good to know external tweening works so well in this situation!

Also I think you're using the ex.Animation.reset() and ex.GraphicsComponent.use() exactly how we intended 👍

Definitely keep us updated on your progress!