Filesystem

Minetest provides various utility functions to help with managing paths, files & directories.

IMPORTANT: Mod security restricts file system access to the mod path (at load time) and the world path later on in secure environments, see Lua Environment.

Paths

WARNING: Always operate on absolute paths, never on relative ones; no assumption about the current working directory can be made.

Normalization

Minetest normalizes paths you pass into filesystem-related functions, replacing / with the platform-specific path delimiter (usually \ on Windows, / on UNIX).

Using / in paths is thus always fine. However, paths returned by Minetest are usually not normalized.

DIR_DELIM

Global variable which holds the path delimiter as a {type-string} (usually \ on Windows, / on UNIX).

Usually not necessary due to path normalization (perhaps only necessary when parsing paths), but may be used "for good measure" (user-friendly paths using the platform-specific delimiters).

minetest.get_modpath

Gets the path of a mod, if it is loaded. If the mod isn't loaded, it will return nil.

Arguments:

• modname - {type-string}: The mod name

TIP: Use local modpath = minetest.get_modpath(minetest.get_current_modname()) rather than hardcoding your modname.

Returns:

• modpath - {type-string}: The absolute, non-normalized path to the mod directory

minetest.get_worldpath

No arguments.

Returns:

• worldpath - {type-string}: The absolute, non-normalized path to the world directory

Directories

Common Returns

• success - {type-bool}: Whether the operation succeeded.

TIP: Use assert to error on failure.

minetest.mkdir

Creates a directory and nonexistent parent directories.

Arguments:

• path - {type-string}: Path to the directory to create

minetest.cpdir

Copies a source directory to a destination.

Arguments:

• source_path - {type-string}: Path to the source directory to copy
• destination_path - {type-string}: Path to the destination directory

CAUTION: If the destination directory exists already, it will be overwritten.

minetest.mvdir

Moves a source directory to a destination.

If the destination is a non-empty directory, the move will fail.

Arguments:

• source_path - {type-string}: Path to the source directory to copy
• destination_path - {type-string}: Path to the destination directory

minetest.rmdir

Removes a directory.

Arguments:

• path - {type-string}: Path to the directory to remove.
• recursive - {type-bool}: Whether to recursively delete the directory's content; if this is not set to true, removal will fail if the directory is nonempty

minetest.get_dir_list

Lists direct directory contents.

Arguments:

• path - {type-string}: Path to the directory to remove.
• is_dir - {type-nil} or {type-bool}: Whether to list:
  • nil: Both directories and files
  • true: Only directories
  • false: Only files

Returns:

• entry_list - list of {type-string}: List of entry names - not paths!; you should make no assumptions concerning the order of this list.

Files

minetest.safe_file_write

Performs an atomic binary file write: Either all or nothing is overwritten. This is done by creating a temporary file, writing to it, then swapping with the temporary file.

Use this function to prevent corruption of save files.

Using minetest.safe_file_write(path, content) would be equivalent to

local f = io.open(path, "wb")
f:write(content)
f:close()

if this code block was atomic.

Arguments:

• path - {type-string}: Path to the file to write.
• content - {type-string}: The content to write.

Returns:

• success - {type-bool}: Whether the operation succeeded.

Lua builtins

All properly overridden by Minetest to apply mod security restrictions.

• io.open(filename, mode): Open a file for reading or writing.
  • IMPORTANT: Use rb and wb rather than r and w for working with binary files, otherwise your code will break on Windows.
• io.lines([filename]): Get an iterator over the lines of a file.
• io.tmpfile(): Get a handle for a temporary file.
• os.tmpname(): Get a name for a temporary file.
• os.remove(filename): Removes an entry (file or empty directory)
• os.rename(oldname, newname): Moves/renames an entry (file or directory)

---

This article is originally based on an article from the minetest_docs project: fs.adoc by Lars Müller, licensed under CC-BY 4.0