New SBS update is complete, follow updates here.

How to use SPANIM

Root / Submissions / [.]

SPANIM. It's not a command the jedi would tell you. It's a sith legend. that many people know how to use. It's useful for making smooth sprite movements, making animations that can play while other functions run, and even making cutscenes. This guide assumes you know the basics of SmileBASIC, sprites, and variable types.

SPANIM Overview

SPANIM is a command that lets you animate sprites. The command only needs to be run once for them to start. At any time during an animation, you can use the SPSTOP command to pause the animation and SPSTART to resume it. Let's break down the average SPANIM command:
SPANIM [sprite ID],[animation type],[animation data],[loop]
The sprite ID is the ID of the sprite you want to animate. The animation type is what part of the sprite you want to animate. There are 8 animation types:
  • 0 or "XY": SPOFS coordinates, or where the sprite is on-screen (needs two values)
  • 1 or "Z": Z coordinate, or the depth of the sprite in 3D mode.
  • 2 or "UV": SPCHR, or where on the sprite sheet this sprite's graphics are from (needs two values)
  • 3 or "I": SPDEF definition number
  • 4 or "R": SPROT angle, or the rotation of the sprite (in degrees)
  • 5 or "S": SPSCALE width and height (2.0 = 2x the size) (needs two values)
  • 6 or "C": SPCOLOR / sprite color
  • 7 or "V": SPVAR variable 7 (Don't know what this is? Don't worry, you're not missing out on much.)
You can use either the number or the string as the animation type. The loop parameter is how many times you want the animation to play. If you put 0, the animation will loop forever until you stop it with SPSTOP. The animation will even continue running while the program is stopped! Finally, the biggest part of the SPANIM command:

Animation data

SPANIM ... [time],[data],[time],[data], ...
Animation data consists of two parts, repeated until the end of the animation. The first is a time value. It dictates how long to wait before moving on to the next keyframe. If there's a positive time value, it sets the data value to the animation's data value and waits for the time value. If there's a negative time value, the transition to the next data value is smoothed over the amount of time you selected. The next is a data value. (Depending on the animation type, there can be two data values per keyframe)

Wait, keyframes?

Oh, sorry for not explaining that. Each part of the animation is called a keyframe. Keyframes are points where the data value needs to change. You can also use DATA labels or one-dimensional arrays to store animation data. If you use DATA labels, be sure to make the first DATA the number of keyframes there are in the animation.

An example

Sprite does a flip!
SPSET 0,413 ' Fish
SPOFS 0,200,120 ' Move the fish to center of screen
SPHOME 0,8,8 ' When the fish rotates, they rotate around their center
'(The fish is 16x16, and 8, 8 is the middle of the sprite)

' And now, the actual SPANIM command...
SPANIM 0,"R",-60,360
' The SPANIM command says:
SPANIM 0, ' Animating using the fish sprite...
"R",      ' To rotate...
-60,      ' with smooth animation...
60, 360,  ' 360 degrees over 60 frames...
0         ' FOREVER!!!
[img]https://giant.gfycat.com/SpicyThirstyAsianporcupine.gif[/img] Now the fish will rotate forever! That... doesn't look healthy... (The gif is slow for some reason.)

Relative animation

By adding 8 to the animation type, (or adding a + onto the end, if you're using strings) you can make relative animations. Relative animations add to the initial value instead of just resetting it.

SPANIM quirks

0 time values

For some reason, you cannot use a time of 0 to set the initial value of the animation. That means you can't use this:
SPANIM 0,"XY",0,5,5,-15,100,50,1
Instead, do this:
SPOFS 0,5,5:SPANIM 0,"XY",-15,100,50,1
(or the equivalent of that, like SPCHR if you're using I)

Positive time values

Unlike negative time values, positive time values animate as soon as they are reached, not when the end of the delay is reached.

Smooth animation of SPCHRs

Despite it having pretty much no use, you can smoothly animate SPCHRs. It just flips through all the sprites between the current sprite and the final sprite.

Relative animation

Relative animation is only relative to the original value, so if you did this:
SPANIM 0,"XY+",-30,16,0,-30,-16,0
it won't go back to the starting point at the end, but go 16 pixels to the left of it.

Overriding animations

If you run a SPANIM command twice or use the animation type's equivalent command, the first SPANIM will be overriden by the second command.
SPANIM 0,"XY",-60,5,5
' Later in the code...
SPOFS 0,30,5
SPSTART will not resume the first animation.

What about BGANIM?

It's pretty much the same as SPANIM but with BG layers and a few less animation types. I've never found it that useful, but if you need it, the guide gives you a rough idea of the differences between the two commands. Also, note that colors can't have an alpha channel.


Thank you for checking out my guide on SPANIM! If you have any questions about SPANIM or if you find a problem with this guide, please feel free to comment! Sorry if this was unclear. Half of it was written on a smartphone. I may make a tool to make SPANIMs easily in the future. Liked this tutorial? Check out my games and programs! Again, thanks for reading.

I'd like to know what animating "V" does!

Replying to:Sam
I'd like to know what animating "V" does!
changes the SPVAR for variable 7 basically, SPVAR(ID,7) will be automatically changed ('animated').