Bonus Project: Sprite Animation

What This Is

Everything you have drawn this quarter has been a rectangle or a circle. This is where that stops. You load a picture, cut four frames out of it, and show them one after another fast enough that a character appears to walk.

There is no game here. There is a character, a floor, and two keys. What you get is the technique every 2D game in existence is built on, which is worth more than another dodging game.

This is extra credit and it is optional. Nothing later in the course depends on it.

Before You Start

You need everything through session 23. Tables, loops, held-key input, and functions.

Get the sprite sheet

Right-click this image and save it into your project folder as sprite-sheet.png. It is 256 by 64 — four frames of 64 by 64, side by side, on a transparent background.

Draw your own instead if you would rather — anything four frames wide with square frames will work, and the code does not care what is in them. If you take one from the internet, write down where it came from and whether you were allowed to use it. That question does not go away when you leave this class.

Two new calls, and one new idea

love.graphics.newImage(path): Loads a picture from a file in your project folder. Do it once, in love.load — never in love.draw.
love.graphics.newQuad(x, y, w, h, sw, sh): A quad is a rectangle cut out of an image. It is not a picture — it is instructions for which part of one to draw.

The idea worth stopping on: there is one image in memory, loaded once, and four little descriptions of where to look inside it. Animation is not four pictures. It is one picture and a number that changes.

Copy template-game and rename it bp-sprite-animation. The sprite sheet goes in that folder, next to main.lua.

Build It

Five stages, and the whole file is printed at the end of every one. Run it after each stage — a stage that works is worth more than three stages you cannot test.

Type it rather than pasting it. The reading you do on the way is the whole point, and pasting skips all of it. When something breaks, the listing at the end of the stage is what your file should look like.

1. Get one frame on screen

sheet = love.graphics.newImage("sprite-sheet.png")
sheet:setFilter("nearest", "nearest")

for i = 1, 4 do
    frames[i] = love.graphics.newQuad(
        (i - 1) * 64, 0, 64, 64, sheet:getDimensions()
    )
end

Then draw quad number 1 somewhere and look at it. If you see the whole sheet, you drew the image instead of the quad. If you see nothing, the file is not in the folder or the name does not match — and LÖVE will have told you so on a blue screen.

setFilter("nearest", "nearest") is what keeps the pixels sharp when you scale it up. Leave it out once and see the difference; the blurry version is what every engine does by default and it is almost never what you want for pixel art.

The whole file after stage 1:

1
local sheet
2
local frames = {}
3

4
function love.load()
5
    sheet = love.graphics.newImage("sprite-sheet.png")
6
    sheet:setFilter("nearest", "nearest")
7

8
    for i = 1, 4 do
9
        frames[i] = love.graphics.newQuad(
10
            (i - 1) * 64, 0, 64, 64, sheet:getDimensions()
11
        )
12
    end
13
end
14

15
function love.draw()
16
    love.graphics.setColor(1, 1, 1)
17
    love.graphics.draw(sheet, frames[1], 300, 340, 0, 4, 4, 32, 32)
18
end
19

20
function love.keypressed(key)
21
    if key == "escape" then
22
        love.event.quit()
23
    end
24
end

2. Cycle the frames

timer = timer + dt

if timer > FRAME_TIME then
    timer = 0
    frame = frame + 1

    if frame > 4 then
        frame = 1
    end
end

This is a counter with a wrap, which you have written before — it is the same shape as a loop index, except it lives across frames instead of inside one. FRAME_TIME = 0.11 is about nine frames a second, which reads as a walk.

The whole file after stage 2:

1
local sheet
2
local frames = {}
3
local frame = 1
4
local timer = 0
5
local FRAME_TIME = 0.11
6

7
function love.load()
8
    sheet = love.graphics.newImage("sprite-sheet.png")
9
    sheet:setFilter("nearest", "nearest")
10

11
    for i = 1, 4 do
12
        frames[i] = love.graphics.newQuad(
13
            (i - 1) * 64, 0, 64, 64, sheet:getDimensions()
14
        )
15
    end
16
end
17

