This is a rough draft of the SphereFS standard I'm working on.  It is designed to be backwards compatible with the Sphere 1.x sandbox but with much more flexibility while abstracting away whether the game is running locally or from a package, whatever.

Sphere 2.0: SphereFS
optional extensions:

• sphere_fs_absolute_path


• sphere_fs_system_alias

SphereFS is a standard for sandboxing the file system exposed to a Sphere game, part of the Sphere 2.0 initiative ("Pegasus").

• The standard path separator is the forward slash (/).

• Unprefixed paths are relative and cannot subvert the sandbox.  Attempts to move upwards (via "../") past the directory containing game.sgm will fail and throw a sandbox violation error.

• Several built-in aliases are available for paths which may vary depending on the platform, engine installation location, etc.  Available aliases:

@/... (or bare relative path)
Specifies a path relative to the location of game.sgm on the running game's file system (either SPK or physical).  Not writable.

#/..
Specifies a path relative to the engine's System Asset Collection (SAC). Not writable.  The engine should declare the sphere_fs_system_alias extension if it supports this.

~/...
Specifies a path relative to the current user's save data directory.  This is the recommended location for storing game save data and is guaranteed to be writable (barring OS misconfiguration).  ~/ refers to the same location for all games, allowing save data to be shared between sequels, for example.

<Absolute Path>
A SphereFS implemention may allow absolute paths only if it declares the extension sphere_fs_absolute_path.

Note that the semantics of ~/ will probably need to be different than ~sgm/ to maintain full compatibility, as existing games tend to assume the former is writable.  For example, it might be mapped to ~usr/ if the game is running from a non-writable medium like a package and someone opens a RawFile for write.

It's prepended with ~ to ensure it stays backwards compatible, I guess? It feels odd, but it's really not much different from % or $ placeholders. Maybe it's because ~ already conventionally means "home directory" on Linux.

Yeah, it's for backwards compatibility.  ~ means "location of game.sgm" in Sphere, so for consistency I followed the notation for the other escapes too.

Where does "/" go to in 1.5?

Nowhere.  It's a sandbox violation: "Invalid filename".

Then I'm curious why we need to specially qualify absolute pathnames with "~abs/". They would be invalid in 1.5 since the Unix root is invalid and Windows/DOS/Symbian filenames cannot have colons in them, and so no 1.5 game that works will use them.

A single / has the opportunity to be ambiguous, if you don't canonize properly. But since that's handled properly in 1.5, there will never be ambiguity between an absolute and a relative path.

The syntax is awkward on Windows though: /C:\path\file

But the abs notation has the same issue, of course.  Either way we have to maintain ~/ with its current semantics for backward compatibility, so for consistency's sake I kept it in the names of the new escapes as well.

Unless we make this a full emulated file system and abstract the underlying platform away entirely.  Then you'd have /usr, /sgm, etc. and something like /local where the entire physical FS is mounted.

I'm saying we just allow absolute paths the way you suggest they be handled, but with no special notation in paths just for them.

You'd just put C:\path\to\file, or /path/to/file depending on the environment. No need to specially qualify it, since it's not ambiguous, and the developer always knows how to specify it (unlike the other aliases, which could actually be anywhere in the fs tree).

That would also unify the notation, since then you allow valid pathnames (relative or absolute), but with several prefixes predefined.

I do think that this entire idea is much cleaner and generally a better idea than an entire emulated FS.

Hm, you're right.

I do still want to confine ".." to the sandbox though, even if the engine implements absolute paths.  Reason being, the game developer doesn't know where there game is going to be placed, so moving upwards relative to game.sgm is dangerous.  Absolute paths are generally provided by the user or temporary used by the developer during debugging, so this isn't an issue there.

Disallowing using a ".." out of an alias makes sense. I wouldn't say it's dangerous, but it is kind of a nonsense thing to do. From the perspective of the developer, that could lead anywhere. On a Unix system, it might not actually lead anywhere at all! Better to make it impossible than cause intermittent bugs.

A note about the sandboxing, and why it exists in Sphere the first place: I think it actually was a security measure. Sphere was designed in the '90s, to work with Windows 9x, Windows 2k, RHEL, and Debian. While the Linux distros had similar security to what we enjoy now (maybe even better, since they were more aligned with how Unix should work and not concerned with making raw device use easier for the desktop user), and Windows 2k had very almost all the security systems that Windows still has today (being Windows NT 6), in Windows 95 and 98 (the most common end-user OS at the time) not sandboxing the FS actually was kind of dangerous. You suddenly could write a virus in JS using Sphere under those circumstances.

I had experiences with the joy of the extremely fagile DOS-based fs in Windows 9x in my Visual Basic days. It's silly to think about it now, but after that occurred to me, it makes a lot of sense.

I kinda like what N E O came up with in te other thread - prepending the path with something like a sphere:// protocol. Thoughts?

I got the feeling that was more about a way to register the sphere protocol with the engine than anything internal - for example you could click a sphere:// link on a webpage and it would automatically download the game/run it off the internet.  Which would be awesome.

Using a protocol to specify filenames internally would be weird I think.  The ~ aliases feel more natural (read: Sphere-like), and I'm trying to avoid going down the Pegasus "new for the sake of it" route if at all possible.

I got the feeling that was more about a way to register the sphere protocol with the engine than anything internal - for example you could click a sphere:// link on a webpage and it would automatically download the game/run it off the internet.  Which would be awesome.

Eventually this, yes. Also, a sphere:// link of some non-game file would open said file in whatever program is registered within Sphere to handle it, some thoughts follow:

• sphere://path/to/some/image.png - Call `sphere -open path/to/some/image.png` or something
  
• Sphere config has an "Openers" section which, when `sphere -open <file>` is called, redirects to a chosen program (eg. "image=/path/to/image/editor", "spriteset=/path/to/spriteset/editor", etc)
  
• Sphere Studio probably does all this, but isn't included with vanilla Sphere distributions just yet and isn't multi-platform yet
  
• Final games are obviously meant to be distributed without an editor, but this method is clearly more useful with an editor
  
• Method to register the sphere:// protocol differs per-platform
  

So...yea.

I'm working on standardizing this for minisphere 2.0.  So far, to be SphereFS compliant, an API must:

• Treat an unqualified, unprefixed path as relative to either game.sgm or ~usr/, regardless of the resource type. Enforcing this ensures maximum flexibility in laying out a game's directory structure.


• Accept all three SphereFS prefixes: ~sgm/, ~usr/, ~sys/


• Must not allow a relative path to navigate outside of the game directory. Absolute paths may be allowed (support not required by spec), but, e.g. "../../../filename" is a sandbox violation.

I'll flesh these requirements out more as 2.0 development goes on.

Oh, and no worries: Classic functions such as LoadImage, LoadSound, etc. will retain the legacy behavior.