Difference between revisions of "LuaAPI/filesystem"
(Categorize) |
|||
| (4 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
This module contains functions for working with files on disk, providing read-only access to the data and userdata directories. | This module contains functions for working with files on disk, providing read-only access to the data and userdata directories. | ||
| + | |||
| + | == Functions == | ||
=== filesystem.read_file === | === filesystem.read_file === | ||
| Line 9: | Line 11: | ||
=== filesystem.have_file === | === filesystem.have_file === | ||
| − | * '''filesystem.have_file'''(''file_path''[ | + | * '''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. | 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. | ||
| Line 21: | Line 23: | ||
=== filesystem.image_size === | === filesystem.image_size === | ||
| − | * '''filesystem.image_size(''filename'')''' → ''width'', ''height' | + | * '''filesystem.image_size(''filename'')''' → ''width'', ''height'' |
Returns the width and height of an image. | Returns the width and height of an image. | ||
| Line 27: | Line 29: | ||
<syntaxhighlight lang=lua> | <syntaxhighlight lang=lua> | ||
local w, h = filesystem.image_size "units/transport/galleon.png" | local w, h = filesystem.image_size "units/transport/galleon.png" | ||
| − | </ | + | </syntaxhighlight> |
=== filesystem.have_asset === | === filesystem.have_asset === | ||
| Line 46: | Line 48: | ||
* '''filesystem.resolve_asset'''(''asset_type'', ''path'') → ''resolved path'' | * '''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. | + | Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will almost always begin with the string "data/<asset_type>/". In the few cases where it doesn't (such as the built-in ellipse images), it still begins with "<asset_type>/". 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. |
[[Category:Lua Reference]] | [[Category:Lua Reference]] | ||
Latest revision as of 18:04, 18 April 2024
This module contains functions for working with files on disk, providing read-only access to the data and userdata directories.
Contents
Functions
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.
local w, h = filesystem.image_size "units/transport/galleon.png"
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 almost always begin with the string "data/<asset_type>/". In the few cases where it doesn't (such as the built-in ellipse images), it still begins with "<asset_type>/". 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.