Skip to content

Namespace Apogee.Content.FileSystem

Classes

DirectorySource

A folder of the real file system. Paths are joined to the folder after they were checked to hold only plain names, and the result is checked to be inside it. A link inside the folder that points out of it is followed, as the operating system does: do not mount a folder whose contents you do not trust to be links-free.

A write is durable and whole: the bytes go to a hidden file of a unique name beside the target, are flushed to the disk, and the file is then renamed over the target, so a crash or a full disk leaves the old file, and not an empty one. A file that is a symbolic link is written through: the new bytes go to the file the link leads to, and the link stays a link. A file that has several hard links is replaced by a new file: the other names keep the old bytes (the operating system does not say which names a file has, so this cannot be seen from here).

Mount

One source mounted at a prefix of the virtual file system.

VfsException

A path that is not valid, or that leaves its mount.

VfsPath

Paths of the virtual file system: scheme://a/b/c.txt, always with /, case-sensitive. is strict, for the paths a program or a script names: no . or .. segments, no empty ones, nothing a Windows file system would treat differently (a trailing dot or space, device names, :, wildcards), so that a path means the same on every platform and cannot leave its mount. and are lenient, for resolving a path a file refers to (a texture next to a model, a require("../x")): .. climbs but stops at the root of the scheme. They work on plain paths too.

VfsSubtreeSource

A folder of the virtual file system as a source of its own: res://packages/cool seen as the root of a package, so that it can be mounted at mod://cool beside the packages that are zips. Read-only, whatever the folder is made of (a real folder, a pack, a zip).

VfsWatcher

Notices when files of a change, for hot reload. It watches every folder that backs a mount (zips and packs do not change under a running game) and gives the changes as virtual paths: the one the file has through the mount it was found in, and every other path that is a view of it (a package at res://packages/core is also mod://core). Saving a file usually makes several events (a temporary file, a rename, a write): a path is reported once, after it has been quiet for debounce. Files and folders whose name starts with a dot, and editors' temporary files, are ignored. Create it after the mounts; call from the thread that owns what is reloaded.

VirtualFileSystem

The engine's view of its files: res:// (the game's content, from folders and packs), user:// (what the player's machine keeps: saves, settings, mods) and mod://<id>/ (a mod's own files), each made of mounted s. A path is looked up in every source mounted at a prefix of it, the one mounted last first, so that a patch pack or a mod's folder overrides what is under it; a source can also a file. Listings are the union of the sources, sorted ordinally. Only a writable source takes writes, and a path that is not valid (see ) is refused, so a script cannot name anything outside its mounts. Paths are case-sensitive, even on a file system that is not: write them as they are on disk.

ZipSource

A zip file, for mods that ship as one. The directory is read when it is opened; entries whose names are not valid paths (.., absolute, a backslash that does not make a valid path) are skipped with a warning, so that no entry can name a place outside the zip. Files are inflated on read, whole.

Interfaces

IFileSource

A folder, a zip file or a pack that a mounts. Paths are relative to the source: canonical, with /, no leading slash, and the empty string for the source's root (see ). Reads are safe from several threads.

Enums

FileKind

What a source knows about a path.