Filesystem Module

The Filesystem submodule contains functions related to folders and files from the sdcard or the game extdata. You can access sdcard by using sdmc:/ prefix at the start of a path, or extdata:/ to access game extdata

Note: If the game has not yet created the extdata, it will not work until the next game launch.

Core.Filesystem.open

Opens a file. Returns nil if the file wasn't opened with an error message. It will return a FilesystemFile object that contains methods that you can use to read or write to the file. Check FilesystemFile methods.

local optionsFile = Core.Filesystem.open("extdata:/options.txt", "r")
if optionsFile then -- Checks that optionsFile is not nil, in other words, that the file opened successfully
    --- < your code here >
else
    Core.Debug.message("Failed to open extdata:/options.txt")
end

Core.Filesystem.fileExists

Checks if the path exists and is a file

if Core.Filesystem.fileExists("sdmc:/yourfile.txt") then
    --- < your code here >
end

Core.Filesystem.directoryExists

Checks if the path exists and is a directory

if Core.Filesystem.directoryExists("sdmc:/path/to/folder") then
    --- < your code here >
end

Core.Filesystem.getDirectoryElements

If the directory exists, it will return a table that contains all elements inside that directory

local function iterateRDir(path)
    local elements = Core.Filesystem.getDirectoryElements(path)
    for index, value in ipairs(elements) do
        Core.Debug.message(path..value)
        if Core.Filesystem.directoryExists(path..value) then -- directoryExists can also be used to detect if a path is a directory
            iterateRDir(path..value.."/")
        end
    end
end

iterateRDir("extdata:/")

Core.Filesystem.createDirectory

Creates the provided directory and returns if success. It will fail if the directory already exists

if Core.Filesystem.createDirectory("sdmc:/path/to/folder") then
    --- < success >
else 
    --- < failure >
end

FilesystemFile Methods

FilesystemFile:read

It reads the specified amount of bytes, or you can use "*all" to read all file and returns the data in a string, or nil if an error occurs

local optionsFile = Core.Filesystem.open("extdata:/options.txt", "r")
if optionsFile then -- Checks that optionsFile is not nil, in other words, that the file opened successfully
    local optionsData = optionsFile:read("*all")
    --- < your code here >
else
    Core.Debug.message("Failed to open extdata:/options.txt")
end

FilesystemFile:write

It writes the data provided, by default it will write all, but if specified it will write the provided amount of bytes

local myFile = Core.Filesystem.open("sdmc:/yourfile.txt", "w")
if myFile then -- Checks that the file is not nil
    myFile:write("data to write")
    --- < your code here >
else
    Core.Debug.message("Failed to open file")
end

FilesystemFile:tell

It returns the current position in the file

local myFile = Core.Filesystem.open("sdmc:/yourfile.txt", "w")
if myFile then -- Checks that the file is not nil
    myFile:write("data to write")
    local pos = myFile:tell()
    --- < your code here >
else
    Core.Debug.message("Failed to open file")
end

FilesystemFile:flush

Flushes all file data in the write buffer. Not needed but sometimes may be useful

local myFile = Core.Filesystem.open("sdmc:/yourfile.txt", "w")
if myFile then -- Checks that the file is not nil
    myFile:write("data to write")
    myFile:flush()
    --- < your code here >
else
    Core.Debug.message("Failed to open file")
end

FilesystemFile:seek

Sets the position in file and returns the new position or nil if error. By default it takes "set" as the origin if not provided origin, but you can use "cur" or "end" as well

local myFile = Core.Filesystem.open("sdmc:/yourfile.txt", "w+")
if myFile then -- Checks that the file is not nil
    myFile:seek(0, "end")
    myFile:write("data to write")
    --- < your code here >
else
    Core.Debug.message("Failed to open file")
end

FilesystemFile:isOpen

Checks if the file is open, useful if you are not sure if the file was previously closed

local myFile = Core.Filesystem.open("sdmc:/yourfile.txt", "r")
if myFile and myFile:isOpen() then -- Checks that the file is not nil
    --- File is open
    --- < your code here >
else
    Core.Debug.message("Failed to open file")
end

FilesystemFile:isEOF

Checks if the current position is at the end of the file

local myFile = Core.Filesystem.open("sdmc:/yourfile.txt", "r")
if myFile then -- Checks that the file is not nil
    --- < your code here >
    if myFile:isEOF() then
        --- < do something >
else
    Core.Debug.message("Failed to open file")
end

FilesystemFile:close

Closes the file if it is open, otherwise does nothing. Is not strictly neccessary to use this method as the file will close when the lua gc collects this object if is still open, but it is still a good practice to explicity close the file

local myFile = Core.Filesystem.open("sdmc:/yourfile.txt", "r")
if myFile then -- Checks that the file is not nil
    --- < your code here >
    myFile:close()
else
    Core.Debug.message("Failed to open file")
end