Activity 2.12: Shipping Your Game

The Idea

A folder on your machine is not something anyone can play. Two things stand between what you have and what you can hand to a friend: the game has to remember something between runs, and it has to travel as one file.

Both turn out to be one idea. The moment your game becomes a single file, it is living inside a read-only archive, and the folder it came from no longer exists as far as the code is concerned. Every decision on this page follows from that.

Where a game is allowed to write

You cannot write next to main.lua. Not because LÖVE is being strict, but because once you ship, main.lua is a compressed entry inside a zip file, and there is no "next to" to write to.

So LÖVE gives every game exactly one writable place, the save directory, somewhere in the operating system's per-user application data. Every path you hand to love.filesystem.write is relative to it, and there is no way to write outside it by accident.

Windows   %APPDATA%\LOVE\skynest
macOS     ~/Library/Application Support/LOVE/skynest
Linux     ~/.local/share/love/skynest

The last part of that path is the identity, and it is yours to choose in conf.lua. If you never set one, LÖVE makes one up from the name of the folder or the .love file your game arrived in, which works right up until the day you rename the folder and every saved game silently disappears. Setting t.identity is how you promise your players their save file survives you reorganizing your desktop.

Reading a file that might not be there

The first time anyone runs your game there is no save file, and that is not an error condition — it is the normal case, exactly once. love.filesystem.read returns the contents, or returns nil and a message. It does not raise. That is the same nil-plus-a-message convention Activity 1.12 met in io.open, and it means a missing high score costs you one or 0.

If you would rather ask before you read, that is what getInfo is for. It hands back a table with the type and size, or nil.

if love.filesystem.getInfo("highscore.txt") then
  -- it is there, and getInfo told you its size too
end

The one-liner that will ruin your day

Here is a bug worth more than the feature it hides in. love.filesystem.read returns two values — the contents and the number of bytes. And tonumber takes two arguments — the string and the base to read it in.

-- Looks tidy. Reads a saved 11 as base 2 and hands you 3.
local function loadHighScore()
  return tonumber(love.filesystem.read("highscore.txt")) or 0
end

-- Reads a saved 11 as eleven.
local function loadHighScore()
  local contents = love.filesystem.read("highscore.txt")
  return tonumber(contents) or 0
end

A call in the last argument position keeps all of its return values, which is the rule from Activity 1.7 arriving with teeth. So the tidy version does not read your high score in base ten. It reads it in a base equal to its own length, and I measured what that costs:

A saved score of 11 comes back as 3. Two bytes, base 2, and 11 in binary is three.
A saved score of 100 comes back as 9.
A saved score of 12 comes back as 0, because 2 is not a base-2 digit, so tonumber returns nil and the or 0 catches it.
A saved score of 7 does not come back at all. The game crashes on launch with bad argument #2 to 'tonumber' (base out of range), because one byte means base 1, and bases start at 2.

Every single-digit high score is a crash on the next launch. Not on the machine you wrote it on — that one already has a two-digit file. On somebody else's, the first time they play. Assigning to a local first is not verbosity. It is how you cut a function call down to one value.

A .love file is a zip

That is the entire format. Rename your zip to .love and LÖVE will run it, on any operating system, as long as the person has LÖVE installed. There is exactly one rule, and everybody breaks it once.

main.lua must be at the top of the archive, not inside a folder in it. LÖVE mounts the archive as the root of the game's file system, so if the zip contains skynest/main.lua then main.lua is not at the root and LÖVE shows you the no-game screen. You zip the contents of the folder, never the folder.

$ unzip -Z1 skynest.love   $ unzip -Z1 broken.love
enemy.lua                  skynest/
collision.lua              skynest/enemy.lua
ship.png                   skynest/.DS_Store
main.lua                   skynest/collision.lua
explode.wav                skynest/ship.png
conf.lua                   skynest/main.lua
shoot.wav                  skynest/explode.wav
hit.wav                    skynest/conf.lua
                           skynest/shoot.wav
                           skynest/hit.wav

