Skip to content

Sprites

Sprites Guides

Using Sprites Examples & Guides

Functions

Call For All Sprites

Call For All Sprites

Call the supplied function for all sprites in the current pack.

Parameters

NameTypeDescription
fnSprite Float FunctionThe sprite function to call on all sprites.
valFloatThe value passed to the function for each sprite.

Signatures

void call_for_all_sprites(sprite_float_function *fn, float val)

Call For All Sprites

Call the supplied function for all sprites in the current pack.

Parameters

NameTypeDescription
fnSprite FunctionThe sprite function to call on all sprites.

Signatures

void call_for_all_sprites(sprite_function *fn)

Call On Sprite Event

Register a procedure to be called when an events occur on any sprite.

Parameters

NameTypeDescription
handlerSprite Event HandlerThe function to call when any sprite raises an event

Signatures

void call_on_sprite_event(sprite_event_handler *handler)

Center Point

Returns the center point of the passed in sprite. This is based on the sprite’s Position, Width and Height.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Point 2d

Signatures

point_2d center_point(sprite s)

Create Sprite

Create Sprite

Creates a sprite for the passed in bitmap image. The sprite will use the cell information within the bitmap if it is animated at a later stage.

This version of create_sprite will initialise the sprite to use pixel level collisions, no animations, and have one layer named ‘layer1’. This version of the constructor will assign a default name to the sprite for resource management purposes.

Parameters

NameTypeDescription
layerBitmapThe bitmap for the sprite’s image.

Return Type - Sprite

Signatures

sprite create_sprite(bitmap layer)

Create Sprite

Creates a sprite for the passed in bitmap image. The sprite will use the cell information within the bitmap if it is animated at a later stage. This version of Create Sprite will initialise the sprite to use pixel level collisions, the specified animation template, the layer have name ‘layer1’.

This version of the constructor will assign a default name to the sprite for resource management purposes.

Parameters

NameTypeDescription
layerBitmapThe bitmap for the sprite’s image.
aniAnimation ScriptThe animation script for the sprite’s animations.

Return Type - Sprite

Signatures

sprite create_sprite(bitmap layer, animation_script ani)

Create Sprite

Creates a sprite for the passed in bitmap image. The sprite will use the cell information within the bitmap if it is animated at a later stage.

This version of create_sprite will initialise the sprite to use pixel level collisions, no animations, and have one layer named ‘layer1’. This version of the constructor will assign a default name to the sprite for resource management purposes.

Parameters

NameTypeDescription
bitmap_nameStringThe name of the bitmap to use as the sprite’s layer

Return Type - Sprite

Signatures

sprite create_sprite(const string &bitmap_name)

Create Sprite

Creates a sprite for the passed in bitmap image. The sprite will use the cell information within the sprite if it is animated at a later stage. This version of create_sprite will initialise the sprite to use pixel level collisions, no animation, the layer have name ‘layer1’.

Parameters

NameTypeDescription
nameStringThe name of the sprite for resource management.
layerBitmapThe bitmap for the sprite’s image.

Return Type - Sprite

Signatures

sprite create_sprite(const string &name, bitmap layer)

Create Sprite

Creates a sprite for the passed in bitmap image. The sprite will use the cell information within the sprite if it is animated at a later stage. This version of create_sprite will initialise the sprite to use pixel level collisions, the specified animation template, the layer have name ‘layer1’.

Parameters

NameTypeDescription
nameStringThe name of the sprite for resource management.
layerBitmapThe bitmap for the sprite’s image.
aniAnimation ScriptThe animation script for the sprite’s animations.

Return Type - Sprite

Signatures

sprite create_sprite(const string &name, bitmap layer, animation_script ani)

Create Sprite

Creates a sprite. The bitmap_name is used to indicate the bitmap the sprite will use, and the animation_name is used to indicate which animation_script to use.

Parameters

NameTypeDescription
bitmap_nameStringThe name of the bitmap to use as the sprite’s image.
animation_nameStringThe name of the animation script to use for this
sprite.

Return Type - Sprite

Signatures

sprite create_sprite(const string &bitmap_name, const string &animation_name)

Create Sprite Pack

Create a new sprite_pack with a given name. This pack can then be selected and used to control which sprites are drawn/updated in the calls to draw_all_sprites and update_all_sprites.

Parameters

NameTypeDescription
nameStringThe name of the new sprite pack.

Signatures

void create_sprite_pack(const string &name)

Current Sprite Pack

Returns the name of the currently selected sprite_pack.

Return Type - String

Signatures

string current_sprite_pack()

Draw All Sprites

