Skip to main content ↑ ↓
Topic: Sphere v2 API discussion (Read 891105 times) previous topic - next topic
0 Members and 9 Guests are viewing this topic.

Re: Sphere v2 API discussion

Reply #30 –
Also, and this is kind of a bikeshed issue, but I wonder if it would make more sense to have:

Code: (javascript) [Select]

job = Dispatch.onUpdate(...);
Dispatch.cancel(job);


The reason is that Job object is not really meant to be a real object but more of just an unforgeable "token" so that outside code can't accidentally cancel your job.  Using the token metaphor it's a bit strange to have the token do anything by itself - you need to "insert" it into the Dispatch machine for it to work.

setTimeout() also works like this, so there's that too. ;)

Re: Sphere v2 API discussion

Reply #31 –
Final API design for the Dispatch API in minisphere 4.3 will probably look like this:

Code: (javascript) [Select]

// Call from event loop ASAP:
jobToken = Dispatch.now(func);

// Call from event loop in X seconds:
jobToken = Dispatch.later(2.0, function() { pig.eat(you); });

// Call at the start of every frame:
jobToken = Dispatch.onUpdate(function() { pig.hunger++; });

// Call at the end of every frame (just before flip).  These can have priority and
// higher priority jobs are rendered later in a frame according to the painter's
// algorithm:
jobToken = Dispatch.onRender(function() { pig.draw(); });
jobToken = Dispatch.onRender(function() { pig.draw(); }, 8);  // priority 8.0

// Cancel an active job:
Dispatch.cancel(jobToken);


Thoughts?

Re: Sphere v2 API discussion

Reply #32 –
Looks good to me, though it seems sensible to me that Dispatch.later also has a version that works with frames rather than seconds. Also, does onUpdate also have priorities?

Re: Sphere v2 API discussion

Reply #33 –
Good point, a lot of games need frame-perfect timing; since the engine manages the frame rate for you (tip: screen.frameRate) it makes sense to be able to do that.  I'll add it, thanks for the idea. :)

I could add priorities for onUpdate easily (the job queue is shared for all types), but I didn't originally expose it to the API because it seemed like a well-designed game wouldn't have any dependencies between different update scripts?  It seemed to matter more for rendering because render order affects the final scene.  Maybe there's a use case I'm not thinking of though.

Re: Sphere v2 API discussion

Reply #34 –
Ohh, I see. It just seemed sensible to me that updates can also be executed in some specific order, just like renderscripts. Like updating the player position before or after checking enemy interactions, for example. But i see why you would give renderscripts specifically an order - it determines what overlaps what after all.
 

Re: Sphere v2 API discussion

Reply #35 –
Quote from: DaVince – on

Ohh, I see. It just seemed sensible to me that updates can also be executed in some specific order, just like renderscripts. Like updating the player position before or after checking enemy interactions, for example. But i see why you would give renderscripts specifically an order - it determines what overlaps what after all.


Good point, there may be dependencies after all.  I'll add update priorities then, that'll be a simple fix.

Re: Sphere v2 API discussion

Reply #36 –
Alright, I added priority support for onUpdate calls in the latest Git build.

Re: Sphere v2 API discussion

Reply #37 –
I decided to make unthrottled framerate be given as Infinity in Sphere v2 rather than 0:

Code: (javascript) [Select]

screen.frameRate = 60;  // 60 fps
screen.frameRate = Infinity;  // unthrottled
screen.frameRate = 0;  // RangeError: invalid frame rate


Having implemented this and then looked back at the Sphere v1 API setup, I can see now that it was designed without fully understanding all the intricacies of JavaScript.  The semantics are those of a typical C API, which also explains all the global functions and lack of any constructors.  Luckily that also makes it very easy to support the two APIs side-by-side. ;)

In any case it feels good to finally be making a clean break from the old designs.

Re: Sphere v2 API discussion