Those are two real archives built from the same eight files. The difference is one cd, and the one on the right does not run. Those are archive listings — every unzip tool can show you one, whatever it calls the command. Note that the broken one also swept up a .DS_Store that macOS left lying in the folder; Windows leaves Thumbs.db and desktop.ini around in exactly the same way. Harmless here, but it tells you something about zipping a folder you have not looked inside.

One file further: fusing

A .love needs LÖVE installed. If you want to hand someone a program instead, you fuse: LÖVE's own executable and your .love are concatenated into one file, and LÖVE finds the zip stuck to its own back end when it starts. On Windows the whole operation is literally copy /b love.exe+skynest.love skynest.exe. On macOS you copy love.app and drop the .love inside it, in Contents/Resources.

The catch is that the rest of the files that shipped with LÖVE have to travel with your executable, and a macOS bundle you have not paid Apple to notarize will be refused by Gatekeeper on your friend's machine. For sharing a game you made for fun, the .love file is the better answer — it is one small file, it works on every platform at once, and it asks nothing of you.

Build

Two edits to main.lua, one to conf.lua, and then you package it. enemy.lua and collision.lua are untouched, and this is the last time you will open them.

Task 1: Finish conf.lua

Add t.identity so the save directory has a name you chose.
Add t.version. It is the version of LÖVE you built against. If someone runs your game on a future major release, LÖVE shows them a compatibility warning instead of a stack trace.

1
-- conf.lua
2

3
function love.conf(t)
4
  t.identity = "skynest"
5
  t.version = "11.5"
6

7
  t.window.width = 800
8
  t.window.height = 600
9
  t.window.title = "Skynest"
10
end

Task 2: Remember the best run

Add a highScore local to the program group, not the per-run group. It is the one number in this game that deliberately survives resetGame.
Write loadHighScore above love.load and call it there. Two lines, not one, for the reason above.
Show it on the HUD, under the score.
Run it. Best: 0, and nothing is written to disk yet — this task only reads.

1
-- main.lua
2

3
local Enemy = require("enemy")
4
local collision = require("collision")
5

6
local ship
7
local font
8
local titleFont
9
local sounds
10
local highScore
11
local spawnEvery = 0.8
12
local gameState = "menu"
13

14
local player
15
local bullets
16
local fireCooldown
17
local enemies
18
local spawnTimer
19
local score
20
local lives
21
local invuln
22
local shake
23

24
local function resetGame()
25
  player = { x = 400, y = 500, size = 40, speed = 300 }
26
  bullets = {}
27
  fireCooldown = 0
28
  enemies = {}
29
  spawnTimer = 0
30
  score = 0
31
  lives = 3
32
  invuln = 0
33
  shake = 0
34
end
35

36
local function loadHighScore()
37
  local contents = love.filesystem.read("highscore.txt")
38
  return tonumber(contents) or 0
39
end
40

41
function love.load()
42
  love.graphics.setBackgroundColor(0.05, 0.05, 0.1)
43
  math.randomseed(os.time())
44
  ship = love.graphics.newImage("ship.png")
45
  font = love.graphics.newFont(20)
46
  titleFont = love.graphics.newFont(48)
47
  love.graphics.setFont(font)
48

49
  sounds = {
50
    shoot = love.audio.newSource("shoot.wav", "static"),
51
    hit = love.audio.newSource("hit.wav", "static"),
52
    explode = love.audio.newSource("explode.wav", "static"),
53
  }
54
  sounds.shoot:setVolume(0.35)
55
  sounds.hit:setVolume(0.6)
56

57
  highScore = loadHighScore()
58
  resetGame()
59
end
60

61
function love.keypressed(key)
62
  if key == "escape" then
63
    love.event.quit()
64
  elseif key == "space" and gameState ~= "playing" then
65
    resetGame()
66
    gameState = "playing"
67
  end
68
end
69

70
function love.update(dt)
71
  shake = shake - dt
72

73
  if gameState ~= "playing" then
74
    return
