Files
vfs sees the game’s files. Serve files that aren’t on disk, send the game somewhere else when it opens one, refuse a write, or just watch what it reads.
Paths use forward slashes, like C:/Game/data.pak. Backslashes work going in too, and case doesn’t matter.
Serve a file
Section titled “Serve a file”vfs.put makes a file the game can open, read and list like any other. It hides a real file at the same path.
import { vfs } from "wraith";
vfs.put("C:/Games/Example/config/difficulty.ini", "[Game]\nDifficulty=Hard\n");vfs.put("C:/Games/Example/mods/hat.pak", bytes); // a Uint8Array or ArrayBuffervfs.putDir(path) makes a folder. Files the game creates in it are virtual too, so its saves can live there without touching the disk. Read them back with vfs.read(path), which gives a Uint8Array, or null if there’s no such file.
vfs.remove(path) takes a file or folder away. Whatever the game already has open keeps working. Everything you put goes when your plugin stops. In a tweak, it goes when the tweak turns off.
Watch the game
Section titled “Watch the game”vfs.watch calls you for what the game does with files that match pattern. * matches anything, slashes too, and ? any one character. Ask for the kinds you want:
| Kind | When | Return |
|---|---|---|
open |
Before an open | A path to open instead, or false to refuse it |
opened |
After it opened | |
failed |
An open that failed, with its status |
|
read |
After a read, with its size |
|
write |
Before a write | false to refuse it |
closed |
The last handle to a file closed |
// Use our own textures, wherever the game looks for themconst id = vfs.watch({ pattern: "C:/Games/Example/textures/*.dds", open: true }, (event) => { if (event.kind === "open") return event.path.replace("/textures/", "/mods/textures/");});
// Keep the game from writing its logvfs.watch({ pattern: "*/game.log", write: true }, () => false);
vfs.unwatch(id);The event has path, where the file really is, and requested, what the game asked for. They differ once something redirects it. file is the same number for every handle to one open file, so you can follow it from opened to closed. read and write say how it was opened. Pass data: true to get the bytes of reads and writes as data.
The game’s thread waits for your callback, so keep it quick. It runs under your script’s lock, like a hook. Existence checks like GetFileAttributes only come as opens with queries: true, and they have query set. While Windows loads a DLL it holds a lock, so those opens are skipped unless you pass loader: true. If you do, don’t wait on anything in the callback.
See it
Section titled “See it”Diagnostics > IO in the workbench shows what the game opens, reads, writes and closes, every file it has open right now, and your virtual files.
File watching can be turned off with file_io in the settings, for a game that doesn’t like it. Then vfs calls throw Unavailable.
Made with ♥ by Asgard
