Filesystem & VFS

Assets are referred to by virtual paths, so a game's data does not depend on where it is installed.

The concept

Hard-coding C:\Users\me\game\hero.png breaks the moment the game moves. A virtual file system maps short, stable names (textures/hero.png) onto real directories chosen at startup. The same game data then works from a dev checkout, an installed build or an archive, and tools can remap folders without touching scenes.

Mounts

The usual model is the mount: a virtual root such as textures is bound to a real folder. Looking up a virtual path replaces the root with the real folder, so only the mount table needs to know where data really lives. With several mounts you can layer a mod folder over the base game, as the first match wins.

Why not relative paths?

Relative paths depend on the working directory, which changes with how the game is launched (double click, terminal, IDE). Absolute paths bake in a developer's machine. Virtual paths avoid both and also use forward slashes everywhere, so scene files behave the same on Windows, Linux and macOS.

Watching files

Tools want to react when a file changes on disk, for example reloading a texture after an artist saves it. Operating systems offer native notifications for this, which are cheaper and faster than re-scanning folders. The watcher runs on its own thread so waiting for changes never blocks the game.

How ASGE does it

VirtualFileSystem

asge::filesystem::VirtualFileSystem keeps a list of mounts, each binding a virtual root to a real directory:

Mount(root, realPath) and Unmount() manage bindings; a root can be mounted more than once.
Resolve(virtualPath) returns the real Path, trying each mount whose root prefixes the path in registration order.
Exists(), IsMounted(), ListMounts() and SplitRoot() inspect state.
ToVirtualPath(realPath) goes the other way, which the editor uses when you pick a file on disk.

Paths are normalized before use, and fallible calls return Result/BoolResult instead of throwing.

vfs.cpp

asge::filesystem::VirtualFileSystem vfs;
vfs.Mount( "textures", "assets/textures" );          // BoolResult

auto real = vfs.Resolve( "textures/hero.png" );      // Result<Path>: assets/textures/hero.png
bool ok   = vfs.Exists( "textures/hero.png" );

File IO and watching

The filesystem namespace also provides ReadText, WriteText, ReadBinary and Copy, plus file metadata. FileWatcher runs on its own concurrent::Thread and reports FileEvents (created, deleted, modified, moved) to an IFileEventHandler, with a native implementation per platform.

Start

Theory

Reference

Examples