Register File Change Handler

Signatures

bool registerFileChangeHandler(string filepath, function callback)
bool registerFileChangeHandler(string filepath, function callback, bool subDirs)
bool registerFileChangeHandler(string filepath, function callback, bool subDirs, int minCheckInterval)

Description

Registers a file change handler that will be triggered when the specified file has been changed.

Returns whether the operation was successful (true) or not (false).

Arguments

File Path

The path of the files to be monitored.

Wildcards * and ? are supported, but only for files, not directories.

Absolute paths are supported and relative paths start from {game}\x64\.

Callback

The Callback function that is executed when a file is changed.

Subdirectories

If set to true, files will be checked not only in the containing directory but also recursively in all of its subdirectories.

Is optional and set to false by default.

Minimum Check Interval

The minimum interval, in milliseconds, between consecutive file change checks.

This helps control the frequency of file checks to reduce unnecessary overhead, particularly when monitoring files that are not expected to change frequently.

If multiple handlers watch the same file, the shortest interval among them will be applied.

This interval applies even if the total number of monitored files is below the period limit in the Configuration file.

Is optional and set to 100ms by default.

Experimental Version

There is also an experimental version available that uses a directory-based approach as opposed to a file-based one.

It is significantly faster, capable of monitoring thousands of files with minimal overhead, and can detect newly added files without requiring the file change handler to be re-registered. However, this detection does not work in virtual file systems used by mod managers such as MO2, even if the virtual file system is rebuilt.

It can safely be used alongside the normal version and accessed with experimental.registerFileChangeHandler instead of event.registerFileChangeHandler.

Notes

If a file change handler is already registered for a file path within the same script, registering it again will update the callback instead of adding a new one. The watcher will not be touched at all in this case.

If the file or wildcard is already being tracked by another script at the time of registration, no new watcher is created. Instead, the script is added as a subscriber. The watcher is only removed when all subscribing scripts have unregistered. Additionally, it is not possible to unregister a watcher unless it was previously registered by the same script.

When a file change handler is registered with a wildcard path, such as scripts/config/mymod/*.lua, it only monitors files that exist at the time of registration. If new matching files are added later, they will not be tracked automatically. To detect changes in newly added files, the handler must be unregistered and then registered again with the same path.

On Windows, file timestamps are recorded with one second precision (or two seconds on FAT32). If a file is modified and saved quickly within that interval, the modification time might not change, which can prevent a change event from being triggered. This is expected behavior based on how the filesystem works.