sprites

sget = "spritesheet get"

 sget( x, y )

This function will return the color number (0-15) of a single pixel currently drawn at the (x,y) coordinate specified on the sprite sheet. If you request a pixel that is outside of the screen, then sget will return 0 (zero).

Example:

sset(10,20,8)              --draw at (10,20), a red pixel
pixel_color = sget(10,20)  --returns 8 (red)

sset = "spritesheet set"

 sset( x, y, [color] )

This function will draw a single pixel to the (x,y) coordinate specified, but on the spritesheet not the screen. You can specify the color as a number (0-15) according to the palette. The default color is the current draw color (last color set by either color() function or by a drawing function's color argument).

Example:

sset(10,0,8)    --draw at (10,0), a red pixel
sset(11,1)    --draw at (11,1), still a red pixel
spr(1,20,30)    --draw sprite 1 at (20,30)

color(12)       --set draw color to #12, blue
sset(16,0)      --draw at (16,0), a blue pixel
sset(17,1)      --draw at (17,1), a blue pixel
spr(2,20,38)    --draw sprite 2 at (20,38)

As you can see, you can specify the draw color multiple ways. In the first example we use the color argument in the sset function the first line and the same color is carried over to the second sset. In the second example, we set the color first with the color function which is also carried over to sset.

Simple Animations

This function can save you some sprite sheet space if you want to animate just one or two pixels, such as this flashing light on an ambulance.

Here is how you could make this animation using 2 sprites. We show the sprite editor to manually do what the code is doing: changing between drawing sprite 1 and sprite 2.

cls()
car=1
counter=0

function _update()
	counter+=.1
	if counter<1 then
		car=1    --sprite 1
	elseif counter<2 then
		car=2    --sprite 2
	else
		counter=0
	end
end

function _draw()
	spr(car,20,30)
end

And here is how you can save a tile on the sprite sheet by doing the same animation with only 1 sprite and the sset() function. We show the sprite editor to manually do what the code is doing: swapping one pixel in the sprite sheet to a different color.

cls()
car=1
counter=0

function _update()
	counter+=.1
	if counter<1 then
		sset(12,0,8) --red
	elseif counter<2 then
		sset(12,0,12) --blue
	else
		counter=0
	end
end

function _draw()
	spr(car,20,30)
end

So if your animations are as simple as swapping a couple colored pixels around, consider using this function to help be more efficient with your sprite sheet space.

fget = "flag get"

 fget( sprite, [flag] )

This function will compare if the sprite has the flag set or not. If you provide a flag argument then it will return true if that flag is set on that sprite and false if it is not set on that sprite.

If you do not provide a flag argument, then the fget function will return a single bitfield of all flags that are set on that sprite.

Example:

-- bomb= sprite 1, flag 0 on

print( fget(1,0) ) --true
print( fget(1,1) ) --false

Getting Multiple Flags

You can set the flags manually in the sprite editor or with the function fset, which will do the same. You can have multiple flags turned on for a single sprite. Here we will turn on flag 0 for the bomb sprite and multiple flags on for the man sprite in the sprite editor.

When you hover your mouse over the flags in the sprite editor, the flag number will be displayed at the bottom left of the screen. Notice that flags 1, 3, 5, and 7 are all turned on for the man sprite. So when we ask fget for any of those specific flags it will return true. If we want to know all of the flags that are turned on we don't specify the flag argument in our call for fget, and we need to understand the bitfield number that is returned.

Now let's use this set up to make calls to fget and see what is returned.

-- bomb= sprite 1, flag 0
-- man = sprite 2, flag 1,3,5,7 

--bomb
print( fget(1,0) ) --true
print( fget(1,1) ) --false
print( fget(1) )   --1

--man
print( fget(2,0) ) --false
print( fget(2,5) ) --true
print( fget(2) )   --170

Notice that when we specify a flag to be checked, the returning value is either true or false, but when we left out that argument, the bomb sprite returned the number 1, and the man sprite returned the number 170. These numbers are bitfields that represent exactly which flags are turned on and they will be a number between 0 (no flags turned on) and 255 (all flags turned on).

To help read these numbers, here is a table to understand which flag or flags are on depending on the bitfield returned.

By adding the bitfield value of the flags that you want turned on, you will get the unique number that is returned by a sprite that has those specific flags turned on. In our example, the bomb sprite returned the bitfield 1 because only flag 0 was turned on. And the man sprite returned 170 because:

fset = "flag set"

 fset( sprite, [flag], value )

This function will set the sprite's flag(s) on or off. If you provide a flag argument then it will set the value of that specific flag to the value.

If you do not provide a flag argument, then the fset function will apply the value to all flags.

Example:

In this example you can see that we manually turned on flag 0 for the bomb sprite. So the first time we get the flag 0, it returns as true. Then we set it false using fset, and get it again and find that it is now false, turned off. So we can change which flags are on for sprites in code while the game is running.

-- bomb= sprite 1, flag 0 on
print( fget(1,0) ) --true

fset(1,0,false) --set flag 0 to false 
print( fget(1,0) ) --false

You can easily turn all flags on or off for a single sprite like this:

fset( 1,true )  --all on
fset( 1,false ) --all off

Setting Multiple Flags

You can set the flags manually in the sprite editor or with this function fset. You can have multiple flags turned on for a single sprite. Here we have flag 0 turned on for the bomb sprite and multiple flags turned on for the man sprite in the sprite editor. We can do the same thing in code like this:

-- bomb= sprite 1, flag 0
-- man = sprite 2, flag 1,3,5,7 

--bomb
fset( 1,0,true ) --flag 0, on

--man
fset( 2,1,true ) --flag 1, on
fset( 2,3,true ) --flag 3, on
fset( 2,5,true ) --flag 5, on
fset( 2,7,true ) --flag 7, on

To avoid many calls to the same function, there is an easier way to set multiple flags. To do this, we need to understand the bitfield number that we can use to represent multiple boolean states (flags as true or false).

Bitfields represent exactly which flags are turned on and they will be a number between 0 (all flags turned off) and 255 (all flags turned on).

Here is a table of flag numbers and their corresponding bitfield values.

By adding the bitfield value of the flags that you want turned on, you will get the unique number that is returned by a sprite that has those specific flags turned on. In our example, the bomb sprite has only flag 0 turned on so the bitfield value is simply 1.

fset( 1, 1 ) --flag 0, true

And the man sprite we want multiple flags turned on, specifically flags 1, 3, 5 and 7. If you refer to the table above, we can add up the bitfield values of each of those flags and get the total bitfield value that represents those exact flags turned on, which is 170 because:

Now we can show you how you can simplify the multiple calls to the function for each flag, down to a single call using a bitfield value.

--set multiple flags using multiple calls
fset( 2,1,true ) --flag 1, on
fset( 2,3,true ) --flag 3, on
fset( 2,5,true ) --flag 5, on
fset( 2,7,true ) --flag 7, on

--set multiple flags using 1 call
fset( 2,170 ) --flags 1,3,5,7 on

Notice that when we don't specify a flag in the arguments, and instead after the sprite number, we only provide the number 170 which will be taken as the value argument, not the flag argument.

spr = "sprite"

spr(sprite_number, x, y, [w, h], [flip_x], [flip_y])

This function will draw a sprite from the sprite sheet to the screen. You must provide the (x,y) position of where to draw the sprite. The pixel at the screen position (x,y) will be the top left pixel of the sprite. When flipping the sprite, this screen position is not changed, only how the sprite is drawn at this same position.

You may optionally provide w (width) and h (height) arguments to draw sprites larger than a single 8x8 pixel tile. Note that width and height arguments are given as tiles, not pixels, so a width of 2 and height of 3 will draw a 16x24 pixel sprite.

You may optionally provide flip arguments. Note that you must provide width and height arguments before these flip arguments, even if you want the default width and height.

Example:

-- 16x16 sprite

spr( 1, 10, 20, 2, 2 )