75
  end
76

77
  if love.keyboard.isDown("left", "a") then
78
    player.x = player.x - player.speed * dt
79
  end
80
  if love.keyboard.isDown("right", "d") then
81
    player.x = player.x + player.speed * dt
82
  end
83

84
  local half = player.size / 2
85
  player.x = math.max(half, math.min(love.graphics.getWidth() - half, player.x))
86

87
  fireCooldown = fireCooldown - dt
88
  invuln = invuln - dt
89

90
  if love.keyboard.isDown("space") and fireCooldown <= 0 then
91
    table.insert(bullets, { x = player.x, y = player.y - 30, size = 6, speed = 500 })
92
    fireCooldown = 0.15
93
    sounds.shoot:clone():play()
94
  end
95

96
  for i = #bullets, 1, -1 do
97
    local b = bullets[i]
98
    b.y = b.y - b.speed * dt
99
    if b.y < -20 then
100
      table.remove(bullets, i)
101
    end
102
  end
103

104
  spawnTimer = spawnTimer - dt
105
  if spawnTimer <= 0 then
106
    table.insert(enemies, Enemy.new(math.random(40, love.graphics.getWidth() - 40)))
107
    spawnTimer = spawnEvery
108
  end
109

110
  for i = #enemies, 1, -1 do
111
    local e = enemies[i]
112
    e:update(dt)
113
    if e.y > love.graphics.getHeight() + 20 then
114
      table.remove(enemies, i)
115
    end
116
  end
117

118
  if invuln <= 0 then
119
    for i = #enemies, 1, -1 do
120
      if collision.overlaps(enemies[i], player) then
121
        table.remove(enemies, i)
122
        lives = lives - 1
123
        invuln = 2
124
        shake = 0.4
125
        sounds.explode:play()
126
        if lives <= 0 then
127
          gameState = "gameover"
128
        end
129
        break
130
      end
131
    end
132
  end
133

134
  for i = #enemies, 1, -1 do
135
    for j = #bullets, 1, -1 do
136
      if collision.overlaps(enemies[i], bullets[j]) then
137
        table.remove(bullets, j)
138

139
        local thud = sounds.hit:clone()
140
        thud:setPitch(0.9 + math.random() * 0.3)
141
        thud:play()
142

143
        enemies[i].hp = enemies[i].hp - 1
144
        if enemies[i].hp <= 0 then
145
          table.remove(enemies, i)
146
          score = score + 1
147
        end
148
        break
149
      end
150
    end
151
  end
152
end
153

154
local function drawHud()
155
  love.graphics.setColor(1, 1, 1)
156
  love.graphics.print("Score: " .. score, 10, 12)
157
  love.graphics.print("Best: " .. highScore, 10, 36)
158

159
  for i = 1, lives do
160
    local x = love.graphics.getWidth() - 24 - (i - 1) * 30
161
    love.graphics.draw(ship, x, 24, 0, 1, 1, ship:getWidth() / 2, ship:getHeight() / 2)
162
  end
163
end
164

165
local function drawOverlay(title, subtitle)
166
  love.graphics.setColor(0, 0, 0, 0.7)
167
  love.graphics.rectangle("fill", 0, 0, love.graphics.getWidth(), love.graphics.getHeight())
168

169
  love.graphics.setColor(1, 1, 1)
170
  love.graphics.setFont(titleFont)
171
  love.graphics.printf(title, 0, 220, love.graphics.getWidth(), "center")
172

173
  love.graphics.setFont(font)
174
  love.graphics.printf(subtitle, 0, 300, love.graphics.getWidth(), "center")
175
end
176

177
function love.draw()
178
  love.graphics.push()
179
  if shake > 0 then
180
    love.graphics.translate(math.random(-6, 6), math.random(-6, 6))
181
  end
182

183
  local blink = invuln > 0 and math.floor(invuln * 10) % 2 == 1
184

185
  if not blink then
186
    love.graphics.setColor(1, 1, 1)
