Nice work with all of this so far!
By the way, I've found it difficult to get started with minisphere while the API keeps changing. Something that worked fine in the previous version is now broken. I guess that's just a risk that comes with chasing a moving target, though.
Yeah, Sphere v2 is still brand new and comprises a HUGE API surface (built-in engine functions + miniRT, it's a much more comprehensive API than Sphere 1.5's) so I used the 4.x cycle as kind of an experimental testing ground to get all the kinks ironed out (I thought I said something to that effect when I released 4.0.0, maybe not though...). The goal for minisphere 5.0 is to stabilize the API so that it won't change anymore, at least not in major, fundamental ways like it has throughout the 4.x cycle. But before that could happen I had to make sure it was presentable - it's important that our frontend be as easy to understand for someone reading the code as possible. That said, the plan is to release 5.0.0 on the second anniversary of minisphere 1.0 (March 28), so 4.3 will remain current for quite a while. And if it makes you feel any better: If you take the time to learn the API now, the rug won't be pulled out from under you again, I don't intend to change much in minisphere 5.0.
I'm also not really sure how to start creating your project as if it's a Node.js module - I have really no experience with this. There is, in all honestly, a LOT of new stuff I have to get used to by now, including just getting a picture shown on screen, which I needed to use the prim module for because I just couldn't figure it out otherwise. (I know I'm not a very good coder but still. )
Actually don't feel bad about that - that's exactly what the
prim module is there for.
miniRT is a first-class part of the Sphere v2 API, so it's not going anywhere. Galileo is there if you need it for advanced stuff - but if you're just getting started or making simple games,
prim is more than sufficient. The built-in APIs in Sphere v2 are low-level because they are meant to be a foundation, so that you can build any kind of framework on top of them you need. Games generally shouldn't use them directly; miniRT is there for small-medium sized projects, but if a large project needs something more robust it can build its own custom library on top of the low-level built-in functions.
Also, I feel it's relevant to mention here, the entire Sphere 1.5 API is still there if you need to fall back on it - and it's fully interchangeable with the Sphere v2 stuff. That was a very important consideration over the course of Sphere v2 development - the two APIs had to be compatible with each other to make migration painless.
The same goes for the Linq-style stuff - it looks really great but usually I don't *quite* understand what half of the selector code does in the examples I see fly by. Comments next to each line, please? Although maybe I just need to read the documentation for that.
Yeah, I'm not sure any example can really convey its power. The basic idea is that
from(array) converts the array to a query, then each query operator you tack onto the end adds a new link to the "chain". When the query runs, each item goes through the links in the chain, being transformed or filtered along the way (this is why a lot of the methods take functions as parameters, the examples would be much easier to read if Duktape supported fat arrow functions, but it doesn't). Whatever makes it to the end without being filtered out is what you get as output. Here's a query that gives you an array of all even numbers between 1 and 10, as strings:
var evenStrings = from([ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ])
.where(function(v) { return v % 2 == 0; }) // "where value is even"
.select(function(v) { return v.toString(); }) // "select value, converted to string"
The best advice I have is to read the documentation, since like I said the current version will be current for a while and the API is not likely to change much for 5.0 anyway. These are permalinked to the 4.3.8 tag so the links shouldn't break in the future:
https://github.com/fatcerberus/minisphere/blob/v4.3.8/docs/sphere2-api.txthttps://github.com/fatcerberus/minisphere/blob/v4.3.8/docs/miniRT-api.txtDespite the lack of examples, I did make sure the API documentation always stayed up to date, and it goes into detail where necessary (unlike the Sphere 1.x documentation which gets pretty vague at times...).
Is there a possibility you could focus a little more on creating some simple snippets or tiny example projects on how to use certain parts of the API? That would be good wiki/tutorial material, too.
But yeah, I'll try to do this for minisphere 5.0.