Harmony Lua

file ​

Read and write files within the Harmony game directory.

The file API is restricted to the current game's Harmony directory, normally Documents/Harmony/Red Dead Redemption 2, including its LUA and Network subdirectories. Paths can be relative to that root or absolute paths inside it. Parent directories must already exist.

Functions ​

file.directory ​

Absolute Harmony game directory.

text
file.directory()

file.lua_directory ​

Absolute LUA directory.

text
file.lua_directory()

file.network_directory ​

Absolute Network directory.

text
file.network_directory()

file.create ​

Creates a new file; true if created, false if already present. Contents default to empty.

text
file.create(path[, contents])

file.exists ​

Whether a permitted regular file exists.

text
file.exists(path)

file.read ​

Complete binary-safe contents.

text
file.read(path)

file.write ​

Creates or replaces a permitted file's contents; returns true.

text
file.write(path, contents)

file.remove ​

Removes a file; false if absent, otherwise true. Never removes directories.

text
file.remove(path)

Invalid/forbidden paths and I/O failures raise Lua errors; use pcall to handle them. credentials.bin is forbidden case-insensitively at every path component. Traversal, device/UNC paths, alternate streams, trailing dots/spaces, short-name aliases, hard links, symbolic links and junctions are rejected. Ancestors are pinned while accessing the opened file, and its normalized final path is checked before content access. Read/write contents are capped at 1 MiB. Linked or otherwise unsupported data-directory layouts fail closed.

The same access checks cover entry scripts and require() modules. loadfile and dofile are unavailable. require("a.b") searches only LUA/a/b.lua and LUA/a/b/init.lua; changing package.path does not widen that boundary. Native DLL loaders remain disabled. This is a file-API boundary, not isolation of untrusted Lua: the existing native and raw-memory APIs still require trusted scripts.

lua
local path = file.lua_directory() .. "/example-settings.json"
if not file.exists(path) then
    file.create(path, json.encode({enabled = true}))
end
local settings = json.decode(file.read(path))
-- file.remove(path)