SphereFS

SphereFS is a standardized system used by Sphere for unambiguously specifying pathnames of files and directories within the sandboxed JavaScript environment.

A canonical SphereFS pathname consists of a prefix, for example @/ or ~/, followed by one or more directory components separated by slashes, and finally an optional filename. Each prefix is either a unique root in itself or else an alias for a directory within one of those roots. Prefixes other than ~/ are write-protected, and it is not possible to reference files outside the sandbox. OS paths such as C:\file.txt or /usr/bin/eatypig are not legal within the SphereFS sandbox, nor are relative paths that extend uplevel from a prefix, e.g. @/../../maggie.fat. Passing such a path to a Sphere API function expecting a file or directory name will cause an exception.

Introduction

TODO: write this section

Prefixes

Prefix	Location	Details
@/	Project root	The root of the game's sandboxed file system. Usually redundant, but can be useful to qualify filenames in situations where a bare SphereFS filename will be ambiguous, for example in an `import` declaration. This directory is read-only; trying to save or modify anything here will cause a TypeError to be thrown.
$/	Startup script directory	The directory containing the startup script. This is mostly provided as a convenience for specifying module names in `import` declarations.
#/	System directory	The engine's system directory. This contains assets included with the engine. As with `@/`, this is read-only to Sphere games.
~/	Save directory	The current user's save data directory (note: requires a save ID; refer to the section on `game.json` above). This is generally used to store save data and such where the user can easily access it.
./	Current script's directory	Any script that's not the main startup script could technically be anywhere in your project. For example, in a subdirectory. This prefix will refer to that specific subdirectory. Useful if you're including scripts and libraries from other people or if you want to organize your scripts.

Path Resolution

TODO: write this section too

Save ID

In order for a game to use the ~/ prefix, it must include a save ID in its JSON manifest. The save ID should be unique for each game or series and typically takes the form authorName.gameName, where both parts are written in camelCase. For example, Spectacles: Bruce's Story's save ID is fatCerberus.spectacles.