love.filesystem

Provides an interface to the user's filesystem.

This module provides access to files in specific places:

  • The root folder of the .love archive (or source directory)
  • The root folder of the game's save directory.
  • The folder containing the game's .love archive (or source directory), but only if specific conditions are met.

Each game is granted a single directory on the system where files can be saved through love.filesystem. This is the only directory where love.filesystem can write files. These directories will typically be found in something like:

  • Windows XP: C:\Documents and Settings\user\Application Data\LOVE\ or %appdata%\LOVE\
  • Windows Vista and 7: C:\Users\user\AppData\Roaming\LOVE or %appdata%\LOVE\
  • Linux: $XDG_DATA_HOME/love/ or ~/.local/share/love/
  • Mac: /Users/user/Library/Application Support/LOVE/
  • Android: /data/user/0/org.love2d.android/files/save/ or /data/data/org.love2d.android/files/save/ (On Android there are various save locations. If these don't work then you can use love.filesystem.getSaveDirectory() to check.)

Files that are opened for write or append will always be created in the save directory. The same goes for other operations that involve writing to the filesystem, like mkdir.

Files that are opened for read will be looked for in the save directory, and then in the .love archive (in that order). So if a file with a certain filename (and path) exist in both the .love archive and the save folder, the one in the save directory takes precedence.

Note: All paths are relative to the .love archive and save directory. (except for the get*Directory() calls)

It is recommended to set your game's identity first in your conf.lua. You can set it with love.filesystem.setIdentity as well.

Types

File Represents a file on the filesystem.
FileData Data representing the contents of a file.

Functions

love.filesystem.append Append data to an existing file. 0.9.0
love.filesystem.areSymlinksEnabled Gets whether love.filesystem follows symbolic links. 0.9.2
love.filesystem.createDirectory Creates a directory. 0.9.0
love.filesystem.enumerate Returns all the files and subdirectories in the directory. 0.3.0 0.9.0
love.filesystem.exists Check whether a file or directory exists.
love.filesystem.getAppdataDirectory Returns the application data directory (could be the same as getUserDirectory)
love.filesystem.getDirectoryItems Returns all the files and subdirectories in the directory. 0.9.0
love.filesystem.getIdentity Gets the write directory name for your game. 0.9.0
love.filesystem.getLastModified Gets the last modification time of a file. 0.7.1
love.filesystem.getRealDirectory Gets the absolute path of the directory containing a filepath. 0.9.2
love.filesystem.getRequirePath Gets the filesystem paths that will be searched when require is called. 0.10.0
love.filesystem.getSaveDirectory Gets the full path to the designated save directory.
love.filesystem.getSize Gets the size in bytes of a file. 0.9.0
love.filesystem.getSource Returns the full path to the directory containing the .love file or directory. 0.9.0
love.filesystem.getSourceBaseDirectory Returns the full path to the directory containing the .love file. 0.9.0
love.filesystem.getUserDirectory Returns the path of the user's directory
love.filesystem.getWorkingDirectory Gets the current working directory.
love.filesystem.init Initializes love.filesystem, will be called internally, so should not be used explictly.
love.filesystem.isDirectory Check whether something is a directory.
love.filesystem.isFile Check whether something is a file.
love.filesystem.isFused Gets whether the game is in fused mode or not. 0.9.0
love.filesystem.isSymlink Gets whether a filepath is actually a symbolic link. 0.9.2
love.filesystem.lines Iterate over the lines in a file.
love.filesystem.load Loads a Lua file (but does not run it).
love.filesystem.mkdir Creates a directory. 0.9.0
love.filesystem.mount Mounts a zip file or folder in the game's save directory for reading. 0.9.0
love.filesystem.newFile Creates a new File object.
love.filesystem.newFileData Creates a new FileData object. 0.7.0
love.filesystem.read Read the contents of a file
love.filesystem.remove Removes a file (or directory).
love.filesystem.setIdentity Sets the write directory for your game.
love.filesystem.setRequirePath Sets the filesystem paths that will be searched when require is called. 0.10.0
love.filesystem.setSource Sets the source of the game, where the code is present. Used internally.
love.filesystem.setSymlinksEnabled Sets whether love.filesystem follows symbolic links. 0.9.2
love.filesystem.unmount Unmounts a zip file or folder previously mounted with love.filesystem.mount. 0.9.0
love.filesystem.write Write data to a file.

Enums

FileDecoder How to decode a given FileData. 0.7.0
FileMode The different modes you can open a File in.

See Also

love.filesystem.enumerate

love.filesystem.enumerate Removed in LÖVE 0.9.0 It has been renamed to

2017-03-21 15:46:05
love.filesystem.isFile

love.filesystem.isFile Check whether something is a file. Function Synopsis

2017-03-21 15:46:18
love.filesystem.isFused

love.filesystem.isFused Available since LÖVE 0.9.0 This function is not supported in earlier versions. Gets whether the game is in fused mode

2017-03-21 15:46:19
love.filesystem.getUserDirectory

love.filesystem.getUserDirectory Returns the path of the user's directory Function Synopsis

2017-03-21 15:46:15
love.filesystem.areSymlinksEnabled

love.filesystem.areSymlinksEnabled Available since LÖVE 0.9.2 This function is not supported in earlier versions. Gets whether love.filesystem

2017-03-21 15:46:03
love.filesystem.createDirectory

love.filesystem.createDirectory Available since LÖVE 0.9.0 It has been renamed from

2017-03-21 15:46:04
love.filesystem.getDirectoryItems

love.filesystem.getDirectoryItems Available since LÖVE 0.9.0 It has been renamed from

2017-03-21 15:46:08
love.filesystem.setRequirePath

love.filesystem.setRequirePath Available since LÖVE 0.10.0 This function is not supported in earlier versions. Sets the filesystem paths that

2017-03-21 15:46:28
love.filesystem.append

love.filesystem.append Available since LÖVE 0.9.0 This function is not supported in earlier versions. Append data to an existing file.

2017-03-21 15:46:02
love.filesystem.isDirectory

love.filesystem.isDirectory Check whether something is a directory. Function Synopsis

2017-03-21 15:46:17