LuaAPI/filesystem

This module contains functions for working with files on disk, providing read-only access to the data and userdata directories.

filesystem.read_file

• filesystem.read_file(file_path) → file_contents

Loads a file into memory and returns it as a string. The rules for locating the files are the same as for WML files, but with no requirements on file extension. If the path points to a directory, it instead returns a table containing a list of directory entries, sorted alphabetically with directories grouped at the beginning. In this case, there is also an ndirs member which contains the number of entries that are directories, allowing you to easily skip the directories if you wish.

filesystem.have_file

• filesystem.have_file(file_path, [only_as_regular_file]) → boolean

Checks if a file exists. The rules for locating the files are the same as for WML files. Using the second parameter, you can distinguish regular files from directories.

filesystem.canonical_path

• filesystem.canonical_path(file_path) → path

Returns the path resolved relative to the current script and with any dotfiles stripped out. The returned path is still relative to the data or userdata directory.

filesystem.image_size

• filesystem.image_size(filename) → width, height

Returns the width and height of an image.

<syntaxhighlight lang=lua> local w, h = filesystem.image_size "units/transport/galleon.png" </syntax_highlight>

filesystem.have_asset

• filesystem.have_asset(asset_type, path) → exists

Tests whether an asset file exists in the current binary path. The asset_type will usually be one of the following constants in filesystem.asset_type:

• IMAGE
• MUSIC
• MAP
• SOUND

However, it can be any arbitrary string. You could conceivably define a custom asset type in this way.

filesystem.resolve_asset

• filesystem.resolve_asset(asset_type, path) → resolved path

Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will always begin with the string "data/". This makes it suitable to be assigned to anything that expects an image path, but if you wish to load the file with wesnoth.read_file, this prefix must be stripped off.