draws all of the sprites in the current sprite pack. Packs can be switched to select between different sets of sprites.

Signatures

void draw_all_sprites()

Draw Sprite

Draw Sprite

Draws the sprite at its position in the game offset by a given amount. Only use this method when you want to draw the sprite displaced from its location in your game. Otherwise you should change the sprite’s location and then use the standard ”draw_sprite” routine.

Parameters

NameTypeDescription
sSpriteThe sprite to draw.
offsetVector 2dThe amount to offset the sprite.

Signatures

void draw_sprite(sprite s, const vector_2d &offset)

Draw Sprite

Draws the sprite at its location in the world. This is affected by the position of the camera and the sprites current location.

This is the standard routine for drawing sprites to the screen and should be used in most cases.

Parameters

NameTypeDescription
sSpriteThe sprite to draw.

Signatures

void draw_sprite(sprite s)

Draw Sprite

Draws the sprite at its position in the game offset by a given amount. Only use this method when you want to draw the sprite displaced from its location in your game. Otherwise you should change the sprite’s location and then use the standard Draw Sprite routine.

Parameters

NameTypeDescription
sSpriteThe sprite to draw.
x_offsetDoubleThe amount to offset on the x axis.
y_offsetDoubleThe amount to offset on the y axis.

Signatures

void draw_sprite(sprite s, double x_offset, double y_offset)

Free All Sprites

Releases all of the sprites that have been loaded.

Signatures

void free_all_sprites()

Free Sprite

Free the resources associated with a sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to be destroyed.

Signatures

void free_sprite(sprite s)

Free Sprite Pack

Frees the sprite pack and all of its sprites.

Parameters

NameTypeDescription
nameStringThe name of the sprite pack to destroy.

Signatures

void free_sprite_pack(const string &name)

Has Sprite

Determines if SplashKit has a sprite for the supplied name. This checks against all sprites, those loaded without a name are assigned a default.

Parameters

NameTypeDescription
nameStringThe name of the sprite to locate.

Return Type - Boolean

Signatures

bool has_sprite(const string &name)

Has Sprite Pack

Indicates if a given sprite_pack has already been created.

Parameters

NameTypeDescription
nameStringThe name for the sprite pack.

Return Type - Boolean

Signatures

bool has_sprite_pack(const string &name)

Move Sprite

Move Sprite

moves the sprite as indicated by its velocity. You can call this directly ot alternatively, this action is performed when the sprite is updated using the ”update_sprite” routine.

Parameters

NameTypeDescription
sSpriteThe sprite to move.

Signatures

void move_sprite(sprite s)

Move Sprite

Moves the sprite a given distance based on the value passed in rather than based on the sprite’s velocity. Typically this method is used to apply other movement actions to the sprite and the velocity of the sprite is used the intended movement of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to move.
distanceVector 2dThe vector that represents the direction and distance to
move the sprite.

Signatures

void move_sprite(sprite s, const vector_2d &distance)

Move Sprite

Moves the sprite a percentage of a given distance based on the value passed in rather than based on the sprite’s velocity. Typically this method is used to apply other movement actions to the sprite and the velocity of the sprite is used the intended movement of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to move.
distanceVector 2dThe vector that represents the direction and distance to
move the sprite.
pctFloatThe percentage of the distance to move the sprite.

Signatures

void move_sprite(sprite s, const vector_2d &distance, float pct)

Move Sprite

Moves the sprite as indicated by a percentage of its velocity. You can call this directly ot alternatively, this action is performed when the sprite is updated using the ”update_sprite” routines that require a percentage.

Parameters

NameTypeDescription
sSpriteThe sprite to move.
pctFloatThe percentage of the sprite’s velocity to move.

Signatures

void move_sprite(sprite s, float pct)

Move Sprite To

This method moves a sprite to a given position in the game.

Parameters

NameTypeDescription
sSpriteThe sprite to move.
xDoubleThe sprite’s new x location.
yDoubleThe sprite’s new y location.

Signatures

void move_sprite_to(sprite s, double x, double y)

Select Sprite Pack

Selects the named sprite_pack (if it has been created). The selected sprite_pack determines which sprites are drawn and updated with the draw_all_sprites and update_all_sprites code.

Parameters

NameTypeDescription
nameStringThe name of the sprite pack to select.

Signatures

void select_sprite_pack(const string &name)

Sprite Add Layer

Adds a new layer to the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to add the layer to.
new_layerBitmapThe new layer’s bitmap.
layer_nameStringThe name of the new layer.

Return Type - Integer

Signatures

int sprite_add_layer(sprite s, bitmap new_layer, const string &layer_name)

Sprite Add To Velocity