18
function love.update(dt)
19
    timer = timer + dt
20

21
    if timer > FRAME_TIME then
22
        timer = 0
23
        frame = frame + 1
24

25
        if frame > 4 then
26
            frame = 1
27
        end
28
    end
29
end
30

31
function love.draw()
32
    love.graphics.setColor(1, 1, 1)
33
    love.graphics.draw(sheet, frames[frame], 300, 340, 0, 4, 4, 32, 32)
34
end
35

36
function love.keypressed(key)
37
    if key == "escape" then
38
        love.event.quit()
39
    end
40
end

3. Move, and face the right way

love.graphics.draw(sheet, frames[frame], x, y, 0, 4 * facing, 4, 32, 32)

That call has a lot of arguments and every one earns its place: the sheet, which quad, where, no rotation, the x scale, the y scale, and the point inside the frame that lands on x and y.

facing is 1 or −1. A negative x scale flips the picture, which is why you do not need a second set of frames for walking left — and why the last two arguments are 32, 32: it flips around its own middle rather than swinging off to one side.

The whole file after stage 3:

1
local sheet
2
local frames = {}
3
local frame = 1
4
local timer = 0
5
local FRAME_TIME = 0.11
6

7
local x = 300
8
local y = 340
9
local facing = 1
10
local walking = false
11

12
function love.load()
13
    sheet = love.graphics.newImage("sprite-sheet.png")
14
    sheet:setFilter("nearest", "nearest")
15

16
    for i = 1, 4 do
17
        frames[i] = love.graphics.newQuad(
18
            (i - 1) * 64, 0, 64, 64, sheet:getDimensions()
19
        )
20
    end
21
end
22

23
function love.update(dt)
24
    walking = false
25

26
    if love.keyboard.isDown("left") then
27
        x = x - 220 * dt
28
        facing = -1
29
        walking = true
30
    end
31

32
    if love.keyboard.isDown("right") then
33
        x = x + 220 * dt
34
        facing = 1
35
        walking = true
36
    end
37

38
    timer = timer + dt
39

40
    if timer > FRAME_TIME then
41
        timer = 0
42
        frame = frame + 1
43

44
        if frame > 4 then
45
            frame = 1
46
        end
47
    end
48
end
49

50
function love.draw()
51
    love.graphics.setColor(0.3, 0.35, 0.45)
52
    love.graphics.rectangle("fill", 0, y + 128, 800, 6)
53

54
    love.graphics.setColor(1, 1, 1)
55
    love.graphics.draw(sheet, frames[frame], x, y, 0, 4 * facing, 4, 32, 32)
56
end
57

58
function love.keypressed(key)
59
    if key == "escape" then
60
        love.event.quit()
61
    end
62
end

4. Stand still when you are standing still

Only advance the timer while a key is held. When nothing is pressed, snap back to frame 1.

Skip this and the character marches on the spot forever, which looks wrong in a way that is hard to name until you fix it.

The whole file after stage 4:

1
local sheet
2
local frames = {}
3
local frame = 1
4
local timer = 0
5
local FRAME_TIME = 0.11
6

7
local x = 300
8
local y = 340
9
local facing = 1
10
local walking = false
11

12
function love.load()
13
    sheet = love.graphics.newImage("sprite-sheet.png")
14
    sheet:setFilter("nearest", "nearest")
15

16
    for i = 1, 4 do
17
        frames[i] = love.graphics.newQuad(
18
            (i - 1) * 64, 0, 64, 64, sheet:getDimensions()
19
        )
20
    end
21
end
22

23
function love.update(dt)
24
    walking = false
25

26
    if love.keyboard.isDown("left") then
27
        x = x - 220 * dt
28
        facing = -1
29
        walking = true
30
    end
31

32
    if love.keyboard.isDown("right") then
33
        x = x + 220 * dt
34
        facing = 1
35
        walking = true
36
    end
37

38
    if not walking then
39
        frame = 1
40
        return
41
    end
42

43
    timer = timer + dt
44

45
    if timer > FRAME_TIME then
46
        timer = 0
47
        frame = frame + 1
48

