What is the "Scene Injection Map" and where is it documented?

I see this note in the documentation several places:

This property will only be available if defined in the Scene Injection Map

For example:

A scene level Camera System. This property will only be available if defined in the Scene Injection Map.

However, I have not seen any documentation that explains what the Scene Injection Map is or how to add things to it.

What’s more, this StackOverflow question on this same topic was marked solved despite not actually answering the question. It cites this post from Rich, where he also fails to provide any technical details on the supported mechanism, instead merely telling the asker not to use an alternative mechanism that was unofficially deprecated.

This example code, which I found by googling rather than any documentation or answers, is confusing as hell:

{
	//  Here we'll tailor the property injection map so that by default our Scene
	//  only gets 2 properties defined on it: 'makeStuff' and 'loader'.
	//  It will also have the property 'sys' which can never be redefined or removed.
	var config = {
		map: {
			add: 'makeStuff',
			load: 'loader'
		}
	};

	Phaser.Scene.call(this, config)
}

Why are the keys named add and load? What is the difference between the two? Why do both makeStuff and loader end up in the same place given that they’re being passed to different keys? Shouldn’t it be either:

  • add: [ "makeStuff", "loader" ], or
  • load: [ "makeStuff", "loader" ] ?

Furthermore, what values can be used here? If I want to add a camera, would it go in add or load? And precisely what value would I provide? What if I want to add more than one thing to the Scene Injection Map?

And what is the effect of add: 'makeStuff'? What does it accomplish? What is the value of this.makeStuff in the scene at runtime? Do we have any control over that value? If I wanted to define a static custom string value on the scene with property name “tpr_rules” and value “indeed”, how would I wire that up via the Scene Injection Map?

This example code prompts more questions than it answers. Absolutely nothing is explained.


What is the Scene Injection Map? Where is the documentation for it? Or, failing that, what is a working example that shows show to add to the map every possible built-in that can be added to it?

It’s an optional feature that’s rarely used.

There is already a default map so there is nothing extra you need to do.

The default mapping is

this.sys.add     → this.add
this.sys.cameras → this.cameras
this.sys.load    → this.load

etc. In that example, a custom mapping is given:

this.sys.add  → this.makeStuff
this.sys.load → this.loader

Because cameras is absent, there is no this.cameras property, just as the docs say.

2 Likes