Activity 2.8: Splitting the Game into Modules

The Idea

Your main.lua is past a hundred lines and every activity from here adds more. This is the moment to split it up — before it hurts, and while the seams are still obvious.

Nothing new is coming. Activity 1.12 already taught the whole mechanism: a module is a table a file returns, and require runs that file once and hands you the table.

skynest/
  main.lua
  conf.lua
  enemy.lua
  collision.lua
  ship.png

local Enemy = require("enemy")
local collision = require("collision")

No paths, no extensions, no build step. LÖVE looks in your game folder, so a file sitting next to main.lua is found by its name alone.

What makes a good seam

The test is not "how many lines" but how much a piece needs to know about everything else. Two things in your file barely know anything:

overlaps takes two tables and returns a boolean. It has never heard of bullets, enemies, or the player. That is a perfect module — it could be dropped into any other game unchanged.
Enemy knows its own position, speed and hp, and nothing about the score or the player. It only needs love.graphics, which is global anyway.

The update loop, by contrast, touches everything at once, and that is why it stays in main.lua. Do not split something just to make the file shorter — a module that needs six things passed into it has moved the mess rather than removed it.

Two shapes of module

collision.lua returns a table of plain functions — a toolbox. You call collision.overlaps(a, b) with a dot.

enemy.lua returns a class table — a thing you make instances from. You call Enemy.new(x) with a dot and e:update(dt) with a colon, exactly as before.

Both are just tables being returned. The difference is entirely in what you put in them, which is the point Activity 1.10 kept making.

The name is yours

local Enemy = require("enemy") — the file is lowercase, the variable is capitalized, and nothing enforces either. That is a convention worth following: lowercase filenames, capitalized class variables, so a reader can tell a class from a toolbox at the point of use.

Remember that require runs the file once. If two files both require enemy.lua, they get the same table — which is exactly right for a class, and something to watch for if a module ever holds mutable state of its own.

A refactor should change nothing

This activity is the first that adds no features. When you finish it the game will look and play identically, and that is the success condition. If behavior changed, something went wrong in the move.

So make one change at a time and run after each. Moving two things at once and finding the game broken leaves you guessing which move did it — and a refactor is the one situation where you have a perfect reference to compare against.

Build

Run the game first and watch it for a few seconds. That is your reference. Everything below should leave it unchanged.

Task 1: Extract collision.lua

Make collision.lua beside main.lua. It creates a table, puts overlaps in it, and returns it.
Delete the local overlaps from main.lua and require the module at the top instead.
Update all three call sites to collision.overlaps(...).
Miss one and you get a clear error naming a nil value, which is one of the few loud failures Lua gives you. Run it.

1
-- collision.lua
2

3
local collision = {}
4

5
function collision.overlaps(a, b)
6
  return a.x - a.size / 2 < b.x + b.size / 2
7
     and a.x + a.size / 2 > b.x - b.size / 2
8
     and a.y - a.size / 2 < b.y + b.size / 2
9
     and a.y + a.size / 2 > b.y - b.size / 2
10
end
11

12
return collision

1
-- main.lua
2

3
local collision = require("collision")
4

5
local ship
6
local player = { x = 400, y = 500, size = 40, speed = 300 }
7
local bullets = {}
8
local fireCooldown = 0
9
local enemies = {}
10
local spawnTimer = 0
11
local spawnEvery = 0.8
12
local score = 0
13

14
local Enemy = {}
15
Enemy.__index = Enemy
16

17
function Enemy.new(x)
18
  return setmetatable({ x = x, y = -20, size = 30, speed = 120, hp = 2 }, Enemy)
19
end
20

21
function Enemy:update(dt)
22
  self.y = self.y + self.speed * dt
23
end
24

25
function Enemy:draw()
26
  love.graphics.rectangle("fill", self.x - self.size / 2, self.y - self.size / 2, self.size, self.size)
27
end
28

29
function love.load()
30
  love.graphics.setBackgroundColor(0.05, 0.05, 0.1)