Alters the current velocity of the sprite, adding the passed in vector_2d to the current velocity. When the sprite is updated (see Update Sprite) this vector_2d is used to move the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueVector 2dThe amount to add to the sprite’s velocity.

Signatures

void sprite_add_to_velocity(sprite s, const vector_2d &value)

Sprite Add Value

Sprite Add Value

Adds a new kind of value to the sprite

Parameters

NameTypeDescription
sSpriteThe sprite to change.
nameStringThe name of the new value to store in the sprite.

Signatures

void sprite_add_value(sprite s, const string &name)

Sprite Add Value

Adds a new kind of value to the sprite, setting the initial value to the value passed in.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
nameStringThe name of the new value to store in the sprite.
init_valFloatThe initial value.

Signatures

void sprite_add_value(sprite s, const string &name, float init_val)

Sprite Anchor Point

Returns the anchor point of the sprite. This is the point around which the sprite rotates. This is in sprite coordinates, so as if the sprite is drawn at 0,0.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Point 2d

Signatures

point_2d sprite_anchor_point(sprite s)

Sprite Anchor Position

The sprite anchor position, is the location of the anchor point in world coordinates, based upon the position of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to find where the anchor is in world coordinates

Return Type - Point 2d

Signatures

point_2d sprite_anchor_position(sprite s)

Sprite Animation Has Ended

Indicates if the sprites animation has ended.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Boolean

Signatures

bool sprite_animation_has_ended(sprite s)

Sprite Animation Name

Returns the name of the sprite’s current animation.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - String

Signatures

string sprite_animation_name(sprite s)

Sprite At

Determines if a sprite is at a given point.

Parameters

NameTypeDescription
sSpriteThe sprite to test
ptPoint 2dThe point to check (in world coordinates)

Return Type - Boolean

Signatures

bool sprite_at(sprite s, const point_2d &pt)

Sprite Bring Layer Forward

Sends the layer specified forward in the visible layer order.

Parameters

NameTypeDescription
sSpriteThe sprite to change
visible_layerIntegerThe visible layer to bring forward

Signatures

void sprite_bring_layer_forward(sprite s, int visible_layer)

Sprite Bring Layer To Front

Sends the layer specified to the front in the visible layer order.

Parameters

NameTypeDescription
sSpriteThe sprite to change
visible_layerIntegerThe visible layer to bring to the front

Signatures

void sprite_bring_layer_to_front(sprite s, int visible_layer)

Sprite Call On Event

Register a procedure to call when events occur on the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to add the handler to.
handlerSprite Event HandlerThe function to call when this sprite raises an event.

Signatures

void sprite_call_on_event(sprite s, sprite_event_handler *handler)

Sprite Circle

Gets a circle in the bounds of the base layer of the indicated sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Circle

Signatures

circle sprite_circle(sprite s)

Sprite Collision Bitmap

Returns the bitmap used by the sprite to determine if it has collided with other objects in the game.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Bitmap

Signatures

bitmap sprite_collision_bitmap(sprite s)

Sprite Collision Circle

Gets a circle in the bounds of the indicated sprite’s collision rectangle.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Circle

Signatures

circle sprite_collision_circle(sprite s)

Sprite Collision Kind

Returns the kind of collision used with this sprite. This is used when determining if the sprite has collided with other objects in the game.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Collision Test Kind

Signatures

collision_test_kind sprite_collision_kind(sprite s)

Sprite Collision Rectangle

Returns the collision rectangle for the specified sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Rectangle

Signatures

rectangle sprite_collision_rectangle(sprite s)

Sprite Current Cell

Returns the current animation cell for an animated sprite. The cell is updated when the sprite’s animation data is updated.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Integer

Signatures

int sprite_current_cell(sprite s)

Sprite Current Cell Rectangle

Returns a rectangle of the current cell within the sprite’s image. This is used to determine what part of the bitmap should be used when the sprite is drawn.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Rectangle

Signatures

rectangle sprite_current_cell_rectangle(sprite s)

Sprite Dx

Returns the X value of the sprite’s velocity.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_dx(sprite s)

Sprite Dy

Returns the Y value of the sprite’s velocity.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_dy(sprite s)

Sprite Has Value

Indicates if the sprite has a value with the given name.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
nameStringThe name of the value to check.

Return Type - Boolean

Signatures

bool sprite_has_value(sprite s, string name)

Sprite Heading

Returns the direction the sprite is heading in degrees.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_heading(sprite s)

Sprite Height

The current height of the sprite (aligned to the Y axis).

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Integer

Signatures

int sprite_height(sprite s)

Sprite Hide Layer