187
    love.graphics.draw(ship, player.x, player.y, 0, 2, 2, ship:getWidth() / 2, ship:getHeight() / 2)
188
  end
189

190
  love.graphics.setColor(1, 0.9, 0.3)
191
  for _, b in ipairs(bullets) do
192
    love.graphics.rectangle("fill", b.x - 2, b.y - 8, 4, 16)
193
  end
194

195
  for _, e in ipairs(enemies) do
196
    e:draw()
197
  end
198

199
  love.graphics.pop()
200

201
  drawHud()
202

203
  if gameState == "menu" then
204
    drawOverlay("SKYNEST", "Press space to play")
205
  elseif gameState == "gameover" then
206
    drawOverlay("GAME OVER", "Score " .. score .. " - press space to play again")
207
  end
208
end

Task 3: Write it down

When the last life goes, compare and save. write wants a string, so tostring the number rather than leaning on coercion.
Once per run, not once per frame. This is a real disk write. The end of a run is the only moment the number can have changed in a way anybody cares about.
Put the best on the game-over line too.
Play, die, quit the game completely, and start it again. The number is on the menu screen before you have pressed anything.

1
-- main.lua
2

3
local Enemy = require("enemy")
4
local collision = require("collision")
5

6
local ship
7
local font
8
local titleFont
9
local sounds
10
local highScore
11
local spawnEvery = 0.8
12
local gameState = "menu"
13

14
local player
15
local bullets
16
local fireCooldown
17
local enemies
18
local spawnTimer
19
local score
20
local lives
21
local invuln
22
local shake
23

24
local function resetGame()
25
  player = { x = 400, y = 500, size = 40, speed = 300 }
26
  bullets = {}
27
  fireCooldown = 0
28
  enemies = {}
29
  spawnTimer = 0
30
  score = 0
31
  lives = 3
32
  invuln = 0
33
  shake = 0
34
end
35

36
local function loadHighScore()
37
  local contents = love.filesystem.read("highscore.txt")
38
  return tonumber(contents) or 0
39
end
40

41
function love.load()
42
  love.graphics.setBackgroundColor(0.05, 0.05, 0.1)
43
  math.randomseed(os.time())
44
  ship = love.graphics.newImage("ship.png")
45
  font = love.graphics.newFont(20)
46
  titleFont = love.graphics.newFont(48)
47
  love.graphics.setFont(font)
48

49
  sounds = {
50
    shoot = love.audio.newSource("shoot.wav", "static"),
51
    hit = love.audio.newSource("hit.wav", "static"),
52
    explode = love.audio.newSource("explode.wav", "static"),
53
  }
54
  sounds.shoot:setVolume(0.35)
55
  sounds.hit:setVolume(0.6)
56

57
  highScore = loadHighScore()
58
  resetGame()
59
end
60

61
function love.keypressed(key)
62
  if key == "escape" then
63
    love.event.quit()
64
  elseif key == "space" and gameState ~= "playing" then
65
    resetGame()
66
    gameState = "playing"
67
  end
68
end
69

70
function love.update(dt)
71
  shake = shake - dt
72

73
  if gameState ~= "playing" then
74
    return
75
  end
76

77
  if love.keyboard.isDown("left", "a") then
78
    player.x = player.x - player.speed * dt
79
  end
80
  if love.keyboard.isDown("right", "d") then
81
    player.x = player.x + player.speed * dt
82
  end
83

84
  local half = player.size / 2
85
  player.x = math.max(half, math.min(love.graphics.getWidth() - half, player.x))
86

87
  fireCooldown = fireCooldown - dt
88
  invuln = invuln - dt
89

90
  if love.keyboard.isDown("space") and fireCooldown <= 0 then
91
    table.insert(bullets, { x = player.x, y = player.y - 30, size = 6, speed = 500 })
92
    fireCooldown = 0.15
93
    sounds.shoot:clone():play()
94
  end
95

96
  for i = #bullets, 1, -1 do
97
    local b = bullets[i]
98
    b.y = b.y - b.speed * dt
