« ReFreezed.com
LuaHotLoader

Documentation


Intro

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

LÖVE

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

API

load

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.

require

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.

unload

hotLoader.unload( path )

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

See also: load

unrequire

hotLoader.unrequire( moduleName )

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

See also: require

preload

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

prerequire

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

hasLoaded

bool = hotLoader.hasLoaded( path )

v1.1 Check if a resource has been loaded.

See also: load, hasRequired

hasRequired

bool = hotLoader.hasRequired( moduleName )

v1.1 Check if a module has been loaded.

See also: require, hasLoaded

monitor

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)
end

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

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

setLoader

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.

getLoader

loader = hotLoader.getLoader( fileExtension )

Get the value set by setLoader.

removeAllLoaders

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

setCustomLoader

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

Set or remove a loader for a specific file path.

getCustomLoader

loader|nil = hotLoader.getCustomLoader( path )

Get the loader set with setCustomLoader.

removeAllCustomLoaders

hotLoader.removeAllCustomLoaders( )

Remove all custom loaders.

See also: setCustomLoader

setDefaultLoader

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.

getDefaultLoader

loader|nil = hotLoader.getDefaultLoader( )

Get the loader set with setDefaultLoader.

disableDefaultLoader

hotLoader.disableDefaultLoader( )

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

update

hotLoader.update( deltaTime )

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

See also: load, require

resetCheckingState

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.

setCheckingInterval

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.

getCheckingInterval

interval = hotLoader.getCheckingInterval( )

Get the value set by setCheckingInterval.

allowExternalPaths

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.

isAllowingExternalPaths

bool = hotLoader.isAllowingExternalPaths( )

v1.3 Get the value set by allowExternalPaths.

setLogFormat

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

getLogFormat

logFormat = hotLoader.getLogFormat( )

v1.2 Get the value set by setLogFormat.

See also: setLogFormat

log

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

Internal Internal function used for printing information.

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

Notes

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