Sprite Hide Layer

Hide the specified layer of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to hide the layer of.
nameStringThe name of the layer to hide.

Signatures

void sprite_hide_layer(sprite s, const string &name)

Sprite Hide Layer

Hide the specified layer of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to hide the layer of.
idIntegerThe index of the layer to hide.

Signatures

void sprite_hide_layer(sprite s, int id)

Sprite Layer

Sprite Layer

Returns the bitmap of the indicated layer of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the layer from
nameStringThe name of the layer to fetch

Return Type - Bitmap

Signatures

bitmap sprite_layer(sprite s, const string &name)

Sprite Layer

Returns the bitmap of the indicated layer of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the layer from
idxIntegerThe index of the layer

Return Type - Bitmap

Signatures

bitmap sprite_layer(sprite s, int idx)

Sprite Layer Circle

Sprite Layer Circle

Gets a circle in the bounds of the indicated layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
nameStringThe name of the layer.

Return Type - Circle

Signatures

circle sprite_layer_circle(sprite s, const string &name)

Sprite Layer Circle

Gets a circle in the bounds of the indicated layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
idxIntegerThe index of the layer.

Return Type - Circle

Signatures

circle sprite_layer_circle(sprite s, int idx)

Sprite Layer Count

Returns the number of layers within the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the layer count from.

Return Type - Integer

Signatures

int sprite_layer_count(sprite s)

Sprite Layer Height

Sprite Layer Height

The height of a given layer of the sprite (aligned to the Y axis).

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
nameStringThe name of the layer to get the details of.

Return Type - Integer

Signatures

int sprite_layer_height(sprite s, const string &name)

Sprite Layer Height

The height of a given layer of the sprite (aligned to the Y axis).

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
idxIntegerThe index of the layer to get the details of.

Return Type - Integer

Signatures

int sprite_layer_height(sprite s, int idx)

Sprite Layer Index

Returns the index of the specified layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the layer from
nameStringThe name of the layer to get the index of

Return Type - Integer

Signatures

int sprite_layer_index(sprite s, const string &name)

Sprite Layer Name

Returns the name of the specified layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the layer name from
idxIntegerThe index of the layer you want the name of

Return Type - String

Signatures

string sprite_layer_name(sprite s, int idx)

Sprite Layer Offset

Sprite Layer Offset

Gets the offset of the specified layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
nameStringThe name of the layer to get the offset of.

Return Type - Vector 2d

Signatures

vector_2d sprite_layer_offset(sprite s, const string &name)

Sprite Layer Offset

Gets the offset of the specified layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
idxIntegerThe index of the layer to get the offset of.

Return Type - Vector 2d

Signatures

vector_2d sprite_layer_offset(sprite s, int idx)

Sprite Layer Rectangle

Sprite Layer Rectangle

Gets a rectangle that surrounds the indicated layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
nameStringThe name of the layer.

Return Type - Rectangle

Signatures

rectangle sprite_layer_rectangle(sprite s, const string &name)

Sprite Layer Rectangle

Gets a rectangle that surrounds the indicated layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
idxIntegerThe index of the layer.

Return Type - Rectangle

Signatures

rectangle sprite_layer_rectangle(sprite s, int idx)

Sprite Layer Width

Sprite Layer Width

The width of a given layer of the sprite (aligned to the X axis).

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
nameStringThe name of the layer to get the details of.

Return Type - Integer

Signatures

int sprite_layer_width(sprite s, const string &name)

Sprite Layer Width

The width of a given layer of the sprite (aligned to the X axis).

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
idxIntegerThe index of the layer to get the details of.

Return Type - Integer

Signatures

int sprite_layer_width(sprite s, int idx)

Sprite Location Matrix

Returns a matrix that can be used to transform points into the coordinate space of the passed in sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Matrix 2d

Signatures

matrix_2d sprite_location_matrix(sprite s)

Sprite Mass

This indicates the mass of the sprite for any of the collide methods from Physics. The mass of two colliding sprites will determine the relative velocitys after the collision.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_mass(sprite s)

Sprite Move From Anchor Point

Indicates if the sprite is moved from its anchor point, or from its top left. When this returns true the location of the sprite will indicate its anchor point. When this returns false the location of the sprite is its top left corner.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details of.

Return Type - Boolean

Signatures

bool sprite_move_from_anchor_point(sprite s)

Sprite Move To

This void starts the sprite moving to the indicated destination point, over a specified number of seconds. When the sprite arrives it will raise the sprite_arrived event.

Parameters

NameTypeDescription
sSpriteThe sprite to move.
ptPoint 2dThe sprite’s destination.
taking_secondsFloatThe time the sprite should take to get to pt.

