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
- setLoader
- getLoader
- removeAllLoaders
- setCustomLoader
- getCustomLoader
- removeAllCustomLoaders
- setDefaultLoader
- getDefaultLoader
- disableDefaultLoader
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:
- Custom loader (by path).
- Loader (by file extension).
- Default loader.
- 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.
unrequire
hotLoader.unrequire( moduleName )
Forces the module to reload at next require call. Stops monitoring the file.
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.
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.
hasLoaded
bool = hotLoader.hasLoaded( path )
v1.1 Check if a resource has been loaded.
hasRequired
bool = hotLoader.hasRequired( moduleName )
v1.1 Check if a module has been loaded.
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
andwav
. (See predefined loaders.)
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.
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.
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"
.
getLogFormat
logFormat = hotLoader.getLogFormat( )
v1.2
Get the value set by setLogFormat
.
log
hotLoader.log( formatString, value1, ... )
Internal Internal function used for printing information.
-- Silence the library:
hotLoader.log = function()end
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