31
  math.randomseed(os.time())
32
  ship = love.graphics.newImage("ship.png")
33
end
34

35
function love.update(dt)
36
  if love.keyboard.isDown("left", "a") then
37
    player.x = player.x - player.speed * dt
38
  end
39
  if love.keyboard.isDown("right", "d") then
40
    player.x = player.x + player.speed * dt
41
  end
42

43
  local half = player.size / 2
44
  player.x = math.max(half, math.min(love.graphics.getWidth() - half, player.x))
45

46
  fireCooldown = fireCooldown - dt
47
  if love.keyboard.isDown("space") and fireCooldown <= 0 then
48
    table.insert(bullets, { x = player.x, y = player.y - 30, size = 6, speed = 500 })
49
    fireCooldown = 0.15
50
  end
51

52
  for i = #bullets, 1, -1 do
53
    local b = bullets[i]
54
    b.y = b.y - b.speed * dt
55
    if b.y < -20 then
56
      table.remove(bullets, i)
57
    end
58
  end
59

60
  spawnTimer = spawnTimer - dt
61
  if spawnTimer <= 0 then
62
    table.insert(enemies, Enemy.new(math.random(40, love.graphics.getWidth() - 40)))
63
    spawnTimer = spawnEvery
64
  end
65

66
  for i = #enemies, 1, -1 do
67
    local e = enemies[i]
68
    e:update(dt)
69
    if e.y > love.graphics.getHeight() + 20 then
70
      table.remove(enemies, i)
71
    end
72
  end
73

74
  for i = #enemies, 1, -1 do
75
    if collision.overlaps(enemies[i], player) then
76
      enemies = {}
77
      bullets = {}
78
      score = 0
79
      break
80
    end
81
  end
82

83
  for i = #enemies, 1, -1 do
84
    for j = #bullets, 1, -1 do
85
      if collision.overlaps(enemies[i], bullets[j]) then
86
        table.remove(bullets, j)
87
        enemies[i].hp = enemies[i].hp - 1
88
        if enemies[i].hp <= 0 then
89
          table.remove(enemies, i)
90
          score = score + 1
91
        end
92
        break
93
      end
94
    end
95
  end
96
end
97

98
function love.draw()
99
  love.graphics.setColor(1, 1, 1)
100
  love.graphics.draw(ship, player.x, player.y, 0, 2, 2, ship:getWidth() / 2, ship:getHeight() / 2)
101

102
  love.graphics.setColor(1, 0.9, 0.3)
103
  for _, b in ipairs(bullets) do
104
    love.graphics.rectangle("fill", b.x - 2, b.y - 8, 4, 16)
105
  end
106

107
  love.graphics.setColor(1, 0.3, 0.4)
108
  for _, e in ipairs(enemies) do
109
    e:draw()
110
  end
111

112
  love.graphics.setColor(1, 1, 1)
113
  love.graphics.print("Score: " .. score, 10, 10)
114
end

Task 2: Extract enemy.lua

Move the whole Enemy class into enemy.lua and return it.
Delete it from main.lua and require it at the top.
Nothing else changes. Enemy.new and e:update(dt) read exactly as they did, because the class was always just a table and now the table arrives from somewhere else.

1
-- enemy.lua
2

3
local Enemy = {}
4
Enemy.__index = Enemy
5

6
function Enemy.new(x)
7
  return setmetatable({ x = x, y = -20, size = 30, speed = 120, hp = 2 }, Enemy)
8
end
9

10
function Enemy:update(dt)
11
  self.y = self.y + self.speed * dt
12
end
13

14
function Enemy:draw()
15
  love.graphics.setColor(1, 0.3, 0.4)
16
  love.graphics.rectangle("fill", self.x - self.size / 2, self.y - self.size / 2, self.size, self.size)
17
end
18

19
return Enemy

1
-- main.lua
2

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

6
local ship
7
local player = { x = 400, y = 500, size = 40, speed = 300 }
8
local bullets = {}
9
local fireCooldown = 0
10
local enemies = {}
11
local spawnTimer = 0
12
local spawnEvery = 0.8
13
local score = 0
14

