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 are available as global AngelScript functions.

---

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

bool create_file(const string &in path, const string &in data = "")

Creates or overwrites a file at the given relative path.

• path — relative file path under the main scripting directory

• data — optional file contents (defaults to empty)

bool ok = create_file("data/info.txt", "Hello World!");

---

bool create_directory(const string &in path)

Creates a directory (non-recursive).

bool ok = create_directory("data/logs");

---

bool read_file(const string &in path, string &out data)

Reads a file and returns its contents through an output parameter.

• Returns true on success, false if the file does not exist or could not be read.

string text;
bool ok = read_file("data/info.txt", text);
if (ok)
{
    log("File contents: " + text);
}

---

bool does_file_exist(const string &in path)

Checks if a file exists.

if (does_file_exist("data/info.txt"))
{
    log("File exists");
}

---

`bool query_directory(const string &in path,

bool include_dirs, bool include_files, const array<string> &in extensions, array<string> &out entries)`

Lists the contents of a directory.

Parameters

• path — relative directory path under the main scripting directory

• include_dirs — if true, include subdirectories in the results

• include_files — if true, include files in the results

• extensions — list of file extensions to include; pass an empty array for no filter

• entries — output array that will be filled with names (no directory prefix)

Example

array<string> entries;
array<string> noFilter; // empty

bool ok = query_directory("data", true, true, noFilter, entries);
if (ok)
{
    for (uint i = 0; i < entries.length(); ++i)
    {
        log("Entry: " + entries[i]);
    }
}

Filtered example

array<string> exts = { ".json" };
array<string> jsonFiles;

bool ok = query_directory("data", false, true, exts, jsonFiles);
if (ok)
{
    for (uint i = 0; i < jsonFiles.length(); ++i)
    {
        log("JSON: " + jsonFiles[i]);
    }
}

---

bool delete_file(const string &in path)

Deletes a file.

bool ok = delete_file("data/old.txt");

---

bool delete_directory(const string &in path)

Deletes a directory. Depending on configuration, the directory may need to be empty.

bool ok = delete_directory("data/temp");

---

Example Test Script

A simple AngelScript example that exercises all functions:

int main()
{
    log("=== AS FS TEST START ===");

    // 1) Create a directory
    bool ok = create_directory("fs_tests");
    log("create_directory: " + string(ok ? "true" : "false"));

    // 2) Create a file
    ok = create_file("fs_tests/test.txt", "Hello from AngelScript FS API!\n");
    log("create_file: " + string(ok ? "true" : "false"));

    // 3) Read it back
    string data;
    ok = read_file("fs_tests/test.txt", data);
    log("read_file: " + string(ok ? "true" : "false"));
    if (ok)
        log("data = " + data);

    // 4) Check existence
    bool exists = does_file_exist("fs_tests/test.txt");
    log("does_file_exist: " + string(exists ? "true" : "false"));

    // 5) Query directory
    array<string> entries;
    array<string> noFilter;
    ok = query_directory("fs_tests", true, true, noFilter, entries);
    log("query_directory: " + string(ok ? "true" : "false"));
    if (ok)
    {
        for (uint i = 0; i < entries.length(); ++i)
            log("entry: " + entries[i]);
    }

    // 6) Delete file + directory
    ok = delete_file("fs_tests/test.txt");
    log("delete_file: " + string(ok ? "true" : "false"));

    ok = delete_directory("fs_tests");
    log("delete_directory: " + string(ok ? "true" : "false"));

    log("=== AS FS TEST END ===");
    return 1; // keep script loaded
}