excaliburjs / Excalibur / 7519104048

89%

push

github

feat: Excalibur Scene Transitions & Loaders (#2790)

This PR  implements an API inspired by https://github.com/mattjennings/excalibur-router/ with permission from Matt.

The idea behind this refactoring is to add transitions between scenes and scene specific loaders!
* Add or remove scenes by constructor
* Add loaders by constructor
* New `DefaultLoader` type that allows for easier custom loader creation
* New `Transition` type for building custom transitions
* New scene lifecycle to allow scene specific resource loading
    * `onTransition(direction: "in" | "out") {...}`
    * `onPreLoad(loader: DefaultLoader) {...}`
* New async goto API that allows overriding loaders/transitions between scenes
* Scenes now can have `async onInitialize` and `async onActivate`!
* New scenes director API that allows upfront definition of scenes/transitions/loaders


View [this file](https://github.com/excaliburjs/Excalibur/blob/feat/async-init-ex-router/sandbox/tests/router/index.ts) for a current example of what the API looks like 


Defining scenes upfront
```typescript
const game = new ex.Engine({
  scenes: {
    scene1: {
      scene: scene1,
      transitions: {
        out: new ex.FadeInOut({duration: 1000, direction: 'out', color: ex.Color.Black}),
        in: new ex.FadeInOut({duration: 1000, direction: 'in'})
      }
    },
    scene2: {
      scene: scene2,
      loader: ex.DefaultLoader, // Constructor only option!
      transitions: {
        out: new ex.FadeInOut({duration: 1000, direction: 'out'}),
        in: new ex.FadeInOut({duration: 1000, direction: 'in', color: ex.Color.Black })
      }
    },
   scene3: ex.Scene // Constructor only option!
  } 
})

game.start('scene1',
{
  inTransition: new ex.FadeInOut({duration: 500, direction: 'in', color: ex.Color.ExcaliburBlue})
  loader: boot,
});
```

![scene-transitions-loader](https://github.com/excaliburjs/Excalibur/assets/612071/e81b3762-e0f9-4122-bd22-e3e477a1abd7)

4903 of 6151 branches covered (0.0%)

11112 of 12114 relevant lines covered (91.73%)

26810.43 hits per line