Implement Scene activation context and data passing

Context

Thinking about usage of scenes as navigation structures, you go between scenes almost like a page router. Typically with navigation APIs, you can pass data (like a URL or route data). In Excalibur, when you call Engine.goToScene(sceneKey) it might be nice to pass data to the Scene.onActivate hook.

Proposal

We’d need to figure out a way to indicate to TypeScript how to type this but something like this:

class Level extends Scene {
  onActivate(context) {
    console.log(context.data); // "overworld"
  }
}
game.add('level', new Level());
game.goToScene('level', 'overworld');

The data passed can be arbitrary, no reason to restrict it necessarily. By default, undefined is used.

interface SceneActivationContext<TData = undefined> {
  data: TData;
  previousScene: Scene;
  engine: Engine;
}

Maybe some type helpers on Scene?

class Level extends Scene<string> {
  onActivate(context /* type: SceneActivationContext<string> */) {
    console.log(context.data); // "overworld"
  }
}

Or can we override with optional generic?

class Scene {
  // ...
  public onActivate<TData = undefined>(context: SceneActivationContext<TData>) {
    // override me
  }
}

class Level extends Scene {
  onActivate<string>(context) {
    console.log(context.data);
                        ^ string
  }

[mattjennings]

@eonarheim oops, it seems the types are a bit off.

This is because the class methods take generics, i.e onActivate<TData = undefined>. Which means the inheriting class also has to match the same definition of generics:

class MyScene extends ex.Scene {
    public onActivate<string>(ctx: ex.SceneActivationContext<string>) {
    }
}

… which is, of course, not ideal.

So a solution would be to go back to having a generic of TActivationData on the Scene, but have it default to unknown . That way it can be inferred by the given generic for ctx: ex.SceneActivationContext in onActivate, and also shouldn’t break any types that just require ex.Scene like I ran into before.

before:

export class Scene
  extends Class
  implements CanInitialize, CanActivate, CanDeactivate, CanUpdate, CanDraw {

  public onActivate<TData = undefined>(_context: SceneActivationContext<TData>): void {}
}

after:

export class Scene<TActivationData = unknown>
  extends Class
  implements CanInitialize, CanActivate<TActivationData>, CanDeactivate, CanUpdate, CanDraw {

  public onActivate(_context: SceneActivationContext<TActivationData>): void {}
}

I’ll make a PR shortly with the changes and you can review if it makes sense. Sorry for the back and forth on this!

[eonarheim]

Hmm indeed, in that case I think providing it in the onActivate might be the best path forward 👍