Filesystem watching;

api/init.lua

@@ -324,6 +324,41 @@ return {
         }
       }
     },
+    {
+      name = "filechanged",
+      tag = "callbacks",
+      summary = "Called when a file is changed.",
+      description = "The `lovr.filechanged` callback is called when a file is changed.  File watching must be enabled, either by passing `--watch` when starting LÖVR or by calling `lovr.filesystem.watch`.\n\nCurrently, only files in the source directory are watched.  On Android, files in the sdcard directory are watched.",
+      key = "lovr.filechanged",
+      module = "lovr",
+      notes = "LÖVR provides a default implementation for `lovr.filechanged` that restarts the project if a non-hidden file was changed:\n\n    function lovr.filechanged(path)\n      if not path:match('^%.') then\n        lovr.event.restart()\n      end\n    end",
+      related = {
+        "lovr.filesystem.watch",
+        "lovr.filesystem.unwatch"
+      },
+      variants = {
+        {
+          arguments = {
+            {
+              name = "path",
+              type = "string",
+              description = "The path to the file that changed."
+            },
+            {
+              name = "action",
+              type = "FileAction",
+              description = "What happened to the file."
+            },
+            {
+              name = "oldpath",
+              type = "string",
+              description = "The old path, for `rename` actions."
+            }
+          },
+          returns = {}
+        }
+      }
+    },
     {
       name = "focus",
       tag = "callbacks",
@@ -8860,6 +8895,31 @@ return {
       description = "The `lovr.filesystem` module provides access to the filesystem.\n\nAll files written will go in a special folder called the \"save directory\".  The location of the save directory is platform-specific:\n\n<table>\n  <tr>\n    <td>Windows</td>\n    <td><code>C:\\Users\\&lt;user&gt;\\AppData\\Roaming\\LOVR\\&lt;identity&gt;</code></td>\n  </tr>\n  <tr>\n    <td>macOS</td>\n    <td><code>/Users/&lt;user&gt;/Library/Application Support/LOVR/&lt;identity&gt;</code></td>\n  </tr>\n  <tr>\n    <td>Linux</td>\n    <td><code>/home/&lt;user&gt;/.local/share/LOVR/&lt;identity&gt;</code></td>\n  </tr>\n  <tr>\n    <td>Android</td>\n    <td><code>/sdcard/Android/data/&lt;identity&gt;/files</code></td>\n  </tr> </table>\n\n`<identity>` is a unique identifier for the project, and can be set in `lovr.conf`.  On Android, the identity can not be changed and will always be the package id (e.g. `org.lovr.app`).\n\nWhen files are read, they will be searched for in multiple places.  By default, the save directory is checked first, then the project source (folder or zip).  That way, when data is written to a file, any future reads will see the new data.  The `t.saveprecedence` conf setting can be used to change this precedence.\n\nConceptually, `lovr.filesystem` uses a \"virtual filesystem\", which is an ordered list of folders and zip files that are merged into a single filesystem hierarchy.  Folders and archives in the list can be added and removed with `lovr.filesystem.mount` and `lovr.filesystem.unmount`.\n\nLÖVR extends Lua's `require` function to look for modules in the virtual filesystem.  The search patterns can be changed with `lovr.filesystem.setRequirePath`, similar to `package.path`.",
       key = "lovr.filesystem",
       enums = {
+        {
+          name = "FileAction",
+          summary = "Different actions that can be taken on files.",
+          description = "The different actions that can be taken on files, reported by `lovr.filechanged` when filesystem watching is active.",
+          key = "FileAction",
+          module = "lovr.filesystem",
+          values = {
+            {
+              name = "create",
+              description = "The file was created."
+            },
+            {
+              name = "delete",
+              description = "The file was deleted."
+            },
+            {
+              name = "modify",
+              description = "The file's contents were modified."
+            },
+            {
+              name = "rename",
+              description = "The file was renamed."
+            }
+          }
+        },
         {
           name = "OpenMode",
           summary = "Different ways to open a file.",
@@ -9625,6 +9685,40 @@ return {
             }
           }
         },
+        {
+          name = "unwatch",
+          summary = "Stop watching files.",
+          description = "Stops watching files.",
+          key = "lovr.filesystem.unwatch",
+          module = "lovr.filesystem",
+          related = {
+            "lovr.filesystem.watch",
+            "lovr.filechanged"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {}
+            }
+          }
+        },
+        {
+          name = "watch",
+          summary = "Start watching the filesystem for changes.",
+          description = "Starts watching the filesystem for changes.  File events will be reported by the `lovr.filechanged` callback.\n\nCurrently, on PC, only files in the source directory will be watched.  On Android, files in the save directory will be watched instead, so that pushing new files with `adb` can be detected.",
+          key = "lovr.filesystem.watch",
+          module = "lovr.filesystem",
+          related = {
+            "lovr.filesystem.unwatch",
+            "lovr.filechanged"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {}
+            }
+          }
+        },
         {
           name = "write",
           tag = "filesystem-files",

api/lovr/callbacks/filechanged.lua

@@ -0,0 +1,46 @@
+return {
+  tag = 'callbacks',
+  summary = 'Called when a file is changed.',
+  description = [[
+    The `lovr.filechanged` callback is called when a file is changed.  File watching must be
+    enabled, either by passing `--watch` when starting LÖVR or by calling `lovr.filesystem.watch`.
+
+    Currently, only files in the source directory are watched.  On Android, files in the sdcard
+    directory are watched.
+  ]],
+  arguments = {
+    path = {
+      type = 'string',
+      description = 'The path to the file that changed.'
+    },
+    action = {
+      type = 'FileAction',
+      description = 'What happened to the file.'
+    },
+    oldpath = {
+      type = 'string',
+      description = 'The old path, for `rename` actions.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'path', 'action', 'oldpath' },
+      returns = {}
+    }
+  },
+  notes = [[
+    LÖVR provides a default implementation for `lovr.filechanged` that restarts the project if a
+    non-hidden file was changed:
+
+        function lovr.filechanged(path)
+          if not path:match('^%.') then
+            lovr.event.restart()
+          end
+        end
+  ]],
+  related = {
+    'lovr.filesystem.watch',
+    'lovr.filesystem.unwatch'
+  }
+}

api/lovr/filesystem/FileAction.lua

@@ -0,0 +1,25 @@
+return {
+  summary = 'Different actions that can be taken on files.',
+  description = [[
+    The different actions that can be taken on files, reported by `lovr.filechanged` when filesystem
+    watching is active.
+  ]],
+  values = {
+    {
+      name = 'create',
+      description = 'The file was created.'
+    },
+    {
+      name = 'delete',
+      description = 'The file was deleted.'
+    },
+    {
+      name = 'modify',
+      description = 'The file\'s contents were modified.'
+    },
+    {
+      name = 'rename',
+      description = 'The file was renamed.'
+    }
+  }
+}

api/lovr/filesystem/unwatch.lua

@@ -0,0 +1,16 @@
+return {
+  summary = 'Stop watching files.',
+  description = 'Stops watching files.',
+  arguments = {},
+  returns = {},
+  variants = {
+    {
+      arguments = {},
+      returns = {}
+    }
+  },
+  related = {
+    'lovr.filesystem.watch',
+    'lovr.filechanged'
+  }
+}

api/lovr/filesystem/watch.lua

@@ -0,0 +1,22 @@
+return {
+  summary = 'Start watching the filesystem for changes.',
+  description = [[
+    Starts watching the filesystem for changes.  File events will be reported by the
+    `lovr.filechanged` callback.
+
+    Currently, on PC, only files in the source directory will be watched.  On Android, files in the
+    save directory will be watched instead, so that pushing new files with `adb` can be detected.
+  ]],
+  arguments = {},
+  returns = {},
+  variants = {
+    {
+      arguments = {},
+      returns = {}
+    }
+  },
+  related = {
+    'lovr.filesystem.unwatch',
+    'lovr.filechanged'
+  }
+}