Signatures

void sprite_move_to(sprite s, const point_2d &pt, float taking_seconds)

Sprite Name

Returns the name of the sprite. This name is used for resource management and can be used to interact with the sprite in various routines.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - String

Signatures

string sprite_name(sprite s)

Sprite Named

Returns the Sprite with the specified name.

Parameters

NameTypeDescription
nameStringThe name of the sprite to locate.

Return Type - Sprite

Signatures

sprite sprite_named(const string &name)

Sprite Offscreen

Returns true if the sprite is entirely off the current screen.

Parameters

NameTypeDescription
sSpriteThe sprite to test.

Return Type - Boolean

Signatures

bool sprite_offscreen(sprite s)

Sprite On Screen At

Sprite On Screen At

Returns true if a pixel of the Sprite s is at the screen location specified (pt), which is converted to a world location.

Parameters

NameTypeDescription
sSpriteThe sprite to test.
ptPoint 2dThe location in screen coordinates to check.

Return Type - Boolean

Signatures

bool sprite_on_screen_at(sprite s, const point_2d &pt)

Sprite On Screen At

Returns true if a pixel of the Sprite s is at the screen location specified.

Parameters

NameTypeDescription
sSpriteThe sprite to test.
xDoubleThe x location in screen coordinates to check.
yDoubleThe y location in screen coordinates to check.

Return Type - Boolean

Signatures

bool sprite_on_screen_at(sprite s, double x, double y)

Sprite Position

Returns the sprite’s position.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Point 2d

Signatures

point_2d sprite_position(sprite s)

Sprite Replay Animation

Sprite Replay Animation

Restart the sprite’s current animation, this will play a sound if the first cell of the animation is associated with a sound effect.

Parameters

NameTypeDescription
sSpriteThe sprite to replay the animation of.

Signatures

void sprite_replay_animation(sprite s)

Sprite Replay Animation

Restart the sprite’s current animation, this will play a sound if with_sound is true and the first cell of the animation is associated with a sound effect.

Parameters

NameTypeDescription
sSpriteThe sprite to replay the animation of.
with_soundBooleanIf false, the animation will not play associated sound
effects when restarted.

Signatures

void sprite_replay_animation(sprite s, bool with_sound)

Sprite Rotation

This indicates the angle of rotation of the sprite. This will rotate any images of the sprite before drawing, which can be very slow. avoid using this method with bitmap based sprites where possible.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_rotation(sprite s)

Sprite Scale

This indicates the scale of the sprite. This will scale any images of the sprite before drawing, which can be very slow. avoid using this method with bitmap based sprites where possible.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_scale(sprite s)

Sprite Screen Rectangle

Returns the rectangle representing the location of the sprite on the screen.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Rectangle

Signatures

rectangle sprite_screen_rectangle(sprite s)

Sprite Send Layer Backward

Sends the layer specified backward in the visible layer order.

Parameters

NameTypeDescription
sSpriteThe sprite to change
visible_layerIntegerThe visible layer to send to backward

Signatures

void sprite_send_layer_backward(sprite s, int visible_layer)

Sprite Send Layer To Back

Sends the layer specified to the back in the visible layer order.

Parameters

NameTypeDescription
sSpriteThe sprite to change
visible_layerIntegerThe visible layer to send to back

Signatures

void sprite_send_layer_to_back(sprite s, int visible_layer)

Sprite Set Anchor Point

Allows you to set the anchor point for the sprite. This is the point around which the sprite rotates. This is in sprite coordinates, as if the sprite is drawn at 0,0.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
ptPoint 2dThe new anchor point in sprite coordinates.

Signatures

void sprite_set_anchor_point(sprite s, const point_2d &pt)

Sprite Set Collision Bitmap

Sets the bitmap used by the sprite to determine if it has collided with other objects in the game. By default the collision_bitmap is set to the bitmap from the sprite’s first layer.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
bmpBitmapThe new collision bitmap for the sprite.

Signatures

void sprite_set_collision_bitmap(sprite s, bitmap bmp)

Sprite Set Collision Kind

Sets the kind of collision used with this sprite. This is used when determining if the sprite has collided with other objects in the game.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueCollision Test KindThe new kind of collision test for this sprite.

Signatures

void sprite_set_collision_kind(sprite s, collision_test_kind value)

Sprite Set Dx

Sets the X value of the sprite’s velocity.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new x component of the sprite’s velocity.

Signatures

void sprite_set_dx(sprite s, float value)

Sprite Set Dy

Sets the Y value of the sprite’s velocity.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new y component of the sprite’s velocity.

