File System

API Folder Location : C:\Users\"UserName"\Documents\My Games\

Filesystem API that allows scripts to read, write, and manage files only inside the main scripting directory.

Scripts cannot access, modify, create, or query files outside this directory. All paths must be relative and are automatically sandboxed for safety.

---

Overview

The filesystem API provides the following capabilities:

• Create files

• Create directories

• Read files

• Check if a file exists

• List files or directories

• Delete files

• Delete directories

All functions operate only on paths relative to the script directory.

---

Path Rules

To ensure safety and consistency:

✔ Paths must be relative

Absolute paths such as:

/folder/file.txt
C:\temp\log.txt

are not allowed.

✔ Parent-directory traversal is not allowed

Paths cannot contain:

..

✔ Scripts cannot escape the main scripting directory

Every operation is automatically constrained to the script directory.

---

Global Functions

All filesystem functions are available as global Lua functions.

---

create_file(path, [data]) → boolean

Creates or overwrites a file.

Example:

create_file("data/info.txt", "Hello World!")

---

create_directory(path) → boolean

Creates a directory (non-recursive).

Example:

create_directory("data/logs")

---

read_file(path) → boolean, string

Reads a file and returns (success, contents).

Example:

local ok, text = read_file("data/info.txt")
if ok then
    print(text)
end

---

does_file_exist(path) → boolean

Checks if a file exists.

Example:

if does_file_exist("data/info.txt") then
    print("found")
end

---

query_directory(path, include_dirs?, include_files?, extensions_table?) → boolean, table

Lists the contents of a directory.

Parameters:

Name	Type	Default	Description
path	string	required	Directory to list
include_dirs	boolean	true	Include subdirectories
include_files	boolean	true	Include files
extensions_table	table	nil	Filter by extensions, e.g. { ".txt" }

Example:

local ok, items = query_directory("data", true, true)
if ok then
    for i, name in ipairs(items) do
        print(name)
    end
end

Filter example:

local ok, jsons = query_directory("data", false, true, { ".json" })

---

delete_file(path) → boolean

Deletes a file.

Example:

delete_file("data/old.txt")

---

delete_directory(path) → boolean

Deletes a directory (may require the directory to be empty).

Example:

delete_directory("data/temp")

---

Example Test Script

A simple script to confirm everything is working:

function main()
    print("=== FS TEST START ===")

    create_directory("fs_tests")
    create_file("fs_tests/test.txt", "hello test")

    local ok, data = read_file("fs_tests/test.txt")
    print("read ok:", ok, "data:", data)

    local ok_q, items = query_directory("fs_tests")
    if ok_q then
        for _, name in ipairs(items) do
            print(" -", name)
        end
    end

    delete_file("fs_tests/test.txt")
    delete_directory("fs_tests")

    print("=== FS TEST END ===")
    return 0;
end