Filesystem Rework

[bjornbytes]

Goals

• Make it easier to read/write absolute paths, since this is a common request.
• Make the virtual filesystem easier to understand. It seems to be causing more pain/confusion than the benefits you get from layering archives. This intends to replace the virtual filesystem with a combination of Archive objects (for reading data from ZIP files) and @-aliases that can serve as a way to read data from common folder paths. This is a more explicit system that makes it clear which paths are being accessed. You can still recreate a virtual filesystem in Lua using Archive objects.
• Relative require. It comes up frequently and is painful.
• Ability to create ZIP archives, so we can add a lovr --package . command.
• Miscellaneous things that have come up before: symlinks, drag-and-drop events.

Examples

-- Relative paths read from your source
lovr.filesystem.read('main.lua)
lovr.graphics.newTexture('texture.png')

-- @save folder
lovr.filesystem.write('gamestate.json', data) -- or @save/gamestate.json
lovr.filesystem.read('@save/gamestate.json')

-- Archive object
local archive = lovr.filesystem.newArchive('level.zip')
archive:getDirectoryItems('/')
archive:read('manifest.ini')

-- Relative require
local utils = require('./utils') -- TBD, maybe require('@local.utils'), '@self/utils', etc.

function lovr.filedropped(path)
  --
end

Notes

Absolute Paths

• Reads with relative paths are relative to the source directory/archive.
• Writes with relative paths are relative to the save directory.
  • Note: this breaks the symmetry where you can do lf.write('file.txt', 'asdf') followed by lf.read('file.txt') to get the contents back. I think this is okay.
• Reads/writes support absolute paths.

Aliases

• Remove mounted archives.
• Add @-aliases for common paths. Paths can start with these, which get expanded to their full path, for convenience.
  • @source - lovr.filesystem.getSourceDirectory()
  • @save - lovr.filesystem.getSaveDirectory()
  • @executable - lovr.filesystem.getExecutablePath() with filename chopped off (just the directory)
• Relative Require
  • Either allow ./ and ../ in require paths (though it doesn't work when using dotted module names) or make require expand aliases and add an alias that resolves to the directory containing the current file (@self? @parent? @dir? @local?)

Archive

• Add Archive object that can be used to access contents of ZIP files. It's readonly, and supports methods like :read, :getDirectoryItems, :getSize, :getLastModified.
• Add lovr.filesystem.compress({files}, destination) that creates a ZIP archive? Should be able to support both file paths and blob entries (maybe also strings). Would allow LÖVR to package projects.

Symlinks

• lovr.filesystem.are/setSymlinksEnabled
• lovr.filesystem.isSymlink
• Skip or return error when accessing symlink when they're not enabled
• Detect symlink loops

File Drop Events

• lovr.filedropped(path) event
  • GLFW: glfwSetDropCallback
  • XCB: XDND
  • win32: WM_DROPFILES

[InfernoAmaruq]

Any plans for being able to alias archives? Smth like

lovr.filesystem.alias(Archive,"@game")

And have files in it be accessible through like read("@game/level1.lua")?

I think it'd be quite useful, especially for older projects being ported to newer lovr versions
Though could cause issues with writes?

Edit:
Or could be cool to keep mount() function, but make all files mount to smth like
@virt/<identifier>
So if you try to read @virt/game/file.txt, it will check the archive for said file

[immortalx74]

That is so much needed!
For ./ and ../ what about "current" and "parent"?
Maybe parent alias could be chained too: require"@parent/@parent/utils"

[bjornbytes]

Any plans for being able to alias archives?

Yeah, I was originally thinking there could be custom aliases like that. But it seems like there isn't a big difference between lovr.filesystem.read('@myarchive/file.lua') and myarchive:read('file.lua') (in fact using the Archive object is less typing). Custom aliases don't really help with backwards compatibility either due to the @. They also create 2 ways of reading files from archives: should I just call :read on it, or should I mount it to an alias and use lovr.filesystem.read?

[jmiskovic]

The saveprecedence is now obsolete too, when I can specify '@save/' prefix per-file, great!

All mentioned features (compress, filedropped, isSymlink) are appreciated!

[jimmykingss]

Is there going to be a recursive version of the getDirectoryItems function with this rework? as I don't see it listed

[bjornbytes]

It isn't currently planned, no. I understand the convenience factor, but doing it in Lua is fairly straightforward and lets you customize the recursion a bit (filter out paths you don't care about without having to iterate them, handle symlinks or not, etc.), so I don't think it's a huge need. Still, it's worth keeping in mind.