Signatures

void sprite_set_dy(sprite s, float value)

Sprite Set Heading

Alters the direction the sprite is heading without changing the speed.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new angle for the sprite’s velocity — distance remains the
same.

Signatures

void sprite_set_heading(sprite s, float value)

Sprite Set Layer Offset

Sprite Set Layer Offset

Sets the offset of the specified layer. The offset is used when the layer is drawn in the sprite, and moves the image relative to the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
nameStringThe name of the layer to change.
valueVector 2dThe new offset.

Signatures

void sprite_set_layer_offset(sprite s, const string &name, const vector_2d &value)

Sprite Set Layer Offset

Sets the offset of the specified layer.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
idxIntegerThe index of the layer to change.
valueVector 2dThe new offset.

Signatures

void sprite_set_layer_offset(sprite s, int idx, const vector_2d &value)

Sprite Set Mass

Allows you to change the mass of a sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new mass for the sprite.

Signatures

void sprite_set_mass(sprite s, float value)

Sprite Set Move From Anchor Point

Allows you to indicate if the sprite is moved from its anchor point, or from its top left.

When set to true the location of the sprite will be its anchor point. When set to false the location of the sprite is its top left corner.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueBooleanThe value to set this option.

Signatures

void sprite_set_move_from_anchor_point(sprite s, bool value)

Sprite Set Position

Sets the sprite’s position.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valuePoint 2dThe new location for the sprite.

Signatures

void sprite_set_position(sprite s, const point_2d &value)

Sprite Set Rotation

Allows you to change the rotation of a sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new rotation angle for the sprite

Signatures

void sprite_set_rotation(sprite s, float value)

Sprite Set Scale

Allows you to change the scale of a sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new scale for the sprite.

Signatures

void sprite_set_scale(sprite s, float value)

Sprite Set Speed

Alters the speed of the sprite without effecting the direction.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new speed of the sprite — direction will remain the same.

Signatures

void sprite_set_speed(sprite s, float value)

Sprite Set Value

Assigns a value to the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
nameStringThe name of the value to change
valFloatThe new value.

Signatures

void sprite_set_value(sprite s, const string &name, float val)

Sprite Set Velocity

Sets the current velocity of the sprite. When the sprite is updated (see Update Sprite) this vector_2d is used to move the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueVector 2dThe new sprite velocity.

Signatures

void sprite_set_velocity(sprite s, const vector_2d &value)

Sprite Set X

Sets the X position of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new x location.

Signatures

void sprite_set_x(sprite s, float value)

Sprite Set Y

Sets the Y position of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
valueFloatThe new sprite y.

Signatures

void sprite_set_y(sprite s, float value)

Sprite Show Layer

Sprite Show Layer

Show the specified layer of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to show the layer of.
nameStringThe layer to show.

Return Type - Integer

Signatures

int sprite_show_layer(sprite s, const string &name)

Sprite Show Layer

Show the specified layer of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to show the layer of.
idIntegerThe index to show.

Return Type - Integer

Signatures

int sprite_show_layer(sprite s, int id)

Sprite Speed

Returns the current speed (distance travelled per update) of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_speed(sprite s)

Sprite Start Animation

Sprite Start Animation

Start playing an animation from the sprite’s animation template. This will play a sound effect if the first cell of the animation has a sound.

Parameters

NameTypeDescription
sSpriteThe sprite to start the animation of.
namedStringThe name of the animation to start from the animation script.

Signatures

void sprite_start_animation(sprite s, const string &named)

Sprite Start Animation

Start playing an animation from the sprite’s animation template. The with_sound parameter determines whether to play a sound effect if the first cell of the animation has a sound.

Parameters

NameTypeDescription
sSpriteThe sprite to start the animation of.
namedStringThe name of the animation to start from the animation script.
with_soundBooleanIf false, the animation will not play associated sound
effects when started.

Signatures

void sprite_start_animation(sprite s, const string &named, bool with_sound)

Sprite Start Animation

Start playing an animation from the sprite’s animation template. This will play a sound effect if the first cell of the animation has a sound.

Parameters

NameTypeDescription
sSpriteThe sprite to start the animation of.
idxIntegerThe index of the animation to start from the animation script.

Signatures

void sprite_start_animation(sprite s, int idx)

Sprite Start Animation

Start playing an animation from the sprite’s animation template. The with_sound parameter determines whether to play a sound effect if the first cell of the animation has a sound.

Parameters

NameTypeDescription
sSpriteThe sprite to start the animation of.
idxIntegerThe index of the animation to start from the animation script.
with_soundBooleanIf false, the animation will not play associated sound
effects when started.

