Auto Refresh/HotLoading

What is Auto Refresh?

Since Garry's Mod 13 all Lua scripts are reloaded "live" when they are changed on disk. This is useful if you're coding because your changes show up immediately - as soon as you save.

Restrictions

Autorefresh does not always work. Not knowing these restrictions can lead to confusion. These are the currently known limitations:

It only supports files that are automatically included by the gamemode, from autorun, effects, entities and weapons.
- Specifically, when editing SWEP/SENT base files, SWEPs/SENTs using this base will not refresh until they are refreshed themselves.
It doesn't work on OSX
It doesn't work if Sublime Text's "Atomic Save" is enabled
It doesn't work with Visual Studio, VS Code works fine though
It doesn't work with dynamically included / AddCSLuaFile'd content - either for all, or specific cases. ( However, editing the primary cl_init.lua or init.lua files will trigger it, or any files included from those files; but anything dynamically added will not trigger the event - current test-case is with include rules inside of a function, called in sh_init.lua and cl_init / init includes sh_init and AddCSLuaFile )
On Linux (tested on Ubuntu 20.04.1 LTS) the game uses inotify watches to detect file changes which may reach limits depending on watcher folder counts (per user, I. E. pterodactyl), making certain files not autorefresh. A solution may be found here. The default may be 8192, depending on distro, which may need increasing in environments hosting multiple servers to work properly!

An unhandled lua refresh is fine and means it is working.

Breaking Code

Note that when code is refreshed, the entire file is run again. This can cause issues if global data is overwritten, especially tables. To prevent this sort of thing from happening, declare dynamic global variables as themselves or a literal, as such:

-- to prevent a specific file from autorefreshing, add something like this to the top of the file: if LangTable then return end --Declare global dynamic variables as themselves or a literal, rather than just a literal: LangTable = LangTable or {}

Furthermore, if your old file references hook.Add and your new file has removed that reference, the original hook will remain in place unless you use hook.Remove. The same goes for any callback function, including net.Receive, usermessage.Hook, and concommand.Add.

Disabling autorefresh

Autorefresh can lag the server when certain Lua files are edited. This happens when the refreshing cascades. This can be unwanted behavior when editing the scripts of a large project on a live server.

To disable autorefresh, add

-disableluarefresh

to the startup command-line and restart your server.

Manual Refreshing

You can refresh files manually (if they've been previously included) by using

lua_refresh_file <path>

My code doesn't work when I refresh it, but it works when I rejoin, why?

This typically means the script that is being refreshed was not written to support it

This could be many things, here are a few:

Not carrying over data(locals are reset, tables may be emptied/re-setup etc)
The refreshed script may be included in another one, in which case that one should be refreshed to reflect changes.
Loading order. The refreshed script may overwrite functionality it otherwise wouldn't during the normal loading of the game (it would be loaded before or after whatever it needed to function properly). Refreshed scripts are "slapped on top", nothing is unloaded, it is just executed again.