Difference between revisions of "SphereFS"

From Spherical
Jump to: navigation, search
(Add WIP SphereFS page)
 
(Added prefixes)
Line 11: Line 11:
 
== Prefixes ==
 
== Prefixes ==
  
TODO: write this section
+
{| class="wikitable" style="max-width: 700px;"
 +
! 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.
 +
|-
 +
| $/
 +
| 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.
 +
|}
  
 
== Path Resolution ==
 
== Path Resolution ==

Revision as of 20:12, 29 October 2017

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.
$/ 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.

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.

See Also

  • THE PIG: It eats you in 2 seconds
  • THE COW: It eats a bunch of cats
  • THE APE: It's the size of the universe. Bye bye cow and pig!