Signatures

void sprite_start_animation(sprite s, int idx, bool with_sound)

Sprite Stop Calling On Event

Removes an event handler from the sprite, stopping events from this sprite calling the indicated method.

Parameters

NameTypeDescription
sSpriteThe sprite to remove the handler from
handlerSprite Event HandlerThe function to remove from this sprites handlers

Signatures

void sprite_stop_calling_on_event(sprite s, sprite_event_handler *handler)

Sprite Toggle Layer Visible

Sprite Toggle Layer Visible

Toggle the visibility of the specified layer of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
nameStringThe name of the layer to toggle.

Signatures

void sprite_toggle_layer_visible(sprite s, const string &name)

Sprite Toggle Layer Visible

Toggle the visibility of the specified layer of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to change.
idIntegerThe index of the layer to toggle.

Signatures

void sprite_toggle_layer_visible(sprite s, int id)

Sprite Value

Returns the indicated value of the sprite

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
nameStringThe name of the value to fetch.

Return Type - Float

Signatures

float sprite_value(sprite s, const string &name)

Sprite Value Count

Returns the number of sprite’s values.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Integer

Signatures

int sprite_value_count(sprite s)

Sprite Velocity

Returns the current velocity of the sprite. When the sprite is updated (see Update Sprite) this vector_2d is used to move the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Vector 2d

Signatures

vector_2d sprite_velocity(sprite s)

Sprite Visible Index Of Layer

Sprite Visible Index Of Layer

Returns the index (z-order) of the sprite’s layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
nameStringThe name of the layer to get the z index of.

Return Type - Integer

Signatures

int sprite_visible_index_of_layer(sprite s, const string &name)

Sprite Visible Index Of Layer

Returns the index (z-order) of the sprite’s layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
idIntegerThe index of the layer to get the z index of.

Return Type - Integer

Signatures

int sprite_visible_index_of_layer(sprite s, int id)

Sprite Visible Layer

Returns the index of the n’th (idx parameter) visible layer.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
idxIntegerThe index of the visible layer to fetch.

Return Type - Integer

Signatures

int sprite_visible_layer(sprite s, int idx)

Sprite Visible Layer Count

Returns the number of layers that are currently visible for the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Integer

Signatures

int sprite_visible_layer_count(sprite s)

Sprite Visible Layer Id

Returns the id of the layer at index idx that is currently visible. Index 0 is the background, with larger indexes moving toward the foreground. This returns -1 if there are no visible layers.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.
idxIntegerThe index of the visible layer.

Return Type - Integer

Signatures

int sprite_visible_layer_id(sprite s, int idx)

Sprite Width

The current Width of the sprite (aligned to the X axis).

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Integer

Signatures

int sprite_width(sprite s)

Sprite X

Returns the X position of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_x(sprite s)

Sprite Y

Returns the Y position of the sprite.

Parameters

NameTypeDescription
sSpriteThe sprite to get the details from.

Return Type - Float

Signatures

float sprite_y(sprite s)

Stop Calling On Sprite Event

Removes an global event handler, stopping events calling the indicated void.

Parameters

NameTypeDescription
handlerSprite Event HandlerThe function to remove from the list of sprite event handlers.

Signatures

void stop_calling_on_sprite_event(sprite_event_handler *handler)

Update All Sprites

Update All Sprites

Update all of the sprites in the current sprite pack.

Signatures

void update_all_sprites()

Update All Sprites

Update all of the sprites in the current sprite pack, passing in a percentage value to indicate the percentage to update.

Parameters

NameTypeDescription
pctFloatThe percentage of the update to apply.

Signatures

void update_all_sprites(float pct)

Update Sprite

Update Sprite

Update the position and animation details of the sprite. This will play a sound effect if the new cell of the animation has a sound.

Parameters

NameTypeDescription
sSpriteThe sprite to update.

Signatures

void update_sprite(sprite s)

Update Sprite

Update the position and animation details of the sprite. This will play a sound effect if the new cell of the animation has a sound and with_sound is true.

Parameters

NameTypeDescription
sSpriteThe sprite to update
with_soundBooleanIf false, animations will not play associated sound
effects when updated.

Signatures

void update_sprite(sprite s, bool with_sound)

Update Sprite

Update the position and animation details of the sprite by a given percentage of a single unit of movement/animation. This will play a sound effect if the new cell of the animation has a sound.

Parameters

NameTypeDescription
sSpriteThe sprite to update.
pctFloatThe percent to update.

Signatures

void update_sprite(sprite s, float pct)

Update Sprite

