Love2D APIFilesystemOn this pageFilesystem Description: Provides an interface to the user's filesystem. setIdentity Type: Function. Description: Sets the write directory for your game. Note that you can only set the name of the folder to store your files in, not the location. Signature: setIdentity: function(identity: string, append_to_path?: boolean) Parameters: ParameterTypeDescriptionidentitystringThe new identity that will be used as write directory.append_to_pathbooleanThe append_to_path parameter. getIdentity Type: Function. Description: Gets the write directory name for your game. Note that this only returns the name of the folder to store your files in, not the full path. Signature: getIdentity: function(): string Returns: Return TypeDescriptionstringThe identity that is used as write directory. getSource Type: Function. Description: Returns the full path to the the .love file or directory. If the game is fused to the LÖVE executable, then the executable is returned. Signature: getSource: function(): string Returns: Return TypeDescriptionstringThe full platform-dependent path of the .love file or directory. getSaveDirectory Type: Function. Description: Gets the full path to the designated save directory. This can be useful if you want to use the standard io library (or something else) to read or write in the save directory. Signature: getSaveDirectory: function(): string Returns: Return TypeDescriptionstringThe absolute path to the save directory. getWorkingDirectory Type: Function. Description: Gets the current working directory. Signature: getWorkingDirectory: function(): string Returns: Return TypeDescriptionstringThe current working directory. getUserDirectory Type: Function. Description: Returns the path of the user's directory Signature: getUserDirectory: function(): string Returns: Return TypeDescriptionstringThe path of the user's directory getAppdataDirectory Type: Function. Description: Returns the application data directory (could be the same as getUserDirectory) Signature: getAppdataDirectory: function(): string Returns: Return TypeDescriptionstringThe path of the application data directory getSourceBaseDirectory Type: Function. Description: Returns the full path to the directory containing the .love file. If the game is fused to the LÖVE executable, then the directory containing the executable is returned. If love.filesystem.isFused is true, the path returned by this function can be passed to love.filesystem.mount, which will make the directory containing the main game (e.g. C:\Program Files\coolgame) readable by love.filesystem. Signature: getSourceBaseDirectory: function(): string getExecutablePath: function(): string Returns: Return TypeDescriptionstringThe full platform-dependent path of the directory containing the .love file. getRealDirectory Type: Function. Description: Gets the platform-specific absolute path of the directory containing a filepath. This can be used to determine whether a file is inside the save directory or the game's source .love. Overload details: This function returns the directory containing the given ''file path'', rather than file. For example, if the file screenshot1.png exists in a directory called screenshots in the game's save directory, love.filesystem.getRealDirectory('screenshots/screenshot1.png') will return the same value as love.filesystem.getSaveDirectory. Signature: getRealDirectory: function(filename: string): string | nil, string | nil Parameters: ParameterTypeDescriptionfilenamestringThe filepath to get the directory of. Returns: Return TypeDescriptionstring or nilThe platform-specific full path of the directory containing the filepath. getRequirePath Type: Function. Description: Gets the filesystem paths that will be searched when require is called. The paths string returned by this function is a sequence of path templates separated by semicolons. The argument passed to ''require'' will be inserted in place of any question mark ('?') character in each template (after the dot characters in the argument passed to ''require'' are replaced by directory separators.) The paths are relative to the game's source and save directories, as well as any paths mounted with love.filesystem.mount. Overload details: The default paths string is '?.lua;?/init.lua', which makes require('cool') try to load cool.lua and then try cool/init.lua if cool.lua doesn't exist. Signature: getRequirePath: function(): string Returns: Return TypeDescriptionstringThe paths that the ''require'' function will check in love's filesystem. setRequirePath Type: Function. Description: Sets the filesystem paths that will be searched when require is called. The paths string given to this function is a sequence of path templates separated by semicolons. The argument passed to ''require'' will be inserted in place of any question mark ('?') character in each template (after the dot characters in the argument passed to ''require'' are replaced by directory separators.) The paths are relative to the game's source and save directories, as well as any paths mounted with love.filesystem.mount. Overload details: The default paths string is '?.lua;?/init.lua', which makes require('cool') try to load cool.lua and then try cool/init.lua if cool.lua doesn't exist. Signature: setRequirePath: function(path: string) Parameters: ParameterTypeDescriptionpathstringThe paths that the ''require'' function will check in love's filesystem. mount Type: Function. Description: Mounts a zip file or folder in the game's save directory for reading. -- It is also possible to mount love.filesystem.getSourceBaseDirectory if the game is in fused mode. Signature: mount: function(archive: string, mountpoint: string, append_to_path?: boolean): boolean Parameters: ParameterTypeDescriptionarchivestringThe folder or zip file in the game's save directory to mount.mountpointstringThe new path the archive will be mounted to.append_to_pathbooleanWhether the archive will be searched when reading a filepath before or after already-mounted archives. This includes the game's source and save directories. (Default: false.) Returns: Return TypeDescriptionbooleansuccess — True if the archive was successfully mounted, false otherwise. mount Type: Function. Description: Mounts a zip file or folder in the game's save directory for reading. -- It is also possible to mount love.filesystem.getSourceBaseDirectory if the game is in fused mode. Signature: mount: function(archive: FileData, mountpoint: string, append_to_path?: boolean): boolean Parameters: ParameterTypeDescriptionarchiveFileDataThe folder or zip file in the game's save directory to mount.mountpointstringThe new path the archive will be mounted to.append_to_pathbooleanWhether the archive will be searched when reading a filepath before or after already-mounted archives. This includes the game's source and save directories. (Default: false.) Returns: Return TypeDescriptionbooleansuccess — True if the archive was successfully mounted, false otherwise. unmount Type: Function. Description: Unmounts a zip file or folder previously mounted for reading with love.filesystem.mount. Signature: unmount: function(archive: string): boolean Parameters: ParameterTypeDescriptionarchivestringThe folder or zip file in the game's save directory which is currently mounted. Returns: Return TypeDescriptionbooleansuccess — True if the archive was successfully unmounted, false otherwise. unmount Type: Function. Description: Unmounts a zip file or folder previously mounted for reading with love.filesystem.mount. Signature: unmount: function(archive: FileData): boolean Parameters: ParameterTypeDescriptionarchiveFileDataThe folder or zip file in the game's save directory which is currently mounted. Returns: Return TypeDescriptionbooleansuccess — True if the archive was successfully unmounted, false otherwise. isFused Type: Function. Description: Gets whether the game is in fused mode or not. If a game is in fused mode, its save directory will be directly in the Appdata directory instead of Appdata/LOVE/. The game will also be able to load C Lua dynamic libraries which are located in the save directory. A game is in fused mode if the source .love has been fused to the executable (see Game Distribution), or if '--fused' has been given as a command-line argument when starting the game. Signature: isFused: function(): boolean Returns: Return TypeDescriptionbooleanTrue if the game is in fused mode, false otherwise. newFile Type: Function. Description: Creates a new File object. -- It needs to be opened before it can be accessed. Signature: newFile: function(filename: string): File Parameters: ParameterTypeDescriptionfilenamestringThe filename of the file. Returns: Return TypeDescriptionFilefile — The new File object. newFile Type: Function. Description: Creates a new File object. -- It needs to be opened before it can be accessed. Signature: newFile: function(filename: string, mode: OpenFileMode): File Parameters: ParameterTypeDescriptionfilenamestringThe filename of the file.modeOpenFileModeThe mode to open the file in. Returns: Return TypeDescriptionFileThe new File object, or nil if an error occurred. newFileData Type: Function. Description: Creates a new FileData object from a file on disk, or from a string in memory. Signature: newFileData: function(filename: string): FileData Parameters: ParameterTypeDescriptionfilenamestringPath to the file. Returns: Return TypeDescriptionFileDatadata — The new FileData. newFileData Type: Function. Description: Creates a new FileData object from a file on disk, or from a string in memory. Signature: newFileData: function(file: File): FileData Parameters: ParameterTypeDescriptionfileFilePath to the file. Returns: Return TypeDescriptionFileDataThe new FileData, or nil if an error occurred. newFileData Type: Function. Description: Creates a new FileData object from a file on disk, or from a string in memory. Signature: newFileData: function(data: string, filename: string): FileData Parameters: ParameterTypeDescriptiondatastringThe Data object to copy into the new FileData object.filenamestringThe name of the file. The extension may be parsed and used by LÖVE when passing the FileData object into love.audio.newSource. Returns: Return TypeDescriptionFileDataThe new FileData, or nil if an error occurred. read Type: Function. Description: Read the contents of a file. Signature: read: function(filename: string, size?: integer): string | nil, number | string Parameters: ParameterTypeDescriptionfilenamestringThe name (and path) of the file.sizeintegerHow many bytes to read. (Default: all.) Returns: Return TypeDescriptionstring | nilcontents — The file contents.number | stringsize — How many bytes have been read. read Type: Function. Description: Read the contents of a file. Signature: read: function(container: string, filename: string, size?: integer): string | nil, number | string Parameters: ParameterTypeDescriptioncontainerstringWhat type to return the file's contents as.filenamestringThe name (and path) of the filesizeintegerHow many bytes to read (Default: all.) Returns: Return TypeDescriptionstring | nilreturns nil as content.number | stringsize — How many bytes have been read. read Type: Function. Description: Read the contents of a file. Signature: read: function(container: string, filename: string, size?: integer): FileData | nil, number | string Parameters: ParameterTypeDescriptioncontainerstringWhat type to return the file's contents as.filenamestringThe name (and path) of the filesizeintegerHow many bytes to read (Default: all.) Returns: Return TypeDescriptionFileData | nilFileData or string containing the file contents.number | stringsize — How many bytes have been read. load Type: Function. Description: Loads a Lua file (but does not run it). Signature: load: function(filename: string): function | nil, string | nil Parameters: ParameterTypeDescriptionfilenamestringThe name (and path) of the file. Returns: Return TypeDescriptionfunctionThe loaded chunk.string or nilThe error message if file could not be opened. lines Type: Function. Description: Iterate over the lines in a file. Signature: lines: function(filename: string): function(): string | nil Parameters: ParameterTypeDescriptionfilenamestringThe name (and path) of the file Returns: Return TypeDescriptionfunction or string or nilA function that iterates over all the lines in the file write Type: Function. Description: Write data to a file in the save directory. If the file existed already, it will be completely replaced by the new contents. Signature: write: function(filename: string, data: string, size?: integer): boolean, string | nil Parameters: ParameterTypeDescriptionfilenamestringThe name (and path) of the file.datastringThe string data to write to the file.sizeintegerHow many bytes to write. (Default: all.) Returns: Return TypeDescriptionbooleansuccess — If the operation was successful.string | nilmessage — Error message if operation was unsuccessful. write Type: Function. Description: Write data to a file in the save directory. If the file existed already, it will be completely replaced by the new contents. Signature: write: function(filename: string, data: FileData, size?: integer): boolean, string | nil Parameters: ParameterTypeDescriptionfilenamestringThe name (and path) of the file.dataFileDataThe Data object to write to the file.sizeintegerHow many bytes to write. (Default: all.) Returns: Return TypeDescriptionbooleansuccess — If the operation was successful.string | nilmessage — Error message if operation was unsuccessful. append Type: Function. Description: Append data to an existing file. Signature: append: function(filename: string, data: string, size?: integer): boolean, string | nil Parameters: ParameterTypeDescriptionfilenamestringThe name (and path) of the file.datastringThe string data to append to the file.sizeintegerHow many bytes to write. (Default: all.) Returns: Return TypeDescriptionbooleansuccess — True if the operation was successful, or nil if there was an error.string | nilerrormsg — The error message on failure. append Type: Function. Description: Append data to an existing file. Signature: append: function(filename: string, data: FileData, size?: integer): boolean, string | nil Parameters: ParameterTypeDescriptionfilenamestringThe name (and path) of the file.dataFileDataThe Data object to append to the file.sizeintegerHow many bytes to write. (Default: all.) Returns: Return TypeDescriptionbooleansuccess — True if the operation was successful, or nil if there was an error.string | nilerrormsg — The error message on failure. getInfo Type: Function. Description: Gets information about the specified file or directory. Signature: getInfo: function(filename: string): FileInfo | nil Parameters: ParameterTypeDescriptionfilenamestringThe file or directory path to check. Returns: Return TypeDescriptionFileInfo | nilinfo — A table containing information about the specified path, or nil if nothing exists at the path. The table contains the following fields: getInfo Type: Function. Description: Gets information about the specified file or directory. Signature: getInfo: function(filename: string, filter_type: FileType): FileInfo | nil exists: function(filename: string): boolean isDirectory: function(filename: string): boolean isFile: function(filename: string): boolean isSymlink: function(filename: string): boolean getLastModified: function(filename: string): number | nil, string | nil getSize: function(filename: string): number | nil, string | nil Parameters: ParameterTypeDescriptionfilenamestringThe file or directory path to check.filter_typeFileTypeCauses getInfo to only return the info table if the item at the given path matches the specified file type. Returns: Return TypeDescriptionFileInfo | nilThe table given as an argument, or nil if nothing exists at the path. The table will be filled in with the following fields: createDirectory Type: Function. Description: Recursively creates a directory. When called with 'a/b' it creates both 'a' and 'a/b', if they don't exist already. Signature: createDirectory: function(name: string): boolean, string | nil Parameters: ParameterTypeDescriptionnamestringThe directory to create. Returns: Return TypeDescriptionbooleanTrue if the directory was created, false if not. remove Type: Function. Description: Removes a file or empty directory. Overload details: The directory must be empty before removal or else it will fail. Simply remove all files and folders in the directory beforehand. If the file exists in the .love but not in the save directory, it returns false as well. An opened File prevents removal of the underlying file. Simply close the File to remove it. Signature: remove: function(name: string): boolean, string | nil Parameters: ParameterTypeDescriptionnamestringThe file or directory to remove. Returns: Return TypeDescriptionbooleanTrue if the file/directory was removed, false otherwise. getDirectoryItems Type: Function. Description: Returns a table with the names of files and subdirectories in the specified path. The table is not sorted in any way; the order is undefined. If the path passed to the function exists in the game and the save directory, it will list the files and directories from both places. Signature: getDirectoryItems: function(directory?: string): {string} Parameters: ParameterTypeDescriptiondirectorystringThe directory. Returns: Return TypeDescription{string}A sequence with the names of all files and subdirectories as strings.