Extern
An Extern Game Object is a special type of Game Object that allows you to pass rendering off to a 3rd party.
When you create an Extern and place it in the display list of a Scene, the renderer will process the list as usual. When it finds an Extern it will flush the current batch and prepare a transform matrix which your render function can take advantage of, if required.
The WebGL context is then left in a 'clean' state, ready for you to bind your own shaders, or draw to it, whatever you wish to do. This should all take place in the render method. The correct way to deploy an Extern object is to create a class that extends it, then override the render (and optionally preUpdate) methods and pass off control to your 3rd party libraries or custom WebGL code there.
The render method is called with this signature: render(renderer: Phaser.Renderer.WebGL.WebGLRenderer, drawingContext: Phaser.Renderer.WebGL.DrawingContext, calcMatrix: Phaser.GameObjects.Components.TransformMatrix, displayList: Phaser.GameObjects.GameObject[], displayListIndex: number): void.
The displayList and displayListIndex parameters allow you to check other objects in the display list. This might be convenient for optimizing operations such as resource management.
Once you've finished, you should free-up any of your resources. The Extern will then return Phaser state and carry on rendering the display list.
Although this object has lots of properties such as Alpha, Blend Mode and Tint, none of them are used during rendering unless you take advantage of them in your own render code.
Constructor
new Extern(scene)
Parameters
| name | type | optional | description |
|---|---|---|---|
| scene | Phaser.Scene | No | The Scene to which this Game Object belongs. A Game Object can only belong to one Scene at a time. |
Scope: static
Extends
Phaser.GameObjects.GameObject
Phaser.GameObjects.Components.Alpha
Phaser.GameObjects.Components.BlendMode
Phaser.GameObjects.Components.Depth
Phaser.GameObjects.Components.Flip
Phaser.GameObjects.Components.Origin
Phaser.GameObjects.Components.ScrollFactor
Phaser.GameObjects.Components.Size
Phaser.GameObjects.Components.Texture
Phaser.GameObjects.Components.Tint
Phaser.GameObjects.Components.Transform
Phaser.GameObjects.Components.Visible
Source: src/gameobjects/extern/Extern.js#L12
Since: 3.16.0
Inherited Methods
From Phaser.Events.EventEmitter:
- addListener
- emit
- eventNames
- listenerCount
- listeners
- off
- on
- once
- removeAllListeners
- removeListener
- shutdown
From Phaser.GameObjects.Components.Alpha:
From Phaser.GameObjects.Components.BlendMode:
From Phaser.GameObjects.Components.Depth:
From Phaser.GameObjects.Components.Filters:
- enableFilters
- focusFilters
- focusFiltersOnCamera
- focusFiltersOverride
- renderWebGLFilters
- setFiltersAutoFocus
- setFiltersFocusContext
- setFiltersForceComposite
- setFilterSize
- setRenderFilters
- willRenderFilters
From Phaser.GameObjects.Components.Flip:
From Phaser.GameObjects.Components.Origin:
From Phaser.GameObjects.Components.RenderSteps:
From Phaser.GameObjects.Components.ScrollFactor:
From Phaser.GameObjects.Components.Size:
From Phaser.GameObjects.Components.Texture:
From Phaser.GameObjects.Components.Tint:
From Phaser.GameObjects.Components.Transform:
- copyPosition
- getLocalPoint
- getLocalTransformMatrix
- getParentRotation
- getWorldPoint
- getWorldTransformMatrix
- setAngle
- setPosition
- setRandomPosition
- setRotation
- setScale
- setW
- setX
- setY
- setZ
From Phaser.GameObjects.Components.Visible:
From Phaser.GameObjects.GameObject:
- addToDisplayList
- addToUpdateList
- destroy
- disableInteractive
- getData
- getDisplayList
- getIndexList
- incData
- removeFromDisplayList
- removeFromUpdateList
- removeInteractive
- setActive
- setData
- setDataEnabled
- setInteractive
- setName
- setState
- setVertexRoundMode
- toggleData
- toJSON
- update
- willRender
- willRoundVertices
Public Methods
addedToScene
<instance> addedToScene()
Description:
Called when this Extern is added to a Scene.
Registers the Extern with the Scene's Update List so that preUpdate is called each frame.
Overrides: Phaser.GameObjects.GameObject#addedToScene
Source: src/gameobjects/extern/Extern.js#L104
Since: 3.50.0
preUpdate
<instance> preUpdate(time, delta)
Description:
Called automatically by the Scene Update List each frame.
Override this method in your own class to add custom logic that should run every frame, such as updating animations or physics.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| time | number | No | The current timestamp, as generated by the Request Animation Frame or SetTimeout. |
| delta | number | No | The delta time, in ms, elapsed since the last frame. |
Source: src/gameobjects/extern/Extern.js#L130
Since: 3.16.0
removedFromScene
<instance> removedFromScene()
Description:
Called when this Extern is removed from a Scene.
Removes the Extern from the Scene's Update List so that preUpdate is no longer called.
Overrides: Phaser.GameObjects.GameObject#removedFromScene
Source: src/gameobjects/extern/Extern.js#L117
Since: 3.50.0
render
<instance> render(renderer, drawingContext, calcMatrix, displayList, displayListIndex)
Description:
Override this method in your own class to provide custom rendering logic.
When the renderer encounters this Extern in the display list, it will flush the current batch, prepare a transform matrix, and leave the WebGL context in a clean state for you to bind your own shaders or draw calls.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| renderer | Phaser.Renderer.WebGL.WebGLRenderer | No | The WebGL Renderer instance. |
| drawingContext | Phaser.Renderer.WebGL.DrawingContext | No | The current Drawing Context. |
| calcMatrix | Phaser.GameObjects.Components.TransformMatrix | No | The calculated Transform Matrix for this Extern. |
| displayList | Array.<Phaser.GameObjects.GameObject> | No | The current display list for the Scene. |
| displayListIndex | number | No | The index of this Extern within the display list. |
Source: src/gameobjects/extern/Extern.js#L148
Since: 3.16.0
Inherited Members
From Phaser.GameObjects.Components.Alpha:
From Phaser.GameObjects.Components.BlendMode:
From Phaser.GameObjects.Components.Depth:
From Phaser.GameObjects.Components.Filters:
- filterCamera
- filters
- filtersAutoFocus
- filtersFocusContext
- filtersForceComposite
- maxFilterSize
- renderFilters
From Phaser.GameObjects.Components.Flip:
From Phaser.GameObjects.Components.Origin:
From Phaser.GameObjects.Components.ScrollFactor:
From Phaser.GameObjects.Components.Size:
From Phaser.GameObjects.Components.Texture:
From Phaser.GameObjects.Components.Tint:
From Phaser.GameObjects.Components.Transform:
From Phaser.GameObjects.Components.Visible:
From Phaser.GameObjects.GameObject:
- active
- body
- cameraFilter
- data
- displayList
- ignoreDestroy
- input
- isDestroyed
- name
- parentContainer
- renderFlags
- scene
- state
- tabIndex
- type
- vertexRoundMode