Update the position and animation details of the sprite by a given percentage of a single unit of movement/animation. This will play a sound effect if the new cell of the animation has a sound and with_sound is true.

Parameters

NameTypeDescription
sSpriteThe sprite to update.
pctFloatThe percent to update.
with_soundBooleanIf false, animations will not play associated sound
effects when updated.

Signatures

void update_sprite(sprite s, float pct, bool with_sound)

Update Sprite Animation

Update Sprite Animation

Updates the animation details of the sprite. This will play a sound effect if the new cell of the animation has a sound.

Parameters

NameTypeDescription
sSpriteThe sprite to update.

Signatures

void update_sprite_animation(sprite s)

Update Sprite Animation

Update the animation details of the sprite. This will play a sound effect if the new cell of the animation has a sound and with_sound is true.

Parameters

NameTypeDescription
sSpriteThe sprite to update.
with_soundBooleanIf false, animations will not play associated sound
effects when updated.

Signatures

void update_sprite_animation(sprite s, bool with_sound)

Update Sprite Animation

Update the animation details of the sprite by a given percentage of a single unit of movement/animation. This will play a sound effect if the new cell of the animation has a sound.

Parameters

NameTypeDescription
sSpriteThe sprite to update.
pctFloatThe percent to update.

Signatures

void update_sprite_animation(sprite s, float pct)

Update Sprite Animation

Update the position and animation details of the sprite by a given percentage of a single unit of movement/animation. This will play a sound effect if the new cell of the animation has a sound and with_sound is true.

Parameters

NameTypeDescription
sSpriteThe sprite to update.
pctFloatThe percent to update.
with_soundBooleanIf false, animations will not play associated sound
effects when updated.

Signatures

void update_sprite_animation(sprite s, float pct, bool with_sound)

Vector From Center Sprite To Point

Returns a Vector 2d that is the difference in location from the center of the sprite s to the point pt.

Parameters

NameTypeDescription
sSpriteThe sprite that is at the start of the vector.
ptPoint 2dThe point that is at the end of the vector.

Return Type - Vector 2d

Signatures

vector_2d vector_from_center_sprite_to_point(sprite s, const point_2d &pt)

Vector From To

Returns a Vector 2d that is the difference in the position of two sprites (s1 and s2).

Parameters

NameTypeDescription
s1SpriteThe sprite that is at the start of the vector.
s2SpriteThe sprite that is at the end of the vector.

Return Type - Vector 2d

Signatures

vector_2d vector_from_to(sprite s1, sprite s2)

Types

Collision Test Kind

This enumeration can be used to set the kind of collisions a sprite will check for.

ConstantValueDescription
PIXEL_COLLISIONSThe sprite will check for collisions with its collision bitmap.
AABB_COLLISIONSThe sprite will check for collisions with a bounding box around the sprite.

This enumeration can be used to set the kind of collisions a sprite will check for.


Sprite

Sprites combine an image, with position and animation details. You can create a sprite using Create Sprite, draw it with Draw Sprite, move it using the Sprite Velocity with Update Sprite, and animate it using an Animation Script.

Sprites combine an image, with position and animation details. You can create a sprite using Create Sprite, draw it with Draw Sprite, move it using the Sprite Velocity with Update Sprite, and animate it using an Animation Script.


Sprite Event Handler

The sprite_event_handler function pointer is used when you want to register to receive events from a Sprite.

The sprite_event_handler function pointer is used when you want to register to receive events from a Sprite.


Sprite Event Kind

This enumeration contains a list of all of the different kinds of events that a Sprite can raise. When the event is raised the assocated sprite_event_kind value passed to the event handler to indicate the kind of event that has occurred.

ConstantValueDescription
SPRITE_ARRIVED_EVENTThe sprite has arrived at the end of a move
SPRITE_ANIMATION_ENDED_EVENTThe Sprite’s animation has ended.
SPRITE_TOUCHED_EVENTThe Sprite was touched
SPRITE_CLICKED_EVENTThe Sprite was touched

This enumeration contains a list of all of the different kinds of events that a Sprite can raise. When the event is raised the assocated sprite_event_kind value passed to the event handler to indicate the kind of event that has occurred.


Sprite Float Function

The sprite single function is used with sprite packs to provide a procedure to be called for each of the Sprites in the sprite pack, where a float value is required.

The sprite single function is used with sprite packs to provide a procedure to be called for each of the Sprites in the sprite pack, where a float value is required.


Sprite Function

sprite_function is used with SpritePacks to provide a procedure to be called for each of the Sprites in the SpritePack.

sprite_function is used with SpritePacks to provide a procedure to be called for each of the Sprites in the SpritePack.