I gave the Pegasus repo another lookover this morning and I have to say, I'm not liking what I see.  It's woefully incomplete, but that doesn't bother me--there's enough there that I could take some liberties to fill in the blanks.  What does bother me is how much of it completely breaks compatibility with Sphere 1.x.  I get that it's supposed to be this revolutionary re-imagining of the Sphere API, but... I don't know, so much of it strikes me as just change for the sake of it.

Great example: Pegasus defines ~/path to be relative to the user profile directory, so that it's guaranteed to be writable.  This is a great idea, except we've completely changed the meaning of the escape.  In Sphere, this same escape means "relative to game.sgm".  There's no easy way to reconcile the discrepancy in the same engine--you either have one or the other.

Long story short: I advocate we start over with Sphere 2.0 and set it up in such a way that the legacy API and the new one are not mutually exclusive.

I'm fine with the APIs not being directly compatible. But I do agree, the Pegasus spec as it stands is not very good. It is extremely complex, and makes doing just about anything very verbose and difficult.

I had expected that it would be revised if/when TurboSphere or Minisphere became more widely used (more than one digit users). I would say that the APIs that Minisphere and TurboSphere expose are a better match for being Sphere 2.0.

I had intended that the APIs would not be totally compatible, but that it would be possible to support both. That was why I came up with the extension system, to allow games to query just what kind of engine they are in. But I agree, they should not be mutually exclusive.

As always, the best way to iron things out was just to jump in.  Rather than agonizing over what's wrong with the current state of Pegasus, I instead began implementing something resembling it in minisphere.  It turns out that the main problem with Pegasus as it exists in the repo is that it tries to be both Sphere 1.x and something-entirely-new at the same time, and doesn't really accomplish either goal very well.  It also makes writing a shim very difficult since it redefines existing APIs to use the new semantics.

For minisphere, I decided the best way forward was to blow away the 1.x API completely and start from scratch pretending it doesn't exist.  If we're already breaking compatibility in such a huge way, there's no reason to keep the old idioms around, and it also makes it easier to shim 1.x compatibility back in when we don't have a mixture of old and new functions in the core API.

Lord, I agree. Make something new. But I do think that Pegasus needs to end up with at least the features of Sphere 1.x.

I also DO think we should use CommonJS modules, and also that we should not have blocking calls but use Promises instead (not the callback stuff, only for callbacks that are actually callbacks: one that will be called 1+ times.)

I'll take a look at it.

Lord, I agree. Make something new. But I do think that Pegasus needs to end up with at least the features of Sphere 1.x.

The features, yes, but the API needs to be redesigned from scratch.  The problem with the spec as it exists right now is that it tries to duplicate a lot of the semantics of Sphere 1.x in an all-new system and things just don't mesh very well.  See the audio module I submitted as a pull request for an example of how to do it right.

Alright, I have taken a look at it and added some comments.