Skip to content

Intro to Sprites

Sprites are a widget that let you include sprites in your panel. They are very straightforward.

Constructor

The signature is as follows:

UISprite(_id, _x, _y, _sprite, _width=0, _height=0, _starting_frame=0, _relative_to=UI_DEFAULT_ANCHOR_POINT, _time_source_parent=time_source_global)

where:

  • id is the string ID.
  • x and y are the offsets with respect to the anchor point. Note that, as directed in the Fundamentals page, your sprites should have its origin point set to top left, to allow for correct positioning in gooey.
  • sprite is the sprite asset to use.
  • width and height are optional variables. If set, the sprite will be scaled; if not, the sprite will be drawn at its original size.
  • starting_frame is an optional argument to specify the starting index of the sprite to render (0 if not specified).
  • relative_to is the anchor point, as usual from the UI_RELATIVE_TO enum.
  • time_source_parent is the time source to use in order to animate the sprite. Valid values are time_source_game and time_source_global.

Drawing nine sliced sprites

If you choose a width and height, the sprite will be stretched to match that size. However, if your sprite has nine slice configured, the rendering will use that setting, preventing potential distortions in the sprite rendering. Enable or disable nine slice as needed on the sprites you need to render.

Animation

The gooey system animates each sprite using its own time source. This time source will be set according to the speed configured in the IDE. If the speed is 0, it will not create a time source.

You can set the animation speed at runtime, by calling setAnimationSpeed. The speed can be set in frames or milliseconds, the same than with GameMaker time sources.

You can optionally set an animation length, if you want to limit the animation to a certain number of frames, using setAnimationLength. Additionally, you can set the animation step, i.e., how many frames are skipped in the animation. For example, if your sprite has six frames, and frames 1,3,5 are an animation you want to show (while 2,4,6 are not), you can set the starting frame to 0, then set setAnimationLength to 3 and setAnimationStep to 2, and finally set the speed to run the animation at.

Changing animation parameters

Note that changes will not be visually applied until you restart the animation using animationRestart.

Setting blend and alpha

Remember that all widgets have an image blend and image alpha properties, so you can configure the sprite blend and alpha by using the Widget methods setImageBlend and setImageAlpha.

Example

For this I used ToffeeCraft's pet assets. I imported the sprite sheet of the cat into GameMaker and, after slicing it into individual frames, I had a 64x64 sprite with 12 frames. The objective for this example is to display a sleeping cat and have it wake up on click. The sleeping animation is in frames 9-12. I set up 4 FPS in the inspector, then created the sprite widget and set up the animation length like so:

1
2
3
4
5
6
7
8
var _panel = new UIPanel("TestPanel", 0,0, 400, 300, grey_panel, UI_RELATIVE_TO.MIDDLE_CENTER);

var _scale = 3;
var _w = sprite_get_width(spr_Cats)*_scale;
var _h = sprite_get_height(spr_Cats)*_scale;
var _sprite = new UISprite("CatSprite", 0, 0, spr_Cats, _w,_h, 8, UI_RELATIVE_TO.MIDDLE_CENTER);
_sprite.setAnimationLength(4);
_panel.add(_sprite);

After doing this, we add a callback to the cat sprite. I use a simple call_later function, to get the cat's sprite widget animation parameters to original, so he can go back to sleep, after 30 frames:

 9
10
11
12
13
14
_sprite.setCallback(UI_EVENT.LEFT_RELEASE, function() {
    ui_get("CatSprite").setAnimationStartingFrame(5).setAnimationLength(1).animationRestart();
    call_later(30, time_source_units_frames, function() {
        ui_get("CatSprite").setAnimationStartingFrame(8).setAnimationLength(4).animationRestart();
    });
});

The result is the following. Left click the cat to wake him up (temporarily)...