15
function love.load()
16
  love.graphics.setBackgroundColor(0.05, 0.05, 0.1)
17
  math.randomseed(os.time())
18
  ship = love.graphics.newImage("ship.png")
19
end
20

21
function love.update(dt)
22
  if love.keyboard.isDown("left", "a") then
23
    player.x = player.x - player.speed * dt
24
  end
25
  if love.keyboard.isDown("right", "d") then
26
    player.x = player.x + player.speed * dt
27
  end
28

29
  local half = player.size / 2
30
  player.x = math.max(half, math.min(love.graphics.getWidth() - half, player.x))
31

32
  fireCooldown = fireCooldown - dt
33
  if love.keyboard.isDown("space") and fireCooldown <= 0 then
34
    table.insert(bullets, { x = player.x, y = player.y - 30, size = 6, speed = 500 })
35
    fireCooldown = 0.15
36
  end
37

38
  for i = #bullets, 1, -1 do
39
    local b = bullets[i]
40
    b.y = b.y - b.speed * dt
41
    if b.y < -20 then
42
      table.remove(bullets, i)
43
    end
44
  end
45

46
  spawnTimer = spawnTimer - dt
47
  if spawnTimer <= 0 then
48
    table.insert(enemies, Enemy.new(math.random(40, love.graphics.getWidth() - 40)))
49
    spawnTimer = spawnEvery
50
  end
51

52
  for i = #enemies, 1, -1 do
53
    local e = enemies[i]
54
    e:update(dt)
55
    if e.y > love.graphics.getHeight() + 20 then
56
      table.remove(enemies, i)
57
    end
58
  end
59

60
  for i = #enemies, 1, -1 do
61
    if collision.overlaps(enemies[i], player) then
62
      enemies = {}
63
      bullets = {}
64
      score = 0
65
      break
66
    end
67
  end
68

69
  for i = #enemies, 1, -1 do
70
    for j = #bullets, 1, -1 do
71
      if collision.overlaps(enemies[i], bullets[j]) then
72
        table.remove(bullets, j)
73
        enemies[i].hp = enemies[i].hp - 1
74
        if enemies[i].hp <= 0 then
75
          table.remove(enemies, i)
76
          score = score + 1
77
        end
78
        break
79
      end
80
    end
81
  end
82
end
83

84
function love.draw()
85
  love.graphics.setColor(1, 1, 1)
86
  love.graphics.draw(ship, player.x, player.y, 0, 2, 2, ship:getWidth() / 2, ship:getHeight() / 2)
87

88
  love.graphics.setColor(1, 0.9, 0.3)
89
  for _, b in ipairs(bullets) do
90
    love.graphics.rectangle("fill", b.x - 2, b.y - 8, 4, 16)
91
  end
92

93
  love.graphics.setColor(1, 0.3, 0.4)
94
  for _, e in ipairs(enemies) do
95
    e:draw()
96
  end
97

98
  love.graphics.setColor(1, 1, 1)
99
  love.graphics.print("Score: " .. score, 10, 10)
100
end

Task 3: Let the enemy own its color

Move the setColor(1, 0.3, 0.4) out of love.draw and into Enemy:draw.
Now main.lua does not know what color an enemy is, and could not tell you if you asked. Making a damaged enemy flash is a change to one file.
This is the real prize of the activity. The split was mechanical; moving knowledge across the seam is what makes the split worth having.
Watch out for the state machine from Activity 2.2 — the enemy now leaves the color set to red when it finishes, so the score text needs its setColor(1, 1, 1) more than ever.

1
-- main.lua
2

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

6
local ship
7
local player = { x = 400, y = 500, size = 40, speed = 300 }
8
local bullets = {}
9
local fireCooldown = 0
10
local enemies = {}
11
local spawnTimer = 0
12
local spawnEvery = 0.8
13
local score = 0
14