49
        if frame > 4 then
50
            frame = 1
51
        end
52
    end
53
end
54

55
function love.draw()
56
    love.graphics.setColor(0.3, 0.35, 0.45)
57
    love.graphics.rectangle("fill", 0, y + 128, 800, 6)
58

59
    love.graphics.setColor(1, 1, 1)
60
    love.graphics.draw(sheet, frames[frame], x, y, 0, 4 * facing, 4, 32, 32)
61
end
62

63
function love.keypressed(key)
64
    if key == "escape" then
65
        love.event.quit()
66
    end
67
end

5. Show your working

love.graphics.draw(sheet, 20, 20, 0, 2, 2)
love.graphics.setColor(1, 0.9, 0.2)
love.graphics.rectangle("line", 20 + (frame - 1) * 128, 20, 128, 128)

Draw the whole sheet in the corner at double size with a box round the frame currently in use. This is a debugging tool that happens to look good, and it makes the thing you cannot otherwise see — which frame is up — visible.

The Whole Program

Every stage above, finished and in one piece. This is the exact file the picture below came from — nothing is left out and nothing is abbreviated.

1
local sheet
2
local frames = {}
3
local frame = 1
4
local timer = 0
5
local FRAME_TIME = 0.11
6

7
local x = 300
8
local y = 340
9
local facing = 1
10
local walking = false
11

12
function love.load()
13
    sheet = love.graphics.newImage("sprite-sheet.png")
14
    sheet:setFilter("nearest", "nearest")
15

16
    for i = 1, 4 do
17
        frames[i] = love.graphics.newQuad(
18
            (i - 1) * 64, 0, 64, 64, sheet:getDimensions()
19
        )
20
    end
21
end
22

23
function love.update(dt)
24
    walking = false
25

26
    if love.keyboard.isDown("left") then
27
        x = x - 220 * dt
28
        facing = -1
29
        walking = true
30
    end
31

32
    if love.keyboard.isDown("right") then
33
        x = x + 220 * dt
34
        facing = 1
35
        walking = true
36
    end
37

38
    if not walking then
39
        frame = 1
40
        return
41
    end
42

43
    timer = timer + dt
44

45
    if timer > FRAME_TIME then
46
        timer = 0
47
        frame = frame + 1
48

49
        if frame > 4 then
50
            frame = 1
51
        end
52
    end
53
end
54

55
function love.draw()
56
    love.graphics.setColor(0.3, 0.35, 0.45)
57
    love.graphics.rectangle("fill", 0, y + 128, 800, 6)
58

59
    love.graphics.setColor(1, 1, 1)
60
    love.graphics.draw(sheet, frames[frame], x, y, 0, 4 * facing, 4, 32, 32)
61

62
    love.graphics.draw(sheet, 20, 20, 0, 2, 2)
63
    love.graphics.setColor(1, 0.9, 0.2)
64
    love.graphics.rectangle("line", 20 + (frame - 1) * 128, 20, 128, 128)
65
end
66

67
function love.keypressed(key)
68
    if key == "escape" then
69
        love.event.quit()
70
    end
71
end

What Success Looks Like

The four source frames across the top with the current one boxed, and the character drawn from that same frame at four times the size, mid-stride, walking right. One image file, one number, and the number is 4.

Then Make It Yours

Draw your own frames. Any editor. Keep the frames square and the same size, and your code will not need a single change — which is the strongest possible argument for having written it with 64 in one place rather than four.
Two animations. A second row in the sheet for jumping or standing. The quad's y is what picks the row, and that is one more number.
Tie the speed to the movement. Walk faster, cycle faster. One division. It is a tiny change and it looks enormously better.
Jump. A vertical speed, gravity added every frame, and a floor to stop at. That is three lines and it is where a character turns into a platformer.
A second character. Same sheet, same quads, different position and frame number. Nothing is loaded twice, and understanding why that is true is the whole point of quads.

The walkthrough is not the submission. Getting the program running earns the credit; what you change afterward is what makes it worth reading. Hand in the folder and a sentence saying what you added, or what broke and what you did about it.