99
    if b.y < -20 then
100
      table.remove(bullets, i)
101
    end
102
  end
103

104
  spawnTimer = spawnTimer - dt
105
  if spawnTimer <= 0 then
106
    table.insert(enemies, Enemy.new(math.random(40, love.graphics.getWidth() - 40)))
107
    spawnTimer = spawnEvery
108
  end
109

110
  for i = #enemies, 1, -1 do
111
    local e = enemies[i]
112
    e:update(dt)
113
    if e.y > love.graphics.getHeight() + 20 then
114
      table.remove(enemies, i)
115
    end
116
  end
117

118
  if invuln <= 0 then
119
    for i = #enemies, 1, -1 do
120
      if collision.overlaps(enemies[i], player) then
121
        table.remove(enemies, i)
122
        lives = lives - 1
123
        invuln = 2
124
        shake = 0.4
125
        sounds.explode:play()
126
        if lives <= 0 then
127
          gameState = "gameover"
128
          if score > highScore then
129
            highScore = score
130
            love.filesystem.write("highscore.txt", tostring(highScore))
131
          end
132
        end
133
        break
134
      end
135
    end
136
  end
137

138
  for i = #enemies, 1, -1 do
139
    for j = #bullets, 1, -1 do
140
      if collision.overlaps(enemies[i], bullets[j]) then
141
        table.remove(bullets, j)
142

143
        local thud = sounds.hit:clone()
144
        thud:setPitch(0.9 + math.random() * 0.3)
145
        thud:play()
146

147
        enemies[i].hp = enemies[i].hp - 1
148
        if enemies[i].hp <= 0 then
149
          table.remove(enemies, i)
150
          score = score + 1
151
        end
152
        break
153
      end
154
    end
155
  end
156
end
157

158
local function drawHud()
159
  love.graphics.setColor(1, 1, 1)
160
  love.graphics.print("Score: " .. score, 10, 12)
161
  love.graphics.print("Best: " .. highScore, 10, 36)
162

163
  for i = 1, lives do
164
    local x = love.graphics.getWidth() - 24 - (i - 1) * 30
165
    love.graphics.draw(ship, x, 24, 0, 1, 1, ship:getWidth() / 2, ship:getHeight() / 2)
166
  end
167
end
168

169
local function drawOverlay(title, subtitle)
170
  love.graphics.setColor(0, 0, 0, 0.7)
171
  love.graphics.rectangle("fill", 0, 0, love.graphics.getWidth(), love.graphics.getHeight())
172

173
  love.graphics.setColor(1, 1, 1)
174
  love.graphics.setFont(titleFont)
175
  love.graphics.printf(title, 0, 220, love.graphics.getWidth(), "center")
176

177
  love.graphics.setFont(font)
178
  love.graphics.printf(subtitle, 0, 300, love.graphics.getWidth(), "center")
179
end
180

181
function love.draw()
182
  love.graphics.push()
183
  if shake > 0 then
184
    love.graphics.translate(math.random(-6, 6), math.random(-6, 6))
185
  end
186

187
  local blink = invuln > 0 and math.floor(invuln * 10) % 2 == 1
188

189
  if not blink then
190
    love.graphics.setColor(1, 1, 1)
191
    love.graphics.draw(ship, player.x, player.y, 0, 2, 2, ship:getWidth() / 2, ship:getHeight() / 2)
192
  end
193

194
  love.graphics.setColor(1, 0.9, 0.3)
195
  for _, b in ipairs(bullets) do
196
    love.graphics.rectangle("fill", b.x - 2, b.y - 8, 4, 16)
197
  end
198

199
  for _, e in ipairs(enemies) do
200
    e:draw()
201
  end
202

203
  love.graphics.pop()
204

205
  drawHud()
206

207
  if gameState == "menu" then
208
    drawOverlay("SKYNEST", "Press space to play")
209
  elseif gameState == "gameover" then
210
    drawOverlay("GAME OVER", "Score " .. score .. " - best " .. highScore .. " - press space to play again")