15
function love.load()
16
  love.graphics.setBackgroundColor(0.05, 0.05, 0.1)
17
  math.randomseed(os.time())
18
  ship = love.graphics.newImage("ship.png")
19
end
20

21
function love.update(dt)
22
  if love.keyboard.isDown("left", "a") then
23
    player.x = player.x - player.speed * dt
24
  end
25
  if love.keyboard.isDown("right", "d") then
26
    player.x = player.x + player.speed * dt
27
  end
28

29
  local half = player.size / 2
30
  player.x = math.max(half, math.min(love.graphics.getWidth() - half, player.x))
31

32
  fireCooldown = fireCooldown - dt
33
  if love.keyboard.isDown("space") and fireCooldown <= 0 then
34
    table.insert(bullets, { x = player.x, y = player.y - 30, size = 6, speed = 500 })
35
    fireCooldown = 0.15
36
  end
37

38
  for i = #bullets, 1, -1 do
39
    local b = bullets[i]
40
    b.y = b.y - b.speed * dt
41
    if b.y < -20 then
42
      table.remove(bullets, i)
43
    end
44
  end
45

46
  spawnTimer = spawnTimer - dt
47
  if spawnTimer <= 0 then
48
    table.insert(enemies, Enemy.new(math.random(40, love.graphics.getWidth() - 40)))
49
    spawnTimer = spawnEvery
50
  end
51

52
  for i = #enemies, 1, -1 do
53
    local e = enemies[i]
54
    e:update(dt)
55
    if e.y > love.graphics.getHeight() + 20 then
56
      table.remove(enemies, i)
57
    end
58
  end
59

60
  for i = #enemies, 1, -1 do
61
    if collision.overlaps(enemies[i], player) then
62
      enemies = {}
63
      bullets = {}
64
      score = 0
65
      break
66
    end
67
  end
68

69
  for i = #enemies, 1, -1 do
70
    for j = #bullets, 1, -1 do
71
      if collision.overlaps(enemies[i], bullets[j]) then
72
        table.remove(bullets, j)
73
        enemies[i].hp = enemies[i].hp - 1
74
        if enemies[i].hp <= 0 then
75
          table.remove(enemies, i)
76
          score = score + 1
77
        end
78
        break
79
      end
80
    end
81
  end
82
end
83

84
function love.draw()
85
  love.graphics.setColor(1, 1, 1)
86
  love.graphics.draw(ship, player.x, player.y, 0, 2, 2, ship:getWidth() / 2, ship:getHeight() / 2)
87

88
  love.graphics.setColor(1, 0.9, 0.3)
89
  for _, b in ipairs(bullets) do
90
    love.graphics.rectangle("fill", b.x - 2, b.y - 8, 4, 16)
91
  end
92

93
  for _, e in ipairs(enemies) do
94
    e:draw()
95
  end
96

97
  love.graphics.setColor(1, 1, 1)
98
  love.graphics.print("Score: " .. score, 10, 10)
99
end

Challenge (Optional)

Extract bullet.lua the same way. Bullets are plain tables, so decide whether they deserve a class or just a bullet.new(x, y) factory function — both are defensible and the reasoning matters more than the answer.
Add collision.circles(a, b) alongside overlaps and switch between them by changing one word at the call sites. That is the payoff of a toolbox module.
Give enemy.lua a second class that inherits from Enemy, using the bonus inheritance page, and return both from the file in one table. Then require it as local enemies = require('enemy') and use enemies.Fast.new(x).

Check Your Work

The game plays exactly as it did before. Same speed, same spawn rate, same two hits per enemy, same reset. Nothing about it should feel different.

What has changed is the shape of the project:

Five files instead of three.
main.lua holds the game loop and the state it coordinates, and nothing else.
collision.lua could be copied into a completely different game and would work.

If you get an error naming a nil value, a call site still uses the old bare name. If enemies vanish, check that enemy.lua ends with return Enemy — a module that returns nothing gives you a nil with no complaint at the point of require.

Previous Next: Score, Lives, and a HUD