Hot Reload¶

Feather Hot Reload lets the desktop app send Lua source for a specific module over the existing WebSocket connection, then replace that module in the running game.

Before Enabling¶

Only enable hot reload when all of this is true:

• You are running a trusted development build.
• The Feather desktop app and game are on a trusted local machine or trusted LAN.
• allow names only the modules you intend to edit.
• persistToDisk is off unless you deliberately want patches written into the LÖVE save directory.
• You have explicitly installed and included the opt-in hot-reload plugin.
• You have a clear release path where the hot-reload plugin is excluded or the Feather integration is removed.

Enable It¶

For CLI-managed projects, let Feather write the allowlist config:

feather init path/to/my-game --plugins hot-reload --hot-reload-allow game.player,game.enemy --yes

For an already initialized project:

feather config hot-reload --allow game.player,game.enemy --dir path/to/my-game

The VS Code extension uses the same CLI path. When you select the hot-reload plugin during init or plugin install, it prompts for Lua files and converts project paths like game/player.lua into module names like game.player.

Or configure it manually from feather.config.lua:

return {
  debug = true,

  -- Hot reload is an opt-in plugin. Without this include, Feather ignores
  -- cmd:hot_reload messages even if debugger.hotReload is configured.
  include = { "hot-reload" },

  debugger = {
    enabled = true,
    hotReload = {
      -- Development-only remote code execution. Keep this false unless you
      -- understand that Feather can replace allowlisted Lua modules at runtime.
      enabled = true,

      -- Prefer exact modules. Avoid broad patterns unless you really mean it.
      allow = {
        "game.player",
        "game.enemy",
        "game.systems.*",
      },

      deny = {
        "main",
        "conf",
        "feather.*",
      },

      persistToDisk = false,
      clearOnBoot = false,
      requireLocalNetwork = true,
      showOverlay = true,
      toastDuration = 2.5,
    },
  },
}

For manual plugin registration, require and register the plugin explicitly:

local FeatherPluginManager = require("feather.plugin_manager")
local HotReloadPlugin = require("plugins.hot-reload")

DEBUGGER = FeatherDebugger({
  debug = true,
  debugger = { enabled = true },
  plugins = {
    FeatherPluginManager.createPlugin(HotReloadPlugin, "hot-reload", {
      enabled = true,
      allow = { "game.player" },
      deny = { "main", "conf", "feather.*" },
    }),
  },
})

Use It¶

1. Start the game with Feather enabled.
2. Open Debugger.
3. Open the game source folder if Feather cannot auto-detect it.
4. Select a .lua file from the file tree.
5. Press Reload.

The Debugger header shows the selected module next to Reload. If the file cannot be safely reloaded, the button stays disabled and its tooltip explains why, for example: hot reload is disabled, the plugin is missing, the selected file is not a Lua module, the module is protected, the module is not in hotReload.allow, or the session is blocked by requireLocalNetwork.

Compact status chips keep the current safety state visible:

• Disabled means the plugin or debugger.hotReload.enabled is off.
• Not allowlisted means the selected module does not match hotReload.allow.
• Remote blocked means requireLocalNetwork rejected the configured Feather host.
• Persisting means persistToDisk is enabled and patches are written to the LÖVE save directory.
• Modified N and Failed N summarize modules replaced by Hot Reload or modules whose latest reload failed.

The Watch toggle polls the selected file and reloads it when the source changes. It intentionally watches only the selected module so changes are explicit and easy to reason about.

Example¶

From the repository root:

love src-lua --hot-reload

Then open Debugger, select example/hot_reload/gameplay.lua, edit the file, and press Reload. You can also enable Watch to reload the selected module whenever the file changes.

Rollback¶

Before replacing a module, Feather keeps the original package.loaded[module] value. Press Restore in the Debugger toolbar to restore all modules replaced by hot reload and clear persisted patches.

If a new module has a syntax error, runtime error, or failing migration hook, Feather restores the previous module immediately and reports the error in the app.

Migration Hook¶

Reloaded modules can expose __feather_reload:

local Player = {}

function Player.__feather_reload(newModule, oldModule)
  newModule.instances = oldModule and oldModule.instances or {}
end

return Player

Use this for state migration, metatable updates, cache rebuilds, or system rebinding.

Mobile And Remote Devices¶

Hot reload works on mobile and handheld devices because Feather sends source code through WebSocket. When persistToDisk = true, patched modules are written to LÖVE's save directory using love.filesystem.write.

Limits¶

Hot reload does not support native libraries, arbitrary filesystem writes, unrestricted Lua execution, reloading Feather internals, or replacing main.lua / conf.lua.