The Scene to which this SpriteGPULayer belongs.
The texture that will be used to render the SpriteGPULayer. This must be sourced from a single image; a multi atlas will not work.
The maximum number of quads that this SpriteGPULayer will hold. This can be increased later if necessary.
The active state of this Game Object.
A Game Object with an active state of true is processed by the Scenes UpdateList, if added to it.
An active object is one which is having its logic and internal systems updated.
The alpha value of the Game Object.
This is a global value, impacting the entire Game Object, not just a region of it.
The alpha value starting from the bottom-left of the Game Object. This value is interpolated from the corner to the center of the Game Object.
The alpha value starting from the bottom-right of the Game Object. This value is interpolated from the corner to the center of the Game Object.
The alpha value starting from the top-left of the Game Object. This value is interpolated from the corner to the center of the Game Object.
The alpha value starting from the top-right of the Game Object. This value is interpolated from the corner to the center of the Game Object.
An ordered list of animations in the frame data texture.
A map of frame indices to animation parameters in
the frame data texture.
These are the starting frame indices used by the vertex shader.
They can be used to map back to names in animationDataIndices.
A map of animation names to animation parameters in the frame data texture. This is used to convert animation names to indices and durations for the vertex shader.
Sets the Blend Mode being used by this Game Object.
This can be a const, such as Phaser.BlendModes.SCREEN, or an integer, such as 4 (for Overlay)
Under WebGL only the following Blend Modes are available:
Canvas has more available depending on browser support.
You can also create your own custom Blend Modes in WebGL.
Blend modes have different effects under Canvas and WebGL, and from browser to browser, depending on support. Blend Modes also cause a WebGL batch flush should it encounter a new blend mode. For these reasons try to be careful about the construction of your Scene and the frequency of which blend modes are used.
If this Game Object is enabled for Arcade or Matter Physics then this property will contain a reference to a Physics Body.
Which segments of the buffer require updates.
This is a bitfield with segments equal to _segments.
The size of each segment of the buffer that requires updates.
A bitmask that controls if this Game Object is drawn by a Camera or not.
Not usually set directly, instead call Camera.ignore, however you can
set this property directly using the Camera.id property:
Customized WebGL render nodes of this Game Object. RenderNodes are responsible for managing the rendering process of this Game Object. A default set of RenderNodes are coded into the engine, but they will check here first to see if a custom one exists.
A Data Manager.
It allows you to store, query and get key/value paired information specific to this Game Object.
null by default. Automatically created if you use getData or setData or setDataEnabled.
The default RenderNodes for this Game Object. RenderNodes are responsible for managing the rendering process of this Game Object. These are the nodes that are used if no custom ones are set.
RenderNodes are identified by a unique key for their role.
Common role keys include:
The depth of this Game Object within the Scene. Ensure this value is only ever set to a number data-type.
The depth is also known as the 'z-index' in some environments, and allows you to change the rendering order of Game Objects, without actually moving their position in the display list.
The default depth is zero. A Game Object with a higher depth value will always render in front of one with a lower value.
Setting the depth will queue a depth sort event within the Scene.
Holds a reference to the Display List that contains this Game Object.
This is set automatically when this Game Object is added to a Scene or Layer.
You should treat this property as being read-only.
ReadonlyEASEStrings for valid easing functions that can be assigned to
the ease property of an SpriteGPULayerMemberAnimation.
This is the reverse mapping of this.EASE_CODES.
ReadonlyEASE_Codes for valid easing functions that can be assigned to
the ease property of an SpriteGPULayerMemberAnimation.
This is the reverse mapping of this.EASE.
The Camera used for filters. You can use this to alter the perspective of filters. It is not necessary to use this camera for ordinary rendering.
This is only available if you use the enableFilters method.
ReadonlyfiltersGet the filters lists.
This is an object with internal and external properties.
Each list is a {@see Phaser.GameObjects.Components.FilterList} object.
This is only available if you use the enableFilters method.
Whether filterCamera should update every frame
to focus on the Game Object.
Disable this if you want to manually control the camera.
Whether the filters should focus on the context, rather than attempt to focus on the Game Object. This is enabled automatically when enabling filters on objects which don't have well-defined bounds.
This effectively sets the internal filters to render the same way as the external filters.
This is only used if filtersAutoFocus is enabled.
The "context" is the framebuffer to which the Game Object is rendered. This is usually the main framebuffer, but might be another framebuffer. It can even be several different framebuffers if the Game Object is rendered multiple times.
Whether the Filters component should always draw to a framebuffer, even if there are no active filters.
The Texture Frame this Game Object is using to render with.
A map of frame names to indices in the frame data texture. This is used to convert frame names to indices for the vertex shader.
A map of indices to frame names in the frame data texture. This is used to convert frame indices back to names for debugging.
A texture containing the frame data for the SpriteGPULayer. This is used by the vertex shader.
The texture is composed of pixel strides, where each stride is interpreted as 6 16-bit unsigned integers, representing the x, y, width, height, and origin x and y of a frame. The texture will be up to 4096 pixels wide and as tall as necessary.
There are two sets of data in the texture: frames and animations.
Frames are taken from the texture.
Animations are defined by calling setAnimations,
and consist of runs of frames suited to shader animation.
Although the texture will be regenerated by setAnimations,
the frames are stored first, so their indices won't change.
If you change the texture of this layer, you will need to
regenerate this by calling generateFrameDataTexture.
The gravity used by member animations in 'Gravity' mode. This is the acceleration in pixels per second squared. The default is 1024 pixels per second squared.
Any animation can be set to ease: 'Gravity' to use this value.
Instead of amplitude, the animation takes
velocity (a number of pixels) and
gravityFactor (0-1) parameters.
This Game Object will ignore all calls made to its destroy method if this flag is set to true.
This includes calls that may come from a Group, Container or the Scene itself.
While it allows you to persist a Game Object across Scenes, please understand you are entirely
responsible for managing references to and from this Game Object.
If this Game Object is enabled for input then this property will contain an InteractiveObject instance.
Not usually set directly. Instead call GameObject.setInteractive().
A boolean flag indicating if this Game Object is being cropped or not.
You can toggle this at any time after setCrop has been called, to turn cropping on or off.
Equally, calling setCrop with no arguments will reset the crop and disable it.
ReadonlylightingShould this GameObject use lighting?
This flag is used to set up WebGL shaders for rendering.
The Mask this Game Object is using during render.
ReadonlyMAX_The state of bufferUpdateSegments when it's full.
This is a constant value and should not be altered.
If you do, all hell will break loose.
The maximum size of the base filter texture. Filters may use a larger texture after the base texture is rendered. The maximum texture size is 4096 in WebGL. You may set this lower to save memory or prevent resizing.
The number of quad members in the SpriteGPULayer.
The name of this Game Object. Empty by default and never populated by Phaser, this is left for developers to use.
The next member buffer, used to store member data before it is added to the GPU buffer.
A Float32Array view of the next member buffer.
A Uint32Array view of the next member buffer. This is used to write 32-bit integer data to the buffer. It is used for color data.
The parent Container of this Game Object, if it has one.
Whether any filters should be rendered on this Game Object.
This is true by default, even if there are no filters yet.
Disable this to skip filter rendering.
Use willRenderFilters() to see if there are any active filters.
The flags that are compared against RENDER_MASK to determine if this Game Object will render or not.
The bits are 0001 | 0010 | 0100 | 1000 set by the components Visible, Alpha, Transform and Texture respectively.
If those components are not used by your custom class then you can use this bitmask as you wish.
An object to store render node specific data in, to be read by the render nodes this Game Object uses.
Render nodes store their data under their own name, not their role.
A reference to the Scene to which this Game Object belongs.
Game Objects can only belong to one Scene.
You should consider this property as being read-only. You cannot move a Game Object to another Scene by simply changing it.
Should this GameObject use self-shadowing?
Self-shadowing is only enabled if lighting is enabled.
The game config option render.selfShadow is used if this is not a boolean.
This flag is used to set up WebGL shaders for rendering.
ReadonlysizeThe maximum number of quad members that can be in the SpriteGPULayer.
This value is read-only. Change buffer size with resize.
The current state of this Game Object.
Phaser itself will never modify this value, although plugins may do so.
Use this property to track the state of a Game Object during its lifetime. For example, it could change from a state of 'moving', to 'attacking', to 'dead'. The state value should be an integer (ideally mapped to a constant in your game code), or a string. These are recommended to keep it light and simple, with fast comparisons. If you need to store complex data about your Game Object, look at using the Data Component instead.
The SubmitterSpriteGPULayer RenderNode for this SpriteGPULayer.
This handles rendering the SpriteGPULayer to the GPU. It is created automatically when the SpriteGPULayer is initialized. Most RenderNodes are singletons stored in the RenderNodeManager, but because this one holds very specific data, it is stored in the SpriteGPULayer itself.
The Tab Index of the Game Object. Reserved for future use by plugins and the Input Manager.
The Texture this Game Object is using to render with.
The time elapsed since timer initialization, in milliseconds.
The time after which timeElapsed will reset, in milliseconds.
By default, this is 1 hour.
If you use the timer for animations, you can set this to a period
that matches the animation durations.
This is necessary for the timer to avoid floating-point precision issues in shaders. A float32 can represent a few hours of milliseconds accurately, but the precision decreases as the value increases.
Whether the elapse timer is paused.
A textual representation of this Game Object, i.e. sprite.
Used internally by Phaser but is available for your own custom classes to populate.
The current vertex rounding mode of this Game Object. This is used by the WebGL Renderer to determine how to round the vertex positions. It can have several values:
off - No rounding is applied.safe - Rounding is applied if the object is 'safe'.safeAuto - Rounding is applied if the object is 'safe' and the camera has roundPixels enabled.full - Rounding is always applied.fullAuto - Rounding is always applied if the camera has roundPixels enabled.A 'safe' object is one that is not rotated or scaled by any transform matrix while rendering. The effective transform is a simple translation. In such cases, rounding will affect all vertices the same way.
Using full rounding can cause vertices to wobble, because they might not be aligned to the pixel grid. Full rounding gives a janky look like PS1 games.
You can use other values if you want to create your own custom rounding modes.
The visible state of the Game Object.
An invisible Game Object will skip rendering, but will still process update logic.
Static ReadonlyRENDER_The bitmask that GameObject.renderFlags is compared against to determine if the Game Object will render or not.
Adds data to the SpriteGPULayer buffer. It is inserted at the end of the buffer.
This is mostly used internally by the SpriteGPULayer.
It takes raw data as a buffer, which is very efficient,
but addMember is easier to use.
Note that, if you add a member with an animation,
the animation must either already be enabled,
or you must enable it with setAnimationEnabled,
e.g. layer.setAnimationEnabled('Linear', true) or
layer.setAnimationEnabled(layer.EASE_CODES[layer.EASE.Linear], true).
This is a buffer modification, and is expensive.
The raw data to add to the buffer.
This callback is invoked when this Game Object is added to a Scene.
Can be overriden by custom Game Objects, but be aware of some Game Objects that will use this, such as Sprites, to add themselves into the Update List.
You can also listen for the ADDED_TO_SCENE event from this Game Object.
Add a listener for a given event.
The event name.
The listener function.
Optionalcontext: anyThe context to invoke the listener with. Default this.
Adds a member to the SpriteGPULayer. This is the easiest way to add a member to the SpriteGPULayer.
This is a buffer modification, and is expensive.
Optionalmember: Partial<Member>The member to add to the SpriteGPULayer.
Add a render step.
The first render step in _renderSteps is run first.
It should call the next render step in the list.
This allows render steps to control the rendering flow.
The render step function to add.
Optionalindex: numberThe index in the render list to add the step to. Omit to add to the end.
Adds this Game Object to the given Display List.
If no Display List is specified, it will default to the Display List owned by the Scene to which this Game Object belongs.
A Game Object can only exist on one Display List at any given time, but may move freely between them.
If this Game Object is already on another Display List when this method is called, it will first be removed from it, before being added to the new list.
You can query which list it is on by looking at the Phaser.GameObjects.GameObject#displayList property.
If a Game Object isn't on any display list, it will not be rendered. If you just wish to temporarly
disable it from rendering, consider using the setVisible method, instead.
OptionaldisplayList: DisplayList | LayerThe Display List to add to. Defaults to the Scene Display List.
Adds this Game Object to the Update List belonging to the Scene.
When a Game Object is added to the Update List it will have its preUpdate method called
every game frame. This method is passed two parameters: delta and time.
If you wish to run your own logic within preUpdate then you should always call
super.preUpdate(time, delta) within it, or it may fail to process required operations,
such as Sprite animations.
Clears all segments of the buffer that require an update.
Clears all alpha values associated with this Game Object.
Immediately sets the alpha levels back to 1 (fully opaque).
Clears the mask that this Game Object was using.
This only works in the Canvas Renderer. In WebGL, use a Mask filter instead (see Phaser.GameObjects.Components.FilterList#addMask).
OptionaldestroyMask: booleanDestroy the mask before clearing it? Default false.
Creates and returns a Geometry Mask. This mask can be used by any Game Object, including this one.
To create the mask you need to pass in a reference to a Graphics Game Object.
If you do not provide a graphics object, and this Game Object is an instance of a Graphics object, then it will use itself to create the mask.
This means you can call this method to create a Geometry Mask from any Graphics Game Object.
This only works in the Canvas Renderer. In WebGL, use a Mask filter instead (see Phaser.GameObjects.Components.FilterList#addMask).
Optionalgraphics: GameObjects.Graphics | ShapeA Graphics Game Object, or any kind of Shape Game Object. The geometry within it will be used as the mask.
Destroys this Game Object removing it from the Display List and Update List and severing all ties to parent resources.
Also removes itself from the Input Manager and Physics Manager if previously enabled.
Use this to remove a Game Object from your game if you don't ever plan to use it again. As long as no reference to it exists within your own code it should become free for garbage collection by the browser.
If you just want to temporarily disable an object then look at using the Game Object Pool instead of destroying it, as destroyed objects cannot be resurrected.
OptionalfromScene: booleanTrue if this Game Object is being destroyed by the Scene, false if not. Default false.
If this Game Object has previously been enabled for input, this will disable it.
An object that is disabled for input stops processing or being considered for
input events, but can be turned back on again at any time by simply calling
setInteractive() with no arguments provided.
If want to completely remove interaction from this Game Object then use removeInteractive instead.
OptionalresetCursor: booleanShould the currently active Input cursor, if any, be reset to the default cursor? Default false.
Edits a member of the SpriteGPULayer. This will update the member's data in the GPU buffer. This is an expensive operation, as it requires the whole buffer to be updated.
The index of the member to edit.
The new member data.
Calls each of the listeners registered for a given event.
The event name.
Additional arguments that will be passed to the event handler.
Enable this Game Object to have filters.
You need to call this method if you want to use the filterCamera
and filters properties. It sets up the necessary data structures.
You may disable filter rendering with the renderFilters property.
This is a WebGL only feature. It will return early if not available.
Return an array listing the events for which the emitter has registered listeners.
Focus the filter camera.
This sets the size and position of the filter camera to match the GameObject.
This is called automatically on render if filtersAutoFocus is enabled.
This will focus on the GameObject's raw dimensions if available. If the GameObject has no dimensions, this will focus on the context: the camera belonging to the DrawingContext used to render the GameObject. Context focus occurs during rendering, as the context is not known until then.
Manually override the focus of the filter camera.
This allows you to set the size and position of the filter camera manually.
It deactivates filtersAutoFocus when called.
The camera will set scroll to place the game object at the
given position within a rectangle of the given width and height.
For example, calling focusFiltersOverride(400, 200, 800, 600)
will focus the camera to place the object's center
100 pixels above the center of the camera (which is at 400x300).
Optionalx: numberThe x-coordinate of the focus point, relative to the filter size. Default is the center.
Optionaly: numberThe y-coordinate of the focus point, relative to the filter size. Default is the center.
Optionalwidth: numberThe width of the focus area. Default is the filter width.
Optionalheight: numberThe height of the focus area. Default is the filter height.
Generate frameDataTexture for the SpriteGPULayer.
This is used by the vertex shader to access frame data.
Retrieves the value for the given key in this Game Objects Data Manager, or undefined if it doesn't exist.
You can also access values via the values object. For example, if you had a key called gold you can do either:
sprite.getData('gold');
Or access the value directly:
sprite.data.values.gold;
You can also pass in an array of keys, in which case an array of values will be returned:
sprite.getData([ 'gold', 'armor', 'health' ]);
This approach is useful for destructuring arrays in ES6.
The key of the value to retrieve, or an array of keys.
Get the number of bytes used to define a member. If you are directly editing the buffer, you will need this value as a 'stride' to move through the buffer.
Returns a reference to the underlying display list array that contains this Game Object, which will be either the Scene's Display List or the internal list belonging to its parent Container, if it has one.
If this Game Object is not on a display list or in a container, it will return null.
You should be very careful with this method, and understand that it returns a direct reference to the internal array used by the Display List. Mutating this array directly can cause all kinds of subtle and difficult to debug issues in your game.
Returns an array containing the display list index of either this Game Object, or if it has one, its parent Container. It then iterates up through all of the parent containers until it hits the root of the display list (which is index 0 in the returned array).
Used internally by the InputPlugin but also useful if you wish to find out the display depth of this Game Object and all of its ancestors.
Returns a member of the SpriteGPULayer.
This returns an object copied from the buffer. Editing it will not change anything in the SpriteGPULayer. The object will be functionally identical to the data used to create the buffer, but some values may be different.
this.EASE).The index of the member to get.
Returns the raw data of a member of the SpriteGPULayer.
This can be useful as the base of efficient editing operations,
including calls to addData and patchMember,
so no data has to be converted.
This returns an Uint32Array copied from the buffer. Editing it will not change anything in the SpriteGPULayer. The array will be functionally identical to the data used to create the buffer.
By default, the data is copied into this.nextMember.
You can use the views this.nextMemberF32 and this.nextMemberU32
to access the data in different formats.
If you provide an out parameter, the data will be copied to that array,
and you must construct your own views.
The primary data view is a 41-element array of 32-bit floats. Some values are grouped to form animations, of the form:
The overall structure is thus:
Elements 32-35 are only visible in the Uint32Array view. They store 32-bit RGBA values for the four corners of the tint:
If the ease for an animation is 'Gravity', the amplitude is replaced
with a two-part value: the integer part is the velocity,
and the fractional part is the gravityFactor.
The index of the member to get.
Optionalout: Uint32ArrayAn optional array to copy the data to. If not provided, this.nextMember will be populated, and nextMemberU32 will be returned.
Return a list of features to enable in the shader program. This is used when the shader program is compiled.
Increase a value for the given key within this Game Objects Data Manager. If the key doesn't already exist in the Data Manager then it is increased from 0.
If the Game Object has not been enabled for data (via setDataEnabled) then it will be enabled
before setting the value.
If the key doesn't already exist in the Data Manager then it is created.
When the value is first set, a setdata event is emitted from this Game Object.
The key to change the value for.
Optionalamount: numberThe amount to increase the given key by. Pass a negative value to decrease the key. Default 1.
Initializes the render nodes for this Game Object.
This method is called when the Game Object is added to the Scene. It is responsible for setting up the default render nodes this Game Object will use.
The default render nodes to set for this Game Object.
Inserts members into the SpriteGPULayer. This will update the GPU buffer. This is an expensive operation, as it requires the whole buffer to be updated after the insertion point.
Inserts raw data into the SpriteGPULayer. This will update the GPU buffer. This is an expensive operation, as it requires the whole buffer to be updated after the insertion point.
The data must be passed in as a Uint32Array. This will preserve data that other TypedArrays would not. As it uses an underlying ArrayBuffer, you can work on the data with any TypedArray view before submitting it.
The buffer can contain 1 or more members.
Ensure that the buffer is the correct size for the number of members.
See getMemberData for the structure of the data.
Note that, if you add a member with an animation,
the animation must either already be enabled,
or you must enable it with setAnimationEnabled,
e.g. layer.setAnimationEnabled('Linear', true) or
layer.setAnimationEnabled(layer.EASE_CODES[layer.EASE.Linear], true).
The index at which to insert members.
The members to insert.
Return the number of listeners listening to a given event.
The event name.
Return the listeners registered for a given event.
The event name.
Remove the listeners of a given event.
The event name.
Optionalfn: FunctionOnly remove the listeners that match this function.
Optionalcontext: anyOnly remove the listeners that have this context.
Optionalonce: booleanOnly remove one-time listeners.
Add a listener for a given event.
The event name.
The listener function.
Optionalcontext: anyThe context to invoke the listener with. Default this.
Add a one-time listener for a given event.
The event name.
The listener function.
Optionalcontext: anyThe context to invoke the listener with. Default this.
Update a member of the SpriteGPULayer with raw data. This will update the member's data in the GPU buffer. This is an expensive operation, as it requires the whole buffer to be updated.
You can supply a mask to control which properties are updated.
This can be useful for updating only a subset of properties.
Try using getMemberData to copy an existing member's data,
then modify the data you want to change.
The data must be passed in as an Uint32Array. This will preserve data that other TypedArrays would not. As it uses an underlying ArrayBuffer, you can work on the data with any TypedArray view before submitting it.
The index of the member to patch.
The new member data.
Optionalmask: number[]The mask to apply to the member data. A value of 1 will update the member data, a value of 0 will keep the existing member data.
ProtectedpreInternal destroy handler, called as part of the destroy process.
Remove all listeners, or those of the specified event.
Optionalevent: string | symbolThe event name.
This callback is invoked when this Game Object is removed from a Scene.
Can be overriden by custom Game Objects, but be aware of some Game Objects that will use this, such as Sprites, to removed themselves from the Update List.
You can also listen for the REMOVED_FROM_SCENE event from this Game Object.
Removes this Game Object from the Display List it is currently on.
A Game Object can only exist on one Display List at any given time, but may move freely removed and added back at a later stage.
You can query which list it is on by looking at the Phaser.GameObjects.GameObject#displayList property.
If a Game Object isn't on any Display List, it will not be rendered. If you just wish to temporarly
disable it from rendering, consider using the setVisible method, instead.
Removes this Game Object from the Scene's Update List.
When a Game Object is on the Update List, it will have its preUpdate method called
every game frame. Calling this method will remove it from the list, preventing this.
Removing a Game Object from the Update List will stop most internal functions working. For example, removing a Sprite from the Update List will prevent it from being able to run animations.
If this Game Object has previously been enabled for input, this will queue it for removal, causing it to no longer be interactive. The removal happens on the next game step, it is not immediate.
The Interactive Object that was assigned to this Game Object will be destroyed, removed from the Input Manager and cleared from this Game Object.
If you wish to re-enable this Game Object at a later date you will need to
re-create its InteractiveObject by calling setInteractive again.
If you wish to only temporarily stop an object from receiving input then use
disableInteractive instead, as that toggles the interactive state, where-as
this erases it completely.
If you wish to resize a hit area, don't remove and then set it as being
interactive. Instead, access the hitarea object directly and resize the shape
being used. I.e.: sprite.input.hitArea.setSize(width, height) (assuming the
shape is a Rectangle, which it is by default.)
OptionalresetCursor: booleanShould the currently active Input cursor, if any, be reset to the default cursor? Default false.
Remove the listeners of a given event.
The event name.
Optionalfn: FunctionOnly remove the listeners that match this function.
Optionalcontext: anyOnly remove the listeners that have this context.
Optionalonce: booleanOnly remove one-time listeners.
Removes a member or a number of members from the SpriteGPULayer. This will update the GPU buffer. This is an expensive operation, as it requires the whole buffer to be updated.
The buffer is not resized.
The index of the member to remove.
Optionalcount: numberThe number of members to remove, default 1. Default 1.
Render this object using filters.
This function's scope is not guaranteed, so it doesn't refer to this.
The WebGL Renderer instance to render with.
The Game Object being rendered.
The current drawing context.
OptionalparentMatrix: TransformMatrixThe parent matrix of the Game Object, if it has one.
OptionalrenderStep: numberThe index of this function in the Game Object's list of render processes. Used to support multiple rendering functions. Default 0.
Run a step in the render process. This is called automatically by the Render module.
In most cases, it just runs the renderWebGL function.
When _renderSteps has more than one entry,
such as when Filters are enabled for this object,
it allows those processes to defer renderWebGL
and otherwise manage the flow of rendering.
The WebGL Renderer instance to render with.
The Game Object being rendered.
The current drawing context.
OptionalparentMatrix: TransformMatrixThe parent matrix of the Game Object, if it has one.
OptionalrenderStep: numberWhich step of the rendering process should be run? Default 0.
OptionaldisplayList: GameObject[]The display list which is currently being rendered. If not provided, it will be created with the Game Object.
OptionaldisplayListIndex: numberThe index of the Game Object within the display list. Default 0.
Reset the elapse timer for this game object.
Optionalms: numberThe time to reset the timer to. Default 0.
Resizes the SpriteGPULayer buffer to a new size. Optionally, clears the buffer.
This is an expensive operation, as it requires the whole buffer to be updated. It can take many frames to complete.
The new number of members in the SpriteGPULayer.
Optionalclear: booleanWhether to clear the buffer. Default false.
Move this Game Object so that it appears above the given Game Object.
This means it will render immediately after the other object in the display list.
Both objects must belong to the same display list, or parent container.
This method does not change this Game Objects depth value, it simply alters its list position.
The Game Object that this Game Object will be moved to be above.
Sets the active property of this Game Object and returns this Game Object for further chaining.
A Game Object with its active property set to true will be updated by the Scenes UpdateList.
True if this Game Object should be set as active, false if not.
Sets all segments of the buffer to require an update.
Set the Alpha level of this Game Object. The alpha controls the opacity of the Game Object as it renders. Alpha values are provided as a float between 0, fully transparent, and 1, fully opaque.
If your game is running under WebGL you can optionally specify four different alpha values, each of which
correspond to the four corners of the Game Object. Under Canvas only the topLeft value given is used.
OptionaltopLeft: numberThe alpha value used for the top-left of the Game Object. If this is the only value given it's applied across the whole Game Object. Default 1.
OptionaltopRight: numberThe alpha value used for the top-right of the Game Object. WebGL only.
OptionalbottomLeft: numberThe alpha value used for the bottom-left of the Game Object. WebGL only.
OptionalbottomRight: numberThe alpha value used for the bottom-right of the Game Object. WebGL only.
Set the enabled state of an animation.
This will enable or disable the animation in the shader program.
This method is called automatically when animations are added with
addMember, so you should not need to call it manually.
Every enabled animation has a cost in the shader program. In particular, low-end devices may be unable to compile a large number of animations, so be careful when enabling many animations.
Note that animations are not disabled automatically, even if they are not used by any members. There are probably too many members for this to be efficient.
The name of the animation to enable or disable.
Whether to enable or disable the animation.
Set the animations available to the SpriteGPULayer.
This will call generateFrameDataTexture to regenerate
frameDataTexture.
Each animation can be either an Animation object, or an object containing a name, duration, and an array of frame names/numbers. If an Animation is used, it will be converted to the object form, discarding any custom individual frame durations and using the animation's duration as default.
This is not a Phaser Animation. It is intended to cycle automatically on the GPU without supervision or interaction. It will not emit events, allow you to pause the animation, set number of repeats, etc.
An array of animations to set.
Move this Game Object so that it appears below the given Game Object.
This means it will render immediately under the other object in the display list.
Both objects must belong to the same display list, or parent container.
This method does not change this Game Objects depth value, it simply alters its list position.
The Game Object that this Game Object will be moved to be below.
Sets the Blend Mode being used by this Game Object.
This can be a const, such as Phaser.BlendModes.SCREEN, or an integer, such as 4 (for Overlay)
Under WebGL only the following Blend Modes are available:
Canvas has more available depending on browser support.
You can also create your own custom Blend Modes in WebGL.
Blend modes have different effects under Canvas and WebGL, and from browser to browser, depending on support. Blend Modes also cause a WebGL batch flush should it encounter a new blend mode. For these reasons try to be careful about the construction of your Scene and the frequency in which blend modes are used.
The BlendMode value. Either a string, a CONST or a number.
Applies a crop to a texture based Game Object, such as a Sprite or Image.
The crop is a rectangle that limits the area of the texture frame that is visible during rendering.
Cropping a Game Object does not change its size, dimensions, physics body or hit area, it just changes what is shown when rendered.
The crop size as well as coordinates can not exceed the the size of the texture frame.
The crop coordinates are relative to the texture frame, not the Game Object, meaning 0 x 0 is the top-left.
Therefore, if you had a Game Object that had an 800x600 sized texture, and you wanted to show only the left
half of it, you could call setCrop(0, 0, 400, 600).
It is also scaled to match the Game Object scale automatically. Therefore a crop rectangle of 100x50 would crop an area of 200x100 when applied to a Game Object that had a scale factor of 2.
You can either pass in numeric values directly, or you can provide a single Rectangle object as the first argument.
Call this method with no arguments at all to reset the crop, or toggle the property isCropped to false.
You should do this if the crop rectangle becomes the same size as the frame itself, as it will allow the renderer to skip several internal calculations.
Optionalx: number | Geom.RectangleThe x coordinate to start the crop from. Cannot be negative or exceed the Frame width. Or a Phaser.Geom.Rectangle object, in which case the rest of the arguments are ignored.
Optionaly: numberThe y coordinate to start the crop from. Cannot be negative or exceed the Frame height.
Optionalwidth: numberThe width of the crop rectangle in pixels. Cannot exceed the Frame width.
Optionalheight: numberThe height of the crop rectangle in pixels. Cannot exceed the Frame height.
Allows you to store a key value pair within this Game Objects Data Manager.
If the Game Object has not been enabled for data (via setDataEnabled) then it will be enabled
before setting the value.
If the key doesn't already exist in the Data Manager then it is created.
sprite.setData('name', 'Red Gem Stone');
You can also pass in an object of key value pairs as the first argument:
sprite.setData({ name: 'Red Gem Stone', level: 2, owner: 'Link', gold: 50 });
To get a value back again you can call getData:
sprite.getData('gold');
Or you can access the value directly via the values property, where it works like any other variable:
sprite.data.values.gold += 50;
When the value is first set, a setdata event is emitted from this Game Object.
If the key already exists, a changedata event is emitted instead, along an event named after the key.
For example, if you updated an existing key called PlayerLives then it would emit the event changedata-PlayerLives.
These events will be emitted regardless if you use this method to set the value, or the direct values setter.
Please note that the data keys are case-sensitive and must be valid JavaScript Object property strings.
This means the keys gold and Gold are treated as two unique values within the Data Manager.
The key to set the value for. Or an object of key value pairs. If an object the data argument is ignored.
Optionaldata: anyThe value to set for the given key. If an object is provided as the key this argument is ignored.
Adds a Data Manager component to this Game Object.
The depth of this Game Object within the Scene.
The depth is also known as the 'z-index' in some environments, and allows you to change the rendering order of Game Objects, without actually moving their position in the display list.
The default depth is zero. A Game Object with a higher depth value will always render in front of one with a lower value.
Setting the depth will queue a depth sort event within the Scene.
The depth of this Game Object. Ensure this value is only ever a number data-type.
Set whether filters should be updated every frame.
Sets the filtersAutoFocus property.
Whether filters should be updated every frame.
Set whether the filters should focus on the context.
Sets the filtersFocusContext property.
Whether the filters should focus on the context.
Set whether the filters should always draw to a framebuffer.
Sets the filtersForceComposite property.
Whether the object should always draw to a framebuffer, even if there are no active filters.
Set the base size of the filter camera. This is the size of the texture that internal filters will be drawn to. External filters are drawn to the size of the context (usually the game canvas).
This is typically the size of the GameObject.
It is set automatically when the Game Object is rendered
and filtersAutoFocus is enabled.
Turn off auto focus to set it manually.
Technically, larger framebuffers may be used to provide padding. This is the size of the final framebuffer used for "internal" rendering.
Base width of the filter texture.
Base height of the filter texture.
Sets the frame this Game Object will use to render with.
If you pass a string or index then the Frame has to belong to the current Texture being used by this Game Object.
If you pass a Frame instance, then the Texture being used by this Game Object will also be updated.
Calling setFrame will modify the width and height properties of your Game Object.
It will also change the origin if the Frame has a custom pivot point, as exported from packages like Texture Packer.
The name or index of the frame within the Texture, or a Frame instance.
OptionalupdateSize: booleanShould this call adjust the size of the Game Object? Default true.
OptionalupdateOrigin: booleanShould this call adjust the origin of the Game Object? Default true.
Pass this Game Object to the Input Manager to enable it for Input.
Input works by using hit areas, these are nearly always geometric shapes, such as rectangles or circles, that act as the hit area for the Game Object. However, you can provide your own hit area shape and callback, should you wish to handle some more advanced input detection.
If no arguments are provided it will try and create a rectangle hit area based on the texture frame the Game Object is using. If this isn't a texture-bound object, such as a Graphics or BitmapText object, this will fail, and you'll need to provide a specific shape for it to use.
You can also provide an Input Configuration Object as the only argument to this method.
OptionalhitArea: anyEither an input configuration object, or a geometric shape that defines the hit area for the Game Object. If not given it will try to create a Rectangle based on the texture frame.
Optionalcallback: HitAreaCallbackThe callback that determines if the pointer is within the Hit Area shape or not. If you provide a shape you must also provide a callback.
OptionaldropZone: booleanShould this Game Object be treated as a drop zone target? Default false.
Sets whether this GameObject should use lighting.
true to use lighting, or false to disable it.
Sets the mask that this Game Object will use to render with.
The mask must have been previously created and must be a GeometryMask. This only works in the Canvas Renderer. In WebGL, use a Mask filter instead (see Phaser.GameObjects.Components.FilterList#addMask).
If a mask is already set on this Game Object it will be immediately replaced.
Masks are positioned in global space and are not relative to the Game Object to which they are applied. The reason for this is that multiple Game Objects can all share the same mask.
Masks have no impact on physics or input detection. They are purely a rendering component that allows you to limit what is visible during the render pass.
The mask this Game Object will use when rendering.
Sets the name property of this Game Object and returns this Game Object for further chaining.
The name property is not populated by Phaser and is presented for your own use.
The name to be given to this Game Object.
Set whether the filters should be rendered.
Sets the renderFilters property.
Whether the filters should be rendered.
Adds an entry to the renderNodeData object of this game object.
If key is not set, it is created. If it is set, it is updated.
If value is undefined and key exists, the key is removed.
The render node to set the data for. If a string, it should be the name of the render node.
The key of the property to set.
The value to set the property to.
Sets the RenderNode for a given role.
Also sets the relevant render node data object, if specified.
If the node cannot be set, no changes are made.
The key of the role to set the render node for.
The render node to set on this Game Object. Either a string, or a RenderNode instance. If null, the render node is removed, along with its data.
OptionalrenderNodeData: objectAn object to store render node specific data in, to be read by the render nodes this Game Object uses.
OptionalcopyData: booleanShould the data be copied from the renderNodeData object? Default false.
Sets a segment of the buffer to require an update.
The index at which an update occurred, which requires the segment to be updated.
Sets whether this GameObject should use self-shadowing.
Self-shadowing is only enabled if lighting is also enabled.
Optionalenabled: booleantrue to use self-shadowing, false to disable it, null to use the game default from config.render.selfShadow, or undefined to keep the setting.
Optionalpenumbra: numberThe penumbra value for the shadow. Lower is sharper but more jagged. Default is 0.5.
OptionaldiffuseFlatThreshold: numberThe texture brightness threshold at which the diffuse lighting will be considered flat. Range is 0-1. Default is 1/3.
Sets the current state of this Game Object.
Phaser itself will never modify the State of a Game Object, although plugins may do so.
For example, a Game Object could change from a state of 'moving', to 'attacking', to 'dead'. The state value should typically be an integer (ideally mapped to a constant in your game code), but could also be a string. It is recommended to keep it light and simple. If you need to store complex data about your Game Object, look at using the Data Component instead.
The state of the Game Object.
Sets the texture and frame this Game Object will use to render with.
Textures are referenced by their string-based keys, as stored in the Texture Manager.
The key of the texture to be used, as stored in the Texture Manager.
Optionalframe: string | numberThe name or index of the frame within the Texture.
Pauses or resumes the elapse timer for this game object.
Optionalpaused: booleanPause state (true to pause, false to unpause). If not specified, the timer will unpause.
Set the reset period for the elapse timer for this game object.
The time after which timeElapsed will reset, in milliseconds.
Sets this Game Object to the back of the display list, or the back of its parent container.
Being at the back means it will render below everything else.
This method does not change this Game Objects depth value, it simply alters its list position.
Sets this Game Object to be at the top of the display list, or the top of its parent container.
Being at the top means it will render on-top of everything else.
This method does not change this Game Objects depth value, it simply alters its list position.
Sets the vertex round mode of this Game Object. This is used by the WebGL Renderer to determine how to round the vertex positions.
The vertex round mode to set. Can be 'off', 'safe', 'safeAuto', 'full' or 'fullAuto'.
Sets the visibility of this Game Object.
An invisible Game Object will skip rendering, but will still process update logic.
The visible state of the Game Object.
Removes all listeners.
Toggle a boolean value for the given key within this Game Objects Data Manager. If the key doesn't already exist in the Data Manager then it is toggled from false.
If the Game Object has not been enabled for data (via setDataEnabled) then it will be enabled
before setting the value.
If the key doesn't already exist in the Data Manager then it is created.
When the value is first set, a setdata event is emitted from this Game Object.
The key to toggle the value for.
Returns a JSON representation of the Game Object.
To be overridden by custom GameObjects. Allows base objects to be used in a Pool.
args
Update the elapse timer for this game object. This should be called automatically by the preUpdate method.
Override this method to create more advanced time management, or set it to a NOOP function to disable the timer update. If you want to control animations with a tween or input system, disabling the timer update could be useful.
The current time in milliseconds.
The time since the last update, in milliseconds.
Whether this Game Object will render filters.
This is true if it has active filters,
and if the renderFilters property is also true.
Checks if this Game Object should round its vertices,
based on the given Camera and the vertexRoundMode of this Game Object.
This is used by the WebGL Renderer to determine how to round the vertex positions.
You can override this method in your own custom Game Object classes to provide custom logic for vertex rounding.
A SpriteGPULayer GameObject. This is a WebGL only GameObject. It is optimized for rendering very large numbers of quads following simple tween animations. It is suited to complex backgrounds with animation.
A SpriteGPULayer is a composite object that contains a collection of Member objects. It stores the rendering data for these objects in a GPU buffer, and renders them in a single draw call. Because it only updates the GPU buffer when necessary, it is up to 100 times faster than rendering the objects individually. Avoid changing the contents of the SpriteGPULayer frequently, as this requires the whole buffer to be updated.
The layer can generally perform well with a million small quads. The exact performance will depend on the device and the size of the quads. If the quads are large, the layer will be fill-rate limited. Avoid drawing more than a few million pixels per frame.
When populating the SpriteGPULayer, use
addMemberto add a new member to the top of the layer. You should populate the layer all at once, and leave it unchanged, rather than frequently adding and removing members, because it is expensive to update the buffer.Rather than create a new
SpriteGPULayer.Memberobject for eachaddMembercall, you can reuse the same object. This is more efficient, because creating millions of objects has a major performance cost and may cause garbage collection issues.Notes on modifying the SpriteGPULayer:
The following operations are expensive. They require some or all of the buffer to be updated:
addDataaddMembereditMemberpatchMemberresizeremoveMembersMembers are added at the end of the buffer. Removed members are spliced out of the buffer, causing the whole buffer to be updated. The index of later members will change if you remove an earlier member. If you need to maintain a structure, such as a grid of tiles, it's best to "remove" a member by setting its scaleX, scaleY, and alpha to 0. It is still rendered, but it does not fill any pixels.
Changes to a small segment of the buffer are less expensive. The buffer is split into several segments, and each segment can be updated independently. Editing and patching members will only update the segments that contain the members being edited. Updating occurs at render time, so edits all happen at once. This can reduce the amount of data that needs to be updated, but it is still more expensive than not updating the buffer at all. If you're updating a large number of segments, it may be more efficient to call
setAllSegmentsNeedUpdateand update the whole buffer at once rather than make several segment updates in a row.The animations in the initial member data are used to compile the shader and
frameDataTexture. If you add new animations after the initial compilation, the shader and texture will be rebuilt, which is expensive.Notes on textures:
This layer gains much of its speed from inflexibility. It can only use one texture, and that texture must be a single image. It cannot use multi-atlas textures.
Further, if the texture is not a power of two in size, some texture seaming may occur if you line up sprites exactly. This is because the GPU precision is limited by binary logic, and texture coordinates will only be perfectly accurate for power of two textures. This can be avoided by adding/extruding a pixel of padding around each frame in the texture, or by using a power of two texture.
Which should you use?