Construct 3 icon

Construct 3

Documentation

Sprite

Published 23 Aug, 2017
1,507 words
~6-10 mins

The Sprite object is an animatable image that appears in the game. It is one of the most important objects for most Construct games. It is used to make most visual elements in a game, such as the player, enemies, projectiles, explosions and non-tiling scenery. (Tiled scenery is much better done with the Tiled Background object.)

If a Sprite has a single animation with a single frame, it simply shows an image without animating. However, multiple animations can be added to Sprite objects with the Animations editor.

All instances of Sprite objects share their animations. In other words, there is a single set of images comprising the animations which belongs to the object type, and these images are referenced by instances.

Sprites can have effects applied. For more information, see Effects.

Sprite properties

Animations

Click the Edit link to open the Animations editor for the object. All instances of the object type share a single set of animations.

Size

Click the Make 1:1 link to size the selection at original size (100%). This makes the width and height of the object the same as its first animation frame image.

Initially visibile

Set whether the object is shown (visible) or hidden (invisible) when the layout starts.

Initial animation

Set the initially displaying animation.

Initial frame

Set the initially displaying animation frame from the object's initial animation. This is a zero-based index, so the first frame is 0.

Enable collisions

Enable or disable collisions for the object. Disabling collisions means no collision events will register for the object nor will any behaviors on the object register collisions with solids or jump-thrus. Disabling collisions does not improve performance unless there are some events or behaviors that test collisions.

Preview Paid plans only

Enable to run a preview of the initial animation directly in the Layout View.

Sprite conditions

For conditions in common to other objects, see Common conditions.

Compare frame

Compare the current animation frame number, which is a zero-based index (the first frame is 0).

Compare speed

Compare the speed of the current animation, in animation frames per second. Animations which are playing backwards (e.g. with ping-pong animations) have a negative speed.

Is flipped

Is mirrored

True if the object has been flipped or mirrored with the Set flipped or Set mirrored actions.

Is playing

True if a given animation is currently set. Animations are identified by their name (case insensitive).

On any finished

Triggered when any animation reaches the end. Looping animations do not finish.

On finished

Triggered when a given animation reaches the end. Looping animations do not finish. Animations are identified by their name (case insensitive).

On frame changed

Triggered whenever the animation switches to another frame while the animation is playing.

Collisions enabled

True if the object's collisions are currently enabled.

Is overlapping another object

Is overlapping at offset

True if any instance is overlapping any instance of another object. The collision polygons are taken in to account if set, as well as the object's size and rotation. The offset variant will test for an overlap at an offset from the first object. For example, testing for an overlap at an offset of (100, 0) will temporarily move the object to the right 100 pixels, test for the overlap, then move it back again.

On collision with another object

Triggered upon the first time any instance starts overlapping any instance of another object. The collision polygons are taken in to account if set, as well as the object's size and rotation.

On image URL loaded

Triggered when Load image from URL finishes downloading the image and is ready to display it.

Sprite actions

For actions common to other objects, see Common actions.

Set animation

Change the currently playing animation to another animation. Animations are identified by their name (case insensitive). The new animation can either play from the beginning or from the same frame number as the last animation was on (current frame).

Set flipped

Set whether the object image appears vertically flipped or normal. This also affects image points and the collision polygon. This is a shortcut for inverting the height (a flipped Sprite's height is a negative size).

Set mirrored

Set whether the object image appears horizontally mirrored or normal. This is useful for platform games. Mirroring also affects image points and the collision polygon. This is a shortcut for inverting the width (a mirrored Sprite's width is a negative size).

Set frame

Set the current zero-based animation frame number that is showing. The animation will continue to play at its current speed.

Set repeat-to frame

Set the frame to return to when looping in the current animation. This essentially changes the Repeat to property of the animation in the Animation Editor. It is especially useful when reversing animations, since the default of repeating to the first frame is no longer suitable. Instead when playing looping animations in reverse it is more useful to repeat to the last frame of the animation (so the animation actually repeats, instead of getting stuck on the first frame).

Set speed

Set the playback rate of the current animation, in animation frames per second. Instances can have different animation speeds. You can also use negative speeds, which causes the animation to play backwards. Note in this case repeating animations should set the Repeat to frame at the end of the animation, otherwise by default it repeats to frame 0 (the start of the animation), causing the animation to stop after playing in reverse.

Start

If the current animation is stopped, start playing the animation again. Playback can either resume from the current frame, or restart from the beginning.

Stop

Stop the current animation from playing. The object will be left showing the current animation frame.

Spawn another object

Create a new instance of a given object type. The new instance is created at the current object's position and also set to the same angle. The created object can be on any layer (chosen by its name or its zero-based number), and it can be positioned by an image point instead of the object's origin (chosen by its name or number). If a Family Paid plans only is created, a random object type in the family is picked.

Set scale

Sets the width and height to a multiple of the object's original size, similar to zooming the object proportionally. For example, if the object is 50x100, Set scale to 2 will set its size to 100x200, and Set scale to 0.1 will set its size to 5x10.

Load image from URL

Load an image from a given URL. The current animation frame will be replaced with the image. It is not shown until the image has finished downloading, and On image URL loaded triggers. Images loaded from different domains are subject to the same cross-domain restrictions as AJAX requests - for more information see the section on cross-domain in the AJAX object. Data URIs can also be passed as an image, e.g. from a canvas snapshot or webcam image. The Size parameter sets whether the Sprite object will be set to the image size when it loads, or whether to keep its current size and stretch the image.

Set collisions enabled

Enable or disable collisions for the object. Disabling collisions means no collision events will register for the object nor will any behaviors on the object register collisions with solids or jump-thrus. Disabling collisions does not improve performance unless there are some events or behaviors that test collisions.

Set solid collision filter

Enable or disable collisions with the Solid behavior according to tags. Specify tags using a string of space-separated tag names. In Inclusive mode, collisions are only enabled with solids that match any of the given tags; if no tags are specified, collisions are disabled with all solids. In Exclusive mode, collisions are disabled with solids that match any of the given tags; if no tags are specified, collisions are enabled for all solids (the default).

Sprite expressions

For expressions common to other objects, see common expressions.

AnimationFrame

The currently displaying zero-based animation frame number.

AnimationFrameCount

The number of animation frames in the current animation.

AnimationName

A string containing the name of the currently playing animation.

AnimationSpeed

The current playback rate of the current animation, in animation frames per second. If the animation is playing backwards (e.g. ping-pong animations), the animation speed is negative.

ImageWidth

ImageHeight

The original dimensions of the object (its current animation frame image size), in pixels. Since objects can be stretched at runtime causing the normal Width and Height expressions to return different values, these can be used to get the original size regardless of the stretched size.

ImagePointCount

Return the number of image points on the currently displaying animation frame of the object.

ImagePointX

ImagePointY

Retrieve the position of an image point on the currently displaying animation frame of the object. You can pass either the zero-based index of the image point, or a string of its name.