211
  end
212
end

Task 4: Make the .love

Your folder should hold exactly these eight files.

skynest/
  main.lua
  conf.lua
  enemy.lua
  collision.lua
  ship.png
  shoot.wav
  hit.wav
  explode.wav

Windows. Open the folder, select all eight files — not the folder, the files inside it — then right-click and compress them. The menu wording differs between Windows 10 and 11, but it is the only compress option there. Rename the .zip you get to skynest.love.
Turn file extensions on before you rename anything. If Explorer is hiding them, the file you believe you just named skynest.love is really skynest.love.zip, and nothing you do to it will work. The View menu has a checkbox for file name extensions. This costs more people more time than every other step on this page put together.

macOS or Linux, from the terminal. Note the cd — you are inside the folder zipping ., and the archive is written one level up so it does not try to include itself. The -x ".*" leaves out hidden files like .DS_Store.

cd skynest
zip -9 -r ../skynest.love . -x ".*"

Check it before you send it. On Windows, copy the .love, rename the copy back to .zip, and double-click it — Explorer will show you what is inside. On macOS or Linux, unzip -l skynest.love. Either way you want main.lua sitting at the top with no folder in front of it.
Run the .love itself, not the folder. Drag it onto LÖVE, or double-click it if the installer associated the file type. If you get the no-game screen, your zip has a folder in it.

Challenge (Optional)

Say when it is a new best. The honest version is harder than it looks: by the time you draw the overlay you have already overwritten highScore, so score == highScore is also true when you exactly tie an old record. Deriving state instead of storing it is usually right, and this is a small clean example of where it is not.
Save more than a number. Write several lines and parse them back with the string patterns from the bonus page, or write a Lua table as source text and load it with loadstring. The second one is how a great many real games do it, and it is worth knowing that a save file being executable code is a decision with consequences.
Handle a corrupted save. Open highscore.txt in a text editor, replace the number with the word banana, and launch the game. It should start at zero without complaining, and if it does, you already wrote the error handling — go and find the or 0 that did it.
Print the save directory on the menu. love.filesystem.getSaveDirectory() tells you exactly where your file went, which is the fastest way to end an argument with yourself about whether it saved.
Give it away. Send the .love to somebody who has LÖVE and watch them play it. This is the only item on the page you cannot verify by yourself.

Check Your Work

The title screen showing Best 25 read from a previous session

A cold launch on a machine that has played before. Best: 25 came off the disk in love.load, before anything was pressed.

Play a run, quit, relaunch. The best score is on the menu screen immediately, before you press anything.
Beat it, quit, relaunch. It went up. Fail to beat it, quit, relaunch. It did not.
A high score of any length works — including a single digit, which is the case that catches the one-liner.
skynest.love runs by itself, from anywhere on your disk, with the original folder moved or renamed.
The archive listing shows main.lua at the top level.

If the best score never changes, look at whether you saved on the hit that ended the run or somewhere the early return can reach. If it resets to zero every launch, print love.filesystem.getSaveDirectory() and go look in that folder — either the file is not there, in which case the write never ran, or it is there with the right number in it, in which case the read is the one-liner and you are getting a base conversion.

That Is the Course

You have a game that starts, is hard, can be lost, remembers you, and fits in one file you can send to somebody. It is built out of four Lua files and about two hundred lines, and there is nothing in it you did not write.

Look back at what is actually doing the work. The enemies are the metatable class from Activity 1.11. Both removal loops run backwards because of Activity 1.9. The cooldown, the spawn timer, the invulnerability and the shake are the same accumulator four times over. The HUD counts icons from a number rather than trusting a second copy of the truth. LÖVE never taught you any of that. It drew the pixels and told you which keys were down, and that was the whole of its contribution.

That was the point of doing Unit 1 first, and it is why you can now pick up any Lua codebase — a Roblox game, a Neovim config, a Redis script, a mod for something you like — and read it. Frameworks are the easy half. You did the other one.

Previous Course Index