Reply #38 –
system.now() in the latest development build now returns the number of frames processed since engine start, rather than wall-clock time.  If needed, wall-clock time can already be retrieved in JavaScript via Date.now(), so it seems much more useful for the Sphere API to work in frames, as that is usually the dominant timing method for realtime games.  That ensures timing remains precise even if you hit lag/slowdown.

Specifically, system.now() counts updates, not flips.  This way skipped frames don't throw off your timing.

Re: Sphere v2 API discussion

Reply #39 –
Following up on that infinite framerate thing, I just realized that it's very common to do seconds * fps to figure out how many frames something will take.  This raises the issue of infinity being used to turn off the frame limiter: Because infinity * anything = infinity, such an operation would never complete.  Using 0 to disable the frame limiter like Sphere 1.x might actually be better, if somewhat less intuitive.

Re: Sphere v2 API discussion

Reply #40 –
I decided to rename FS.mkdir() etc. to make them more discoverable.  I originally used the POSIX names to match Node, but one of Sphere's strengths is having very descriptive API names even at a glance, so I made the following renames:


  • FS.mkdir() -> FS.createDirectory()

  • FS.unlink() -> FS.deleteFile()

  • FS.rmdir() -> FS.removeDirectory()

  • FS.open() -> FS.openFile()

Re: Sphere v2 API discussion

Reply #41 –
I'm looking at the sphere2-api.txt doc right now, and was thinking: how about a screen.toggleFullScreen() method to, well, toggle the fullscreen mode? Perhaps it could even take a boolean argument to force full screen on or off.

Also, did the Sphere 2 project files have any setting to define a game as being full screen or windowed by default? I kinda forgot. Also, are these settings writable by the game itself in an intuitive manner?

Re: Sphere v2 API discussion

Reply #42 –
None of that is supported yet, but all good ideas :).  This is why system.apiLevel is still 0, I'm still open to making modifications!

Full screen toggle could just be a property, no function needed:
Code: (javascript) [Select]

screen.fullScreen = !screen.fullScreen;


That'd be easy to implement too.

Re: Sphere v2 API discussion

Reply #43 –
Alright, I added a screen.fullScreen property.  You'll be able to set it to true or false to control the engine's fullscreen mode at runtime.

I reorganized the file API a bit: Instead of FS.openFile() (which is awkward to explain to newbies: what does it mean to "open" a file?  It's not a folder.), you now do instead:

Code: (javascript) [Select]

import { FileReader, FileWriter } from 'struct';

function saveGame(world)
{
    var stream = new FileStream("~/saveFile.dat", FileMode.Write);
    var fw = new FileWriter(stream);
    fw.writeString8(world.playerName);
    // etc. etc.
}


There are no more obscure C fopen() mode strings, it uses easy-to-understand FileMode constants now.  And while it seems superficial, the rename from FS.openFile() to new FileStream() is actually pretty significant: It takes the concept of "opening a file" completely out of the equation.  That makes it much simpler to explain to new users: you create a new FileStream which provides streaming access to the data stored in the file.

This kind of thing is a delicate balance to strike: You want the code calling these API functions to be self-documenting (so that less experienced users can read it and see what's going on, and thus learn from it), but at the same time you don't want to dumb it down and take power away from more advanced users.  That sometimes requires a lot of thought, but in the end I think the work has paid off.  For many, Sphere 1.x served as a "gateway drug" into programming.  I think I've been able to preserve that gateway potential in Sphere v2, but only time will tell.

Re: Sphere v2 API discussion

Reply #44 –
5.0 will change the save data handling so that games no longer have to share the same save file folder.  How that works is you set a "save ID" in the JSON manifest and miniSphere uses that as the name of the folder.  If you have want to have sequels be able to share save data, you can just give them the same save ID.

I'm thinking there should be a standardized format for save IDs to avoid clashes, something like this maybe (inspired by Android app IDs):
Code: [Select]
com.authorname.gamename