Difference between revisions of "LuaAPI/filesystem"

From The Battle for Wesnoth Wiki
(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''[, ''only_as_regular_file'']) → ''boolean''
+
* '''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"
</syntax_highlight>
+
</syntaxhighlight>
  
 
=== filesystem.have_asset ===
 
=== filesystem.have_asset ===
Line 46: Line 48:
 
* '''filesystem.resolve_asset'''(''asset_type'', ''path'') &rarr; ''resolved path''
 
* '''filesystem.resolve_asset'''(''asset_type'', ''path'') &rarr; ''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.

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.

This page was last edited on 18 April 2024, at 18:04.