« ReFreezed.com



Some bullet points about the library:

  • Individual files are monitored (as opposed to directories).
  • Modules are loaded using a very similar system to Lua's own.
  • Other files (we call these resources) are loaded using loader functions.
  • Files are reloaded when their modification time changes. (See notes.)
  • The library is single-threaded.

Predefined loaders


In LÖVE loaders are automatically added for the most common image and sound file extensions, like png and wav. The loaders are/use love.graphics.newImage and love.audio.newSource, and return Image and Source objects.

Loaders are currently added for these extensions:

  • Textures: jpg, jpeg, png, bmp, tga, hdr, pic, exr
  • Sounds (static): wav, ogg, oga
  • Music (stream): mp3, flac, 699, amf, ams, dbm, dmf, dsm, far, it, j2b, mdl, med, mod, mt2, mtm, okt, psm, s3m, stm, ult, umx, xm, abc, mid, pat



resource = hotLoader.load( path [, customLoader ] )
resource = hotLoader.load( path [, protectedLoad=false, customLoader ] )
resource = customLoader( path )

Load a resource/file. Returns nil and a message on error (if protectedLoad is true, otherwise errors are raised). If customLoader is set it replaces the previous custom loader for path.

Different loaders are used depending on availability, in this order:

  1. Custom loader (by path).
  2. Loader (by file extension).
  3. Default loader.
  4. Basic loader (returns file contents as a plain string).

LÖVE In LÖVE, relative paths are loaded from the default LÖVE directories, and absolute paths require allowExternalPaths to be enabled.


module = hotLoader.require( moduleName )

Load a module (like the standard Lua require() function).

Note that the library's system for modules is not connected to Lua's own system. There are likely some differences in how the two systems work.


hotLoader.unload( path )

Forces the resource to reload at next load call. Stops monitoring the file.

See also: load


hotLoader.unrequire( moduleName )

Forces the module to reload at next require call. Stops monitoring the file.

See also: require


hotLoader.preload( path, resource [, customLoader ] )
resource = customLoader( path )

Tell the library about a resource that has already been loaded. load will return the value set by this function. The resource file will be monitored as if load had been called for the resource initially.

See also: load, prerequire, monitor


hotLoader.prerequire( moduleName, module )

Tell the library about a module that has already been loaded. require will return the value set by this function. The module file will be monitored as if require had been called for the module initially.

See also: require, preload


bool = hotLoader.hasLoaded( path )

v1.1 Check if a resource has been loaded.

See also: load, hasRequired


bool = hotLoader.hasRequired( moduleName )

v1.1 Check if a module has been loaded.

See also: require, hasLoaded


hotLoader.monitor( path, onFileModified )
hotLoader.monitor( path, callbackData, onFileModified )
onFileModified = function( path, callbackData|nil )

v1.3 Monitor a file for changes. onFileModified gets called (in protected mode) when the file is modified, with the path and optionally some extra data of any kind as arguments.

Note that calling this function replaces any previously loaded value and custom loader for path. You should only use this function if you don't intend to use load for the file. This function is useful if you for example normally don't want to hot-load files in your program - only during development - or if you have a separate system for handling resources.

local function loadImageAsset(path, name)
	imageAssets[name] = loadImage(path)

local path = "images/funnyDuck.png"
local name = "duck"
loadImageAsset(path, name)

if devMode then
	hotLoader.monitor(path, name, loadImageAsset)


hotLoader.setLoader( fileExtension, [ fileExtension2..., ] loader|nil )
resource = loader( path )

Set or remove a loader for files with a specific extension. For example, you could add loaders for .json or .my_level_format files.


loader = hotLoader.getLoader( fileExtension )

Get the value set by setLoader.


hotLoader.removeAllLoaders( )

Remove all loaders, including automatically added loaders.

LÖVE In LÖVE loaders are automatically added for the most common image and sound file extensions, like png and wav. (See predefined loaders.)

See also: setLoader


hotLoader.setCustomLoader( path, [ path2..., ] loader|nil )
resource = loader( path )

Set or remove a loader for a specific file path.


loader|nil = hotLoader.getCustomLoader( path )

Get the loader set with setCustomLoader.


hotLoader.removeAllCustomLoaders( )

Remove all custom loaders.

See also: setCustomLoader


hotLoader.setDefaultLoader( loader|nil )
resource = loader( path )

Set the fallback loader to be used for files without loaders. If there's no default loader (nil) then these files are loaded as plain strings.


loader|nil = hotLoader.getDefaultLoader( )

Get the loader set with setDefaultLoader.


hotLoader.disableDefaultLoader( )

After calling this, trying to load files with no loader will raise an error.


hotLoader.update( deltaTime )

Check if monitored files have changed and trigger reloading of them.

See also: load, require


hotLoader.resetCheckingState( )

v1.2 Make the library start over and check the first monitored file next update. The current update is aborted if this is called from within a loader.


hotLoader.setCheckingInterval( interval )

Set how often each file is checked for modifications in seconds. Note that the more files that are monitored the more checks happen per second in total. The default interval is 1.0.

There's little reason to set the value lower than 1 as the file modification time returned by the operative system is in whole seconds.

LÖVE In Windows a more efficient method is used to monitor files, in which case this interval value isn't used except as a fallback.


interval = hotLoader.getCheckingInterval( )

Get the value set by setCheckingInterval.


hotLoader.allowExternalPaths( bool )

LÖVE Allow the library to access files outside the default LÖVE directories. Note that absolute paths are required to access external files (e.g. "C:/Images/Duck.png"). The default value is false.

This setting is only used in LÖVE. Outside LÖVE all files are accessible like normal.


bool = hotLoader.isAllowingExternalPaths( )

v1.3 Get the value set by allowExternalPaths.


hotLoader.setLogFormat( logFormat )

v1.2 Set message format used by log. Use the percent sign (%) to indicate where the values go:

  • %m = the message
  • %d = the current date (YYYY-MM-DD)
  • %t = the current time (HH:MM:SS)
  • %% = a literal percent sign

The default format is "[HotLoader|%t] %m".

See also: getLogFormat


logFormat = hotLoader.getLogFormat( )

v1.2 Get the value set by setLogFormat.

See also: setLogFormat


hotLoader.log( formatString, value1, ... )

Internal Internal function used for printing information.

-- Silence the library:
hotLoader.log = function()end
See also: setLogFormat


File modification times not available

For example, in LÖVE (with allowExternalPaths enabled), if external files are monitored, the library won't be able to retrieve the file modification time as it relies on LÖVE's file system functionality which is limited to only internal paths. In this case the library monitors the file size instead (by opening the file), which will result in the library not detecting file changes as long as the the size doesn't change, and may possibly interfere with programs trying to write to the file if the timing is unfortunate.

It's recommended to only hot-load internal files in LÖVE to avoid these issues.

Page updated: 2022-07-19