Files

The Files namespace provides access to the in-game virtual file system. Create, read, modify, and navigate files and folders that appear in the player's computer.

Required permission: filesystem

Import

import { Files } from "@hotbunny/hackhub-content-sdk";

Methods

Files.create(options)

Create a new file or folder.

Parameter	Type	Description
options.name	string	File name (without extension)
options.extension	string?	File extension (e.g. "txt", "png")
options.data	string?	File content
options.parentPath	string?	Parent folder path (defaults to home)
options.isFolder	boolean?	Create a folder instead of a file

Returns: Promise<FileInfo>

const file = await Files.create({
    name: "readme",
    extension: "txt",
    data: "Hello world!",
    parentPath: "~/Documents",
});

Files.createTree(parentPath, tree)

Create a nested file/folder structure in one call.

Parameter	Type	Description
parentPath	string	Path to the parent directory
tree	FileDefinition[]	Nested structure to create

await Files.createTree("~/Projects", [
    {
        name: "my-project",
        isFolder: true,
        children: [
            { name: "index", extension: "html", data: "<h1>Hello</h1>" },
            { name: "style", extension: "css", data: "body { color: red; }" },
        ],
    },
]);

Files.getByPath(path)

Get a file by its virtual path.

Returns: Promise<FileInfo | null>

const file = await Files.getByPath("~/Documents/readme.txt");
if (file) {
    console.log(file.id, file.data);
}

Files.getById(id)

Get a file by its internal ID.

Returns: FileInfo | null

Files.getChildren(folderId)

Get all children of a folder.

Returns: Promise<FileInfo[]>

const home = await Files.getByPath("~");
const children = await Files.getChildren(home!.id);

Files.remove(id)

Delete a file by its ID.

const file = await Files.getByPath("~/temp.txt");
if (file) Files.remove(file.id);

Files.rename(id, newName)

Rename a file (name only, not extension).

Files.move(id, newParentId)

Move a file to a different folder.

Files.read(id)

Read the text content of a file.

Returns: string | undefined

Files.write(id, data)

Overwrite the content of a file.

const file = await Files.getByPath("~/notes.txt");
if (file) Files.write(file.id, "Updated content");

Files.exists(path)

Check if a file or folder exists at a given path.

Returns: Promise<boolean>

if (await Files.exists("~/secret.txt")) {
    console.log("File found!");
}

Files.getHomePath()

Get the home directory path. Returns "~" which resolves to the player's user folder.

Returns: string

const home = Files.getHomePath(); // "~"
const file = await Files.getByPath(home); // resolves to user folder

Files.getDesktopPath()

Get the desktop directory path. Returns "~/desktop".

Returns: string

const desktopPath = Files.getDesktopPath(); // "~/desktop"
await Files.create({
    name: "shortcut",
    extension: "lnk",
    parentPath: desktopPath,
});

Files.getRootPath()

Get the filesystem root path. Always returns "/".

Returns: string

Files.getRoot()

Get the filesystem root folder as a FileInfo. Useful for walking the tree from the top (e.g. to reach virtual absolute folders like /etc or /home).

Returns: Promise<FileInfo | null>

const root = await Files.getRoot();
if (root) {
    const top = await Files.getChildren(root.id);
    console.log(top.map(f => f.name)); // ["bin", "etc", "home", ...]
}

Files.resolvePath(path, cwd?)

Resolve a relative, ~-based or absolute path into a normalized absolute path. Handles ., .., ~ (home) and / (root).

Parameter	Type	Description
path	string	The path to resolve
cwd	string?	Base directory for relative paths (defaults to the current working directory)

Returns: Promise<string>

await Files.resolvePath("../logs", "/home/user/app"); // "/home/user/logs"
await Files.resolvePath("~/notes.txt");               // "/home/user/notes.txt"
await Files.resolvePath("/etc/passwd");               // "/etc/passwd"

Files.getCurrentWorkingDirectory()

Get the absolute path of the directory the current terminal command is running in. Outside of a terminal command this falls back to the user's home directory.

Returns: Promise<string>

Files.isRemoteSession()

Whether the current terminal command is executing inside an active SSH session on a remote host. Use it to branch behaviour between the player's own PC and a compromised remote box.

Returns: boolean

if (Files.isRemoteSession()) {
    // path-based calls below resolve against the REMOTE machine
    const cwd = await Files.getCurrentWorkingDirectory();
}

Local vs. remote (SSH) filesystem

When a terminal command runs inside an active SSH session, the path-based helpers resolve against the remote machine's filesystem (its root, and the SSH user's home for ~):

create, createTree, getByPath, exists, resolvePath, getRoot and getCurrentWorkingDirectory.

Everywhere else — and for any call made outside a running command — they resolve against the player's own PC. ID-based operations (getById, read, write, remove, rename, move, getChildren) always act on the exact file referenced by its ID, regardless of session.

Use Files.isRemoteSession() to branch explicitly, and pair this with a command's scope to keep tools in the right context.

Available since SDK v0.18.5

getRootPath, getRoot, resolvePath, getCurrentWorkingDirectory, isRemoteSession and the remote-session path resolution require @hotbunny/[email protected] or newer. Run npm install @hotbunny/hackhub-content-sdk@latest to update.

Types

FileInfo

interface FileInfo {
    id: string;
    name: string;
    extension?: string;
    isFolder?: boolean;
    data?: string;
    parent?: string;
    readonly?: boolean;
    hidden?: boolean;
}

FileCreateOptions

interface FileCreateOptions {
    name: string;
    extension?: string;
    data?: string;
    parentPath?: string;
    isFolder?: boolean;
}

FileDefinition

interface FileDefinition {
    name: string;
    extension?: string;
    data?: string;
    isFolder?: boolean;
    children?: FileDefinition[];
    readonly?: boolean;
    hidden?: boolean;
}