fs.md

fs

Summary

geode.fs reads and writes files inside the running mod's own directories. Every call takes a root as its first argument. The root selects one of the mod's directories, and access is sandboxed to it. A path that escapes the root (for example with ..) or an absolute path is rejected.

Root	Directory	Access
"save"	getSaveDir()	read + write
"config"	getConfigDir()	read + write
"persistent"	getPersistentDir()	read + write
"resources"	getResourcesDir()	read only

An unknown root raises a Lua error.

Recoverable failures return nil and an error string. See globals Error shapes.

Symlinks

Paths are canonicalized before the sandbox check. A symlink inside a root that resolves outside the root is rejected. LuauAPI never creates symlinks.

read

geode.fs.read(root: FsRoot, path: string) -> (string?, string?)

Reads a file's contents. Returns the contents, or nil and an error message.

write

geode.fs.write(root: FsRoot, path: string, data: string) -> (boolean?, string?)

Writes data to a file, creating parent directories as needed. Returns true, or nil and an error message. Writing to the read-only resources root fails.

exists

geode.fs.exists(root: FsRoot, path: string) -> (boolean?, string?)

Returns true when a file or directory exists, false when missing. Returns nil and an error message when the path escapes the root or the filesystem fails.

list

geode.fs.list(root: FsRoot, path: string) -> ({ string }?, string?)

Lists the immediate entries of a directory (names, not full paths, not recursive). Returns an array table, or nil and an error message. Listings are capped.

mkdir

geode.fs.mkdir(root: FsRoot, path: string) -> (boolean?, string?)

Creates a directory and any missing parents. Returns true, or nil and an error message. Fails on the read-only resources root.

remove

geode.fs.remove(root: FsRoot, path: string) -> (boolean?, string?)

Removes a single file or empty directory (never recursive). Returns true, or nil and an error message. A missing path still returns true. Fails on the read-only resources root.

Limits

Reads, writes, and directory listings are capped.

See Limits and errors.

Example

local data = geode.json.dump({ count = 3 })
assert(geode.fs.write("save", "state.json", data))

if geode.fs.exists("save", "state.json") then
    local text = geode.fs.read("save", "state.json")
    print(geode.json.parse(text).count) -- 3
end

local entries, err = geode.fs.list("save")
if not entries then return print(err) end
for _, name in ipairs(entries) do
    print(name)
end

Related

• json
• mod
• globals
• Limits and errors
• Getting started

Source

• src/bindings/geode/GeodeFsBinding.cpp
• src/bindings/geode/ModSandbox.cpp
• src/require/PathSandbox.hpp
• tools/luau_codegen/extra_bindings/fs.dluau