Problem

In this article we talk about how to use the luafilesystem native shared library in love2d.

Part I: Native Shared Library Module Loading

For quite some time I've been using love2d to build simulations. When I need some functionality not available in love2d, I've used a 3-rd party open source lua library. However I've only been able to use "pure lua" libraries. Any libraries that are built as a native shared-library has been a problem.

A lua native shared library is a lua library implemented in C and compiled into an OS and LUA version dependent shared library. Since such a library is both dependent on the operating system and on the Lua version it is compatible with, using such a library is more involved than using a "pure lua" library, which is distributed as lua source code files.

Part II: Missing FileSystem API Support

Love2d for good reasons supports reading and writing to just one folder on the file system. This is to maintain compatibility with mobile operating system environements. However if one is writing an application which will only run on desktop OSes, then we have the entire file system available. In such a case the love.filesystem API is not useful, and one needs to use something like lfs/luafilesystem.

Solution

The solution is to use a Love2D compatible version of luafilesystem for the operating system one is targeting.

Build an lfs.dll Compatible with Love2d

In this section I describe steps to build Love2d compatible version of luafilesystem on Windows.

Pre-requisites

Love2d is binary compatible with Luajit 2.1 and Lua 5.1. This means we need to create a Lua installation for one of these versions to be able to build an lfs version compatible with love2d.

So we need to perform the following steps:

1. Setup Love2d compatible Lua environment
2. Install luarocks in the same environment
3. Build and install luafilessytem using luarocks in the above environment.
4. Use lfs.dll build in step#3 in love2d.

Hererocks Luajit environment (Step 1 & 2 above)

Install hererocks using pip.

pip install git+https://github.com/luarocks/hererocks

Open "x64 Visual Studio Tools" command prompt and use hererocks to build luajit environment.

The command below installs luajit v2.1 and latest luarocks:

hererocks luajit21_love -j 2.1 -r latest

Install LFS (Step 3)

Activate the newly created lua environment

luajit21_love\bin\activate.bat

Install lfs using luarocks

luarocks install luafilesystem

Use lfs.dll (Step 4)

Copy the resultant lfs.dll into the love2d program folder.

copy luajit21_love\lib\lua\5.1\lfs.dll <lua_program_folder>\

Now one can use love . in the with require 'lfs' in main.lua. See the main.lua in this simulation to see how to use lfs in love2d.

--- main.lua: lfs Usage Simulation in LÖVE
-- date: 4/4/2024
-- author: Abhishek Mishra

local lfs = require 'lfs'

local currentDir
local filesInDir

--- love.load: Called once at the start of the simulation
function love.load()
    -- get the current directory
    currentDir = lfs.currentdir()

    -- get the files in the current directory
    filesInDir = {}
    for f in lfs.dir(currentDir) do
        table.insert(filesInDir, f)
    end
end

--- love.update: Called every frame, updates the simulation
function love.update(dt)
end

--- love.draw: Called every frame, draws the simulation
function love.draw()
    -- write the current directory path at 10, 10
    -- will get concatenated if it is a long path
    love.graphics.print('Current Directory: ' .. currentDir, 10, 10)

    -- list the files in the folder
    -- again the list might get concatenated if there are too many entries
    for i, val in ipairs(filesInDir) do
        love.graphics.print('--> ' .. tostring(val), 10, 10 + (i * 20))
    end
end

-- escape to exit
function love.keypressed(key)
    if key == "escape" then
        love.event.quit()
    end
end