Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Threaded resource loading for LÖVE

tag: v1.1.0

Fetching latest commit…

Cannot retrieve the latest commit at this time



This is an utility lib for LÖVE that loads resources (images, sounds) from the hard disk on a separate thread.

This allows for “doing stuff” while resources are being loaded; for example, playing an animation. The fact that the blocking calls happen in a separate thread ensures that the animation is fluid, without blocking calls dropping the framerate.

Version 1.0.0 of this lib only works with LÖVE 0.7.x . LÖVE 0.8.x has backwards-incompatible changes on the way threads and fonts are managed.


local loader = require 'love-loader'

local images = {}
local sounds = {}

local finishedLoading = false

function love.load()
  loader.newImage(  images, 'rabbit', 'path/to/rabbit.png')
  loader.newSource( sounds, 'iiiik',  'path/to/iiik.ogg')
  loader.newSource( sounds, 'music',  'path/to/music.ogg', 'stream')

    finishedLoading = true

function love.update(dt)
  if not finishedLoading then
    loader.update() -- You must do this on each iteration until all resources are loaded

function love.draw()
  if finishedLoading then
    -- media contains the images and sounds. You can use them here safely now., 100, 200)
  else -- not finishedLoading
    local percent = 0
    if loader.resourceCount ~= 0 then percent = loader.loadedCount / loader.resourceCount end"Loading .. %d%%"):format(percent*100), 100, 100)


  • loader.newImage(holder, key, path). Adds a new image to the list of images to load.
  • loader.newSource(holder, key, path, sourceType). Adds a new source to the list of images to load.
  • loader.start(finishCallback, loadedCallback). Starts doing the loading on a separate thread. When it finishes, it invokes finishCallback with no parameters. Every time it loads a new resource, it invokes loadedCallback. finishedCallback admits no parameters, and @loadedCallback@’s signature is function(kind, holder, key). kind is a string (“image”, “source” or “stream”). Neither loadedCallback or finishedCallback are mandatory.
  • loader.loadedCount integer returning the number of resources loaded. When loader.start gets invoked, it’s 0.
  • loader.resourceCount integer containing the total number of resources to be loaded. It can be used in conjunction with loader.loadedCount to show progressbars etc.

Gotchas / Warnings

  • I have not implemented font loading yet, since the interface will probably change from LÖVE 0.7.x to 0.8.×.
  • In order to use this lib, you must store the resources in “holder tables”. If you really want to store them in separate global variables, I guess you could use _G:

    — will create a new global variable called rabbit when the image is loaded
    loader.newImage( _G, ‘rabbit’, ‘path/to/rabbit.png’)

    If you do that I might come to your house and take your keyboard away. Use tables and local variables!


Just copy the love-loader.lua file somewhere in your projects (maybe inside a /lib/ folder) and require it accordingly.

Remember to store the value returned by require somewhere! (I suggest a local variable named loader or love.loader)

local loader = require 'love-loader'

The second step is making sure that your “game loop” calls loader.update, at least while there are resources to load.


I took a lot of inspiration from Michael Enger’s Stealth2D project. I learned the basic internals of threads from his loading state code.

Something went wrong with that request. Please try again.