Difference between revisions of "API:Functions"

From Spherical
Jump to: navigation, search
(CommonJS API)
m (Sphere Game Platform: Add APIs from mS 5 final)
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This is a function reference for the Sphere v2 API. It is currently based on the official [https://github.com/fatcerberus/minisphere/blob/master/docs/sphere2-api.txt miniSphere API reference].
+
{{DISPLAYTITLE:Sphere v2 API}}
  
The plan, in the future, is to turn this page into a simple list enumerating all Sphere functions, objects and methods, and leave the explanatory details to the individual articles.
+
The '''Sphere API''' is the collective name for the set of bindings (functions, objects, and methods) available for use by all Sphere games.  The API provides access to a host of convenient features, allowing you to get up and running quickly.
  
 +
<noinclude>
 +
{{section|sph-section-green|Making new function/object pages|Simple steps:
 +
#Before getting started, please check the [[Article standards and practices]].
 +
#Click a red link.
 +
#Place the following code in the empty edit box:
 +
##For a new function: <code><nowiki>{{subst:functemp|preamble=REPLACEME|function=REPLACEME|object=REPLACEME|returns=REPLACEME|params=REPLACEME}}</nowiki></code>
 +
##For a new object: <code><nowiki>{{subst:objecttemp|preamble=REPLACEME|function=REPLACEME|object=REPLACEME|returns=REPLACEME|params=REPLACEME}}</nowiki></code>
 +
#Check the minor edit flag and save.
 +
#Click 'edit' at the top of the page to add content.
 +
#Try to be [http://en.wiktionary.org/wiki/objective objective] when writing, and save when you're done.
 +
#Remove description from this page, add page link to list at the top of the matching section.
 +
}}
 +
</noinclude>
 +
__TOC__
  
== Sphere v2 Core API Reference ==
+
== Core API ==
  
As the successor to the original Sphere engine, miniSphere implements nearly the entire Sphere v1 API. However, the v1 API is quite dated and, as of miniSphere 4.0, has been deprecated in its entirety. It is not documented here at all; while games using the legacy functions will continue to run, new code should be written against the modern Sphere v2 API, documented here.
+
The '''Core API''' provides low-level access to the engine's features and includes all bindings provided directly by the engine. These bindings are exposed to the global scope and can be used without importing any extra modules.
  
To ease migration of existing Sphere v1 codebases to Sphere v2, legacy and modern API calls may be freely intermingled within the same codebase, and this is true even when the engine is running in compatibility mode.
+
=== Sphere Game Platform ===
  
== JSON Game Manifest (<code>game.json</code>) ==
+
<tt>
 +
* [[API:Sphere.APILevel|Sphere.APILevel]]
 +
* [[API:Sphere.Compiler|Sphere.Compiler]]
 +
* [[API:Sphere.Engine|Sphere.Engine]]
 +
* [[API:Sphere.Game|Sphere.Game]]
 +
* [[API:Sphere.Version|Sphere.Version]]
 +
* [[API:Sphere.frameRate|Sphere.frameRate]]
 +
* [[API:Sphere.frameSkip|Sphere.frameSkip]]
 +
* [[API:Sphere.fullScreen|Sphere.fullScreen]]
 +
* [[API:Sphere.abort|Sphere.abort()]]
 +
* [[API:Sphere.now|Sphere.now()]]
 +
* [[API:Sphere.restart|Sphere.restart()]]
 +
* [[API:Sphere.setResolution|Sphere.setResolution()]]
 +
* [[API:Sphere.shutDown|Sphere.shutDown()]]
 +
* [[API:Sphere.sleep|Sphere.sleep()]]
 +
</tt>
  
To take full advantage of the Sphere v2 platform, a game package must include a file named <code>game.json</code> in its root directory. This file holds metadata such as the title and author, as well as some control information which affects how the engine runs the game.
+
=== Debugging ===
  
Here's a sample manifest:
+
<tt>
 +
* [[API:SSj.flipScreen|SSj.flipScreen()]]
 +
* [[API:SSj.log|SSj.log()]]
 +
* [[API:SSj.trace|SSj.trace()]]
 +
</tt>
  
<pre>{
+
=== Files and Directories ===
    &quot;version&quot;: 2,
 
    &quot;name&quot;: &quot;Spectacles: Bruce's Story&quot;,
 
    &quot;author&quot;: &quot;Fat Cerberus&quot;,
 
    &quot;summary&quot;: &quot;Follow Scott Starcross in his quest to stop the Primus.&quot;,
 
    &quot;resolution&quot;: &quot;320x240&quot;,
 
    &quot;main&quot;: &quot;main.js&quot;
 
}</pre>
 
JSON fields defined by the Sphere v2 specification are documented below. Because the manifest format is JSON, as many additional fields may be added as needed, and their values accessed from JavaScript through <code>Sphere.Game</code>.
 
  
&quot;version&quot; [default: 2]
+
<tt>
 +
* [[API:DirectoryStream|new DirectoryStream()]]
 +
** [[API:DirectoryStream::fileCount|DirectoryStream::fileCount]]
 +
** [[API:DirectoryStream::fileName|DirectoryStream::fileName]]
 +
** [[API:DirectoryStream::position|DirectoryStream::position]]
 +
** [[API:DirectoryStream::dispose|DirectoryStream::dispose()]]
 +
** [[API:DirectoryStream::next|DirectoryStream::next()]]
 +
** [[API:DirectoryStream::rewind|DirectoryStream::rewind()]]
 +
* [[API:FileStream|new FileStream()]]
 +
** [[API:FileStream::fileName|FileStream::fileName]]
 +
** [[API:FileStream::fileSize|FileStream::fileSize]]
 +
** [[API:FileStream::position|FileStream::position]]
 +
** [[API:FileStream::dispose|FileStream::dispose()]]
 +
** [[API:FileStream::read|FileStream::read()]]
 +
** [[API:FileStream::write|FileStream::write()]]
 +
* [[API:FS.createDirectory|FS.createDirectory()]]
 +
* [[API:FS.deleteFile|FS.deleteFile()]]
 +
* [[API:FS.directoryExists|FS.directoryExists()]]
 +
* [[API:FS.fileExists|FS.fileExists()]]
 +
* [[API:FS.fullPath|FS.fullPath()]]
 +
* [[API:FS.readFile|FS.readFile()]]
 +
* [[API:FS.relativePath|FS.relativePath()]]
 +
* [[API:FS.removeDirectory|FS.removeDirectory()]]
 +
* [[API:FS.rename|FS.rename()]]
 +
* [[API:FS.writeFile|FS.writeFile()]]
 +
</tt>
  
<pre>The Sphere standards version the game was developed against.  If this is 2,
+
=== Random Number Generation ===
the game runs in Sphere v2 mode.  In Sphere v2 mode, the main script is
 
loaded as a CommonJS module, which enables use of relative paths in
 
require() calls (see below), as well as ensuring variable and function
 
declarations remain local to the module.
 
  
If this is 1, the game runs in Sphere v1 compatibility mode. In this mode,
+
<tt>
the main module is executed as normal program code, and miniSphere calls
+
* [[API:RNG.fromSeed|RNG.fromSeed()]]
the global game() function--if one is provided--to begin game execution.
+
* [[API:RNG.fromState|RNG.fromState()]]
 +
* [[API:RNG|new RNG()]]
 +
** [[API:RNG::state|RNG::state]]
 +
** [[API:RNG::next|RNG::next()]]
 +
</tt>
  
Note: Regardless of the version specified, both Sphere v1 and v2 APIs will
+
== Sphere Runtime ==
      be available for use by game code.  The version in the manifest
 
      currently only affects the way the main module is run.  This may
 
      change in the future, however.</pre>
 
&quot;author&quot; [default: none]
 
  
<pre>The name of the person or company who developed the game.</pre>
+
The '''Sphere Runtime''' is a standard collection of JavaScript modules included with the engine.  Some modules can even be used in Cellscripts as well!  Unlike the Core API above which was organized by category, the following list is organized by module.  Most modules export only a single object or function; to import more than one at a time, you can use an ES2015 <tt>import</tt> statement and import objects from the <tt>sphere-runtime</tt> or <tt>cell-runtime</tt> module, as appropriate:
&quot;main&quot; [required]
 
  
<pre>The SphereFS path of the main JavaScript module (see below for more on
+
==== In a Sphere game ====
SphereFS).  This is the script miniSphere will run when the game is
 
started.  If no &quot;main&quot; field is present, the game will not start.</pre>
 
&quot;name&quot; [default: &quot;Untitled&quot;]
 
  
<pre>The title of the game. This field must be present; if it is not, the game
+
  import { from, Music, Thread } from 'sphere-runtime';
will not start.</pre>
 
&quot;resolution&quot; [required]
 
  
<pre>The default screen resolution of the game, expressed as a string of the
+
==== In a Cellscript ====
form &quot;WxH&quot;, specifying the number of pixels across and down.  For example,
 
720p resolution would be expressed as &quot;1280x720&quot;.
 
  
Note: The resolution can be changed at runtime by calling screen.resize().</pre>
+
import { assert, transpile } from 'cell-runtime';
&quot;summary&quot; [default: none]
 
  
<pre>A short summary of the game.  While there is no imposed length limit, it
+
=== <tt>from</tt> Module ===
is recommended to keep this short (150 characters or less) with no line
 
breaks.</pre>
 
== SphereFS File System ==
 
  
Sphere uses the SphereFS standard to interpret file paths. Under SphereFS, when a relative path is used in an API call, it will be resolved relative to the root of the game package (where <code>game.json</code> is located). To load files from a different location, you can use one of the SphereFS prefixes:
+
<tt>
 +
* [[API:from|from()]]
 +
** [[API:from::all|from::all()]]
 +
** [[API:from::allIn|from::allIn()]]
 +
** [[API:from::any|from::any()]]
 +
** [[API:from::anyIn|from::anyIn()]]
 +
** [[API:from::anyIs|from::anyIs()]]
 +
** [[API:from::ascending|from::ascending()]]
 +
** [[API:from::besides|from::besides()]]
 +
** [[API:from::count|from::count()]]
 +
** [[API:from::descending|from::descending()]]
 +
** [[API:from::each|from::each()]]
 +
** [[API:from::first|from::first()]]
 +
** [[API:from::from|from::from()]]
 +
** [[API:from::including|from::including()]]
 +
** [[API:from::last|from::last()]]
 +
** [[API:from::random|from::random()]]
 +
** [[API:from::reduce|from::reduce()]]
 +
** [[API:from::remove|from::remove()]]
 +
** [[API:from::sample|from::sample()]]
 +
** [[API:from::select|from::select()]]
 +
** [[API:from::shuffle|from::shuffle()]]
 +
** [[API:from::skip|from::skip()]]
 +
** [[API:from::take|from::take()]]
 +
** [[API:from::toArray|from::toArray()]]
 +
** [[API:from::update|from::update()]]
 +
** [[API:from::where|from::where()]]
 +
</tt>
  
<pre>@/: The root of the game's sandboxed file system.  Usually redundant, but
+
=== <tt>image</tt> Module ===
    can be useful to qualify filenames in situations where a bare SphereFS
 
    filename is ambiguous, for example in a require() call.  This directory
 
    is read-only; trying to save or modify anything here will throw a
 
    TypeError.
 
#/: The engine's system directory.  This contains assets included with the
 
    engine.  As with `@/`, this is read-only to Sphere games.
 
~/: The current user's save data directory.  This is generally used to
 
    store save data and such where the user can easily access it.  Note
 
    that all games share the same physical directory for this.  That allows
 
    games to easily share save data.</pre>
 
As an example, the following will create a FileStream which allows reading from the file <code>EatyPig.bin</code> residing in the user's save data directory.
 
  
<pre>var file = new FileStream('~/EatyPig.bin', FileOp.Read);</pre>
+
<tt>
Note: Absolute paths are forbidden, and any attempt to circumvent the sandbox to break into the underlying file system, e.g. &quot;@/../maggie.fat&quot;, will be met with a sandbox violation error.
+
* [[API:Image|new Image()]]
 +
** [[API:Image::blitTo|Image::blitTo()]]
 +
</tt>
  
== CommonJS API ==
+
=== <tt>logger</tt> Module ===
  
* [[API:Require|require]](module_id)
+
<tt>
 +
* [[API:Logger|new Logger()]]
 +
** [[API:Logger::beginGroup|Logger::beginGroup()]]
 +
** [[API:Logger::endGroup|Logger::endGroup()]]
 +
** [[API:Logger::write|Logger::write()]]
 +
</tt>
  
== Sphere v2 Platform API ==
+
=== <tt>music</tt> Module ===
  
The <code>Sphere</code> object is provided to allow games to communicate with the underlying Sphere v2 platform. The <code>Sphere</code> object's properties provide access to the engine's name and version number as well as the API level supported, and there are also several methods for managing engine execution.
+
<tt>
 +
* [[API:Music.adjusting|Music.adjusting]]
 +
* [[API:Music.adjustVolume|Music.adjustVolume()]]
 +
* [[API:Music.override|Music.override()]]
 +
* [[API:Music.play|Music.play()]]
 +
* [[API:Music.pop|Music.pop()]]
 +
* [[API:Music.push|Music.push()]]
 +
* [[API:Music.reset|Music.reset()]]
 +
* [[API:Music.play|Music.play()]]
 +
</tt>
  
Sphere.Platform [read-only]
+
=== <tt>prim</tt> Module ===
  
<pre>The name of the engine. In our case, that's &quot;miniSphere&quot;.</pre>
+
<tt>
Sphere.Version [read-only]
+
* [[API:Prim.blit|Prim.blit()]]
 +
* [[API:Prim.blitSection|Prim.blitSection()]]
 +
* [[API:Prim.drawCircle|Prim.drawCircle()]]
 +
* [[API:Prim.drawEllipse|Prim.drawEllipse()]]
 +
* [[API:Prim.drawLine|Prim.drawLine()]]
 +
* [[API:Prim.drawPoint|Prim.drawPoint()]]
 +
* [[API:Prim.drawRectangle|Prim.drawRectangle()]]
 +
* [[API:Prim.drawSolidCircle|Prim.drawSolidCircle()]]
 +
* [[API:Prim.drawSolidEllipse|Prim.drawSolidEllipse()]]
 +
* [[API:Prim.drawSolidRectangle|Prim.drawSolidRectangle()]]
 +
* [[API:Prim.fill|Prim.fill()]]
 +
</tt>
  
<pre>The version number of the engine; e.g. &quot;X.X.X&quot;.</pre>
+
=== <tt>random</tt> Module ===
Sphere.APIVersion [read-only] Sphere.APILevel [read-only]
 
  
<pre>The API version and level supported by the engine, respectively. The API
+
<tt>
version indicates which version of the Sphere API is supported (currently
+
* [[API:Random.chance|Random.chance()]]
v2), while the API level reflects the level of functionality within a
+
* [[API:Random.discrete|Random.discrete()]]
version. When new classes, methods, or properties are added to the Core
+
* [[API:Random.normal|Random.normal()]]
API without breaking compatibility, the API level is bumped.</pre>
+
* [[API:Random.sample|Random.sample()]]
Sphere.Game [read-only]
+
* [[API:Random.string|Random.string()]]
 +
* [[API:Random.uniform|Random.uniform()]]
 +
</tt>
  
<pre>An object whose properties describe the currently running game.  The object
+
=== <tt>thread</tt> Module ===
consists of everything in the JSON manifest plus any fields synthesized by
 
the engine.</pre>
 
Sphere.abort(message);
 
  
<pre>Unconditionally aborts execution and displays an error screen before
+
<tt>
closing the engine. `message` will be displayed on the error screen.
+
* [[API:Thread.join|Thread.join()]]
 +
* [[API:Thread.self|Thread.self()]]
 +
* [[API:Thread|new Thread()]]
 +
** [[API:Thread::running|Thread::running]]
 +
** [[API:Thread::start|Thread::start()]]
 +
** [[API:Thread::stop|Thread::stop()]]
 +
</tt>
  
Note: Sphere.abort() bypasses all exception handling mechanisms, including
+
= Miscellaneous =
      the debugger.  Be sure you know what you're doing before you call
 
      this function.</pre>
 
Sphere.exit();
 
  
<pre>Shuts down the engine. Be careful; this function will not return, so any
+
* [[SphereFS]] - How the file system prefixes work.
unsaved data will be lost.</pre>
 
Sphere.restart();
 
  
<pre>Restarts the currently running game from scratch, as though it were just
+
[[Category:Sphere 2 API]]
loaded.  Unsaved data will be lost.</pre>
 
Sphere.run();
 
 
 
<pre>Runs a single iteration of the Sphere v2 event loop.  This function always
 
returns true, allowing it to be used as part of a loop condition; for
 
example:
 
 
 
    while (!isDone &amp;&amp; Sphere.run()) {
 
        // do stuff here
 
    }
 
 
 
Note: Be careful.  This function runs all pending immediate jobs in the job
 
      queue.  That may lead to undesirable side effects if a Dispatch job
 
      modifies a global variable, for example.</pre>
 
Sphere.sleep(timeout);
 
 
 
<pre>Suspends JavaScript execution for the specified amount of time.  `timeout`
 
is in seconds, and may include fractions (e.g., 1.5).
 
 
 
Note: Any pending Dispatch.now() jobs will be run before sleeping.
 
      Depending on how long that takes, Sphere.sleep() may take longer than
 
      expected to return.</pre>
 
== Dispatch API ==
 
 
 
The Dispatch API is used to set up asynchronous function calls which are later performed from a designated part of the Sphere event loop. This is like an advanced version of Sphere v1 update and render scripts, but better integrated and available throughout the engine.
 
 
 
Dispatch.cancel(token);
 
 
 
<pre>Cancels the job associated with JobToken `token`.  Note that for one-time
 
jobs, cancellation has no effect if the job has already been processed.</pre>
 
Dispatch.cancelAll();
 
 
 
<pre>Cancels all one-time jobs currently in the job queue.  To help prevent
 
mishaps, recurring jobs are not affected by this call and must be cancelled
 
individually.</pre>
 
Dispatch.later(num_frames, fn);
 
 
 
<pre>Sets up a one-time job to call `fn` from the event loop after a specified
 
number of frames have passed.
 
 
 
Returns a JobToken for use with Dispatch.cancel().</pre>
 
Dispatch.now(fn);
 
 
 
<pre>Sets up a one-time job to call `fn` from the event loop on the next tick.
 
This is useful for performing operations that need to be done from the
 
event loop with minimal delay.
 
 
 
Returns a JobToken for use with Dispatch.cancel().
 
 
 
Note: Dispatch.now(fn) is *NOT* an alias for Dispatch.later(0, fn).  The
 
      latter runs at the beginning of the next frame; Dispatch.now() always
 
      runs on the very next tick even if no frame processing is done.</pre>
 
Dispatch.onRender(fn[, priority]); Dispatch.onUpdate(fn[, priority]);
 
 
 
<pre>Sets up a recurring job to call `fn` from a given part of the event loop.
 
For example, `onRender()` jobs are called before the backbuffer is flipped,
 
and `onUpdate()` jobs are called at the start of a frame.
 
 
 
`priority` affects the order of calls when there is more than one job.
 
Render jobs are performed in ascending priority order, while update jobs
 
are performed in descending priority order.  If no priority is given, the
 
default is 0.0.  Priority can be negative, and fractional priorities are
 
honored: 8.12, for example, is considered a higher priority than 8.0.
 
 
 
Returns a JobToken for use with Dispatch.cancel().
 
 
 
Note: Update jobs are processed at the beginning of a frame, while render
 
      jobs are processed at the end, just before the backbuffer is flipped.
 
      This ensures that:
 
 
 
      1) Frame loops always have access to up-to-date game state for the
 
        current frame.
 
      2) Objects drawn by an asynchronous render job can't be obscured by
 
        those rendered synchronously.</pre>
 
== Random Number Generator API ==
 
 
 
Games often have need of a good psuedorandom number generator, particularly in the case of RPGs. JavaScript provides a basic generator in the form of Math.random(). Sphere v2 takes it a step further with the powerful <code>RNG</code> object.
 
 
 
miniSphere uses the xoroshiro128+ algorithm to generate high-quality random numbers and allows manually seeding the generator, as well as saving and restoring the exact state of the generator at any time. RNG state is often saved along with other save data as a way to deter save scumming.
 
 
 
RNG.fromSeed(seed);
 
 
 
<pre>Constructs a new random number generator seeded using the specified value.
 
The specific sequence of numbers generated is entirely defined by the seed:
 
Two generators running in parallel, initialized with the same seed, will
 
always produce the same sequence.
 
 
 
`seed` is a number greater than zero.  If the seed is fractional, only the
 
integer part is used; everything after the decimal point is ignored.</pre>
 
RNG.fromState(state);
 
 
 
<pre>Constructs a new random number generator which starts in the specified
 
state.  See RNG#state for more information.</pre>
 
new RNG();
 
 
 
<pre>Constructs a new random number generator seeded from the current system
 
time.</pre>
 
RNG#state [read/write]
 
 
 
<pre>Gets or sets the current state of this generator.  State is encoded as
 
a 32-digit hexadecimal string which makes it easy to save and restore.
 
 
 
When setting `RNG#state`, the string given must be exactly 32 characters
 
and consist only of hexadecimal digits (0-9, A-F), otherwise a TypeError
 
will be thrown.</pre>
 
RNG#next();
 
 
 
<pre>Gets the next random number in the sequence.  Value returned is in the
 
range [0-1).</pre>
 
== Keyboard Routines ==
 
 
 
What would a game be without the ability for the player to control it? This set of functions allows your game to accept input via the keyboard, the most common input method for a PC game.
 
 
 
Key [enumeration]
 
 
 
<pre>Specifies a keyboard key.  Can be one of the following:
 
 
 
    Key.Alt
 
    Key.AltGr
 
    Key.Apostrophe
 
    Key.Backslash
 
    Key.Backspace
 
    Key.CapsLock
 
    Key.CloseBrace
 
    Key.Comma
 
    Key.Delete
 
    Key.Down
 
    Key.End
 
    Key.Enter
 
    Key.Equals
 
    Key.Escape
 
    Key.F1
 
    Key.F2
 
    Key.F3
 
    Key.F4
 
    Key.F5
 
    Key.F6
 
    Key.F7
 
    Key.F8
 
    Key.F9
 
    Key.F10
 
    Key.F11
 
    Key.F12
 
    Key.Home
 
    Key.Hyphen
 
    Key.Insert
 
    Key.LCtrl
 
    Key.LShift
 
    Key.Left
 
    Key.NumLock
 
    Key.OpenBrace
 
    Key.PageDown
 
    Key.PageUp
 
    Key.Period
 
    Key.RCtrl
 
    Key.RShift
 
    Key.Right
 
    Key.ScrollLock
 
    Key.Semicolon
 
    Key.Slash
 
    Key.Space
 
    Key.Tab
 
    Key.Tilde
 
    Key.Up
 
    Key.A
 
    Key.B
 
    Key.C
 
    Key.D
 
    Key.E
 
    Key.F
 
    Key.G
 
    Key.H
 
    Key.I
 
    Key.J
 
    Key.K
 
    Key.L
 
    Key.M
 
    Key.N
 
    Key.O
 
    Key.P
 
    Key.Q
 
    Key.R
 
    Key.S
 
    Key.T
 
    Key.U
 
    Key.V
 
    Key.W
 
    Key.X
 
    Key.Y
 
    Key.Z
 
    Key.D1
 
    Key.D2
 
    Key.D3
 
    Key.D4
 
    Key.D5
 
    Key.D6
 
    Key.D7
 
    Key.D8
 
    Key.D9
 
    Key.D0
 
    Key.NumPad1
 
    Key.NumPad2
 
    Key.NumPad3
 
    Key.NumPad4
 
    Key.NumPad5
 
    Key.NumPad6
 
    Key.NumPad7
 
    Key.NumPad8
 
    Key.NumPad9
 
    Key.NumPad0
 
    Key.NumPadEnter
 
    Key.Add
 
    Key.Decimal
 
    Key.Divide
 
    Key.Multiply
 
    Key.Subtract
 
 
 
Note: Keys D0-D9 refer to the row of numbers above the letter keys and
 
      below the function keys, while NumPad0-NumPad9 refer to the numbers
 
      on the numeric keypad.</pre>
 
Keyboard.Default [read-only]
 
 
 
<pre>Gets the default keyboard device.  miniSphere currently only supports a
 
single keyboard.</pre>
 
Keyboard#capsLock [read-only] Keyboard#numLock [read-only] Keyboard#scrollLock [read-only]
 
 
 
<pre>Gets the state of the corresponding lock key.  true if the lock is on,
 
false if not.</pre>
 
Keyboard#clearQueue();
 
 
 
<pre>Removes all keys from the keyboard queue.  If another key is not pressed
 
in the interim, the next getKey() will return null.</pre>
 
Keyboard#getChar(key, shifted);
 
 
 
<pre>Gets the character(s) that would be generated if a specified key is pressed
 
on this keyboard.  For example, Key.A becomes &quot;a&quot; (or &quot;A&quot; if shifted).
 
`shifted` specifies whether to assume the Shift key is pressed.
 
 
 
An empty string is returned if the specified key is not associated with a
 
character (a modifier key, for example).</pre>
 
Keyboard#getKey();
 
 
 
<pre>Gets the next key in the keyboard queue, or null if the queue is empty.</pre>
 
Keyboard#isPressed(key);
 
 
 
<pre>Returns true if the user is currently pressing the specified key.  `key`
 
should be a member of the Key enumeration.</pre>
 
== Joystick Routines ==
 
 
 
Joystick.Null [read-only]
 
 
 
<pre>Gets the null joystick.  When polled, a null joystick returns neutral
 
values for all inputs.  Joystick.Null can be used in place of a real
 
Joystick object to simplify input code.</pre>
 
Joystick.getDevices();
 
 
 
<pre>Gets an array of Joystick objects, one for each connected gamepad or
 
joystick.</pre>
 
Joystick#name [read-only]
 
 
 
<pre>Gets the name of the device, as reported by the Allegro backend.  Xbox
 
controllers are reported as &quot;XInput Joystick &lt;n&gt;&quot;</pre>
 
Joystick#numAxes [read-only]
 
 
 
<pre>Gets the number of analog axes supported by the device.</pre>
 
Joystick#numButtons [read-only]
 
 
 
<pre>Gets the number of buttons supported by the device.</pre>
 
Joystick#getPosition(axisID);
 
 
 
<pre>Polls the device and gets the current position along the specified analog
 
axis.  To get the number of axes supported by a device, use the `numAxes`
 
property.
 
 
 
Note: Axes are numbered sequentially, starting from 0.  Which physical axis
 
      is associated with any given axis ID will vary from device to device.
 
      For gamepads with analog sticks, though, it's generally a safe bet
 
      that the primary analog stick will be mapped to the first two axes.</pre>
 
Joystick#isPressed(buttonID);
 
 
 
<pre>Polls the device and returns true if the specified button is currently
 
depressed.  To get the number of buttons supported by a device, use the
 
`numButtons` property.
 
 
 
Note: Buttons are numbered sequentially, starting from 0.  As with axes,
 
      which physical button is associated with any given button ID will
 
      vary from device to device.</pre>
 
== Mouse Routines ==
 
 
 
These methods allow access to the mouse, another common input method for games. As with the Keyboard API, the Mouse API provides access to an event queue which accumulates mouse clicks and other events until the game is ready to process them.
 
 
 
MouseKey [enumeration]
 
 
 
<pre>Specifies a mouse click or other event (such as a wheel movement).  Can
 
be one of the following:
 
 
 
    MouseKey.Left
 
    MouseKey.Middle
 
    MouseKey.Right
 
    MouseKey.WheelUp
 
    MouseKey.WheelDown</pre>
 
Mouse.Default [read-only]
 
 
 
<pre>Gets the default mouse device.  miniSphere currently only supports a single
 
mouse.</pre>
 
Mouse#x [read-only] Mouse#y [read-only]
 
 
 
<pre>Gets the immediate X and Y position of the mouse cursor relative to the
 
game's rendering area.</pre>
 
Mouse#clearQueue();
 
 
 
<pre>Removes all events from this mouse's event queue.  If another event is not
 
received in the interim, the next getEvent() will return null.</pre>
 
Mouse#getEvent();
 
 
 
<pre>Gets the next event in this mouse's event queue.  `null` is returned if the
 
queue is empty.
 
 
 
The object returned has the following properties:
 
 
 
    event.key
 
 
 
        A MouseKey value representing the type of the click or other event.
 
        For example, a left mouse click is represented as MouseKey.Left.
 
 
 
    event.x
 
    event.y
 
 
 
        The X and Y position of the mouse cursor relative to the rendering
 
        area at the time the event was received.</pre>
 
Mouse#isPressed(key);
 
 
 
<pre>Gets whether the specified mouse button is currently pressed.  `key` is one
 
of the MouseKey constants listed above.
 
 
 
Note: This function always returns false for virtual keys such as WheelUp
 
      and WheelDown.</pre>
 
== Graphics API ==
 
 
 
Unlike in Sphere 1.x, in second-generation games all rendering, both 2D and 3D, is done through the Galileo API. Galileo represents a more modern, polygon- based approach to graphics. Scenes are built from groups of Shape objects representing graphics primitives (triangle strips, fans, etc.).
 
 
 
screen [global variable]
 
 
 
<pre>A Surface object (see below) representing the primary render target--
 
specifically, the backbuffer.  Anything drawn to this surface will become
 
visible to the player when calling `screen.flip()`.</pre>
 
screen.frameRate [read/write]
 
 
 
<pre>Gets or sets the frame rate used to regulate `screen.flip()` (see below).
 
Set this to Infinity to disable the frame limiter.</pre>
 
screen.frameSkip [read/write]
 
 
 
<pre>Gets or sets the maximum number of frames the engine is allowed to skip in
 
order to maintain the desired frame rate.</pre>
 
screen.fullScreen [read/write]
 
 
 
<pre>Gets or sets whether the engine is running in fullscreen mode.  Set this to
 
`true` for fullscreen, or `false` for windowed.</pre>
 
screen.width [read-only] screen.height [read-only]
 
 
 
<pre>Gets the width and height of the screen resolution.</pre>
 
screen.clipTo(x, y, width, height);
 
 
 
<pre>Changes the clipping rectangle.  Anything drawn outside of the clipping
 
rectangle won't be rendered.  The effect lasts until the next backbuffer
 
flip.</pre>
 
screen.flip();
 
 
 
<pre>Performs event loop processing and flips the backbuffer to the screen.
 
`screen.frameRate` determines the maximum number of flips to perform per
 
second; this makes it easier to regulate your game's update rate.
 
 
 
After a flip, the backbuffer is cleared to black.  If you need to perform a
 
long operation without disturbing the contents of the screen, you should
 
use Sphere.run() instead of screen.flip() to run the event loop.
 
 
 
Note: Calling screen.flip() resets the clipping rectangle.  See the entry
 
      for screen.clipTo() above.</pre>
 
screen.now();
 
 
 
<pre>Returns the number of frames (including skipped frames) processed by the
 
engine since it started running.
 
 
 
Note: This value will wrap around to zero after around 4.3 billion frames.
 
      That typically isn't an issue: at 60 FPS, a game would need to run
 
      continuously for *over 2 years* before it would roll over.</pre>
 
screen.resize(width, height);
 
 
 
<pre>Changes the game's resolution.  The change is not persistent and lasts only
 
until the engine is closed.</pre>
 
Color.Red [read-only] Color.Green [read-only] Color.Blue [read-only] Color.Transparent [read-only] etc...
 
 
 
<pre>Gets a copy of a predefined color.  The entire X11 color set is provided,
 
giving you access to such colors as `DodgerBlue` and `Chartreuse` in
 
addition to the standard red, green, blue, yellow, etc.
 
 
 
Each of these is an accessor which returns a new Color object every time
 
it is invoked.  This ensures that code like what's shown below won't cause
 
undesirable side effects:
 
 
 
    var color = Color.Red;
 
    color.blue = 255;  // we needed magenta instead
 
 
 
The downside to this is that e.g. `Color.Red === Color.Red` evaluates to
 
false, but this is rarely an issue in practice.</pre>
 
Color.is(color1, color2);
 
 
 
<pre>Returns true if `color1` refers to the same physical color as `color2`
 
without regard to their alpha components.  Otherwise returns false.
 
 
 
Note: This is not the same as comparing the color objects' .name properties
 
      because Color#name encodes the alpha channel in addition to the
 
      physical color.</pre>
 
Color.mix(color1, color2[, w1, w2]);
 
 
 
<pre>Calculates a weighted average of two colors.  `w1` and `w2` are optional
 
and specify the relative weights of `color1` and `color2` respectively.  If
 
the weights are omitted, the mix is 50/50.</pre>
 
Color.of(name);
 
 
 
<pre>Returns a Color object from `name`, which can either be the name of a
 
predefined X11 color without spaces (e.g. &quot;chartreuse&quot;), or an ARGB
 
signature such as &quot;#800000FF&quot;.  If `name` cannot be resolved to a color,
 
throws a TypeError.</pre>
 
new Color(red, green, blue[, alpha]);
 
 
 
<pre>Constructs a new Color object.  Color objects are used to specify the color
 
of elements such as vertices and primitives.  Color components should be in
 
the range [0.0-1.0] and out-of-range values will be silently clamped.
 
`alpha` specifies opacity and defaults to 1.0 if not provided.</pre>
 
Color#red [read/write] Color#green [read/write] Color#blue [read/write] Color#alpha [read/write]
 
 
 
<pre>Gets or sets the individual components of the color.  Values outside the
 
range of [0-1] are accepted, but the engine will automatically clamp them
 
during rendering.</pre>
 
Color#name [read-only]
 
 
 
<pre>Gets the name of the Color according to its component values such that
 
Color.of(color.name) will give back a Color with the same values.  Useful
 
for saving and reading back colors from save files.</pre>
 
Color#clone();
 
 
 
<pre>Returns a copy of this Color object.  Changes to the clone will not affect
 
the original object.</pre>
 
Color#fade(alpha);
 
 
 
<pre>Scales this color's alpha channel by `alpha`, between 0.0 and 1.0, and
 
returns the result.  The red, green, and blue components are not modified.
 
This is useful when you need to make a predefined color translucent, for
 
instance:
 
 
 
    var translucentBlue = Color.Blue.fade(0.5);</pre>
 
Font.Default [read-only]
 
 
 
<pre>Gets the default engine font.  This is the font used for the FPS counter
 
and system messages.</pre>
 
new Font(filename);
 
 
 
<pre>Constructs a Font object from a font file.  Currently only the Sphere RFN
 
font format is supported.</pre>
 
Font#fileName [read-only]
 
 
 
<pre>Gets the full, canonical SphereFS filename of the file used to construct
 
this Font object.</pre>
 
Font#height [read-only]
 
 
 
<pre>Gets the line height, in pixels, for text rendered using this font.</pre>
 
Font#drawText(surface, x, y, text[, color[, wrap_width]]);
 
 
 
<pre>Renders `text` to the specified surface at (x,y).  `color` defaults to
 
Color.White if not provided, and `wrap_width` specifies the width in which
 
to constrain the text.  If `wrap_width` is not provided, no wrapping is
 
performed.</pre>
 
Font#getTextSize(text, wrap_width);
 
 
 
<pre>Gets the size, in pixels, of `text` if it were rendered by Font:drawText()
 
with the specified wrap width.  Return value is an object with `width` and
 
`height` properties.</pre>
 
Font#wordWrap(text, wrap_width);
 
 
 
<pre>Wraps `text` as if it were drawn with Font#drawText() using the specified
 
wrap width.  Returns an array of strings, representing the lines in the
 
wrapped text.
 
 
 
When drawing large amounts of word-wrapped text every frame, for example in
 
a text box, this function should be used to pre-wrap the text since
 
performing wrapping calculations every frame can get expensive.</pre>
 
new Texture(filename);
 
 
 
<pre>Constructs a new Texture object from an image file.  Unlike images in
 
Sphere v1, these cannot be rendered directly but instead must be used to
 
texture a Shape object.
 
 
 
Note that Textures are read-only.  If you need a writable image, you should
 
use a Surface object instead.</pre>
 
new Texture(width, height, pixels);
 
 
 
<pre>Constructs a new Texture from a pixel buffer.  `width` and `height` specify
 
the size of the texture image, and `pixels` is an ArrayBuffer containing
 
the RGBA pixel data to use to initialize the image.  The pixel data should
 
not be padded (i.e. stride is equal to width).
 
 
 
An error is thrown if the ArrayBuffer doesn't contain enough pixel data to
 
describe the entire texture.</pre>
 
Texture#fileName [read-only]
 
 
 
<pre>Gets the full, canonical SphereFS filename of the file used to construct
 
this Texture object.  For synthesized textures, returns null.</pre>
 
Texture#width [read-only] Texture#height [read-only]
 
 
 
<pre>Gets the width or height of the texture, in pixels.</pre>
 
new Model(shapes[, shader]);
 
 
 
<pre>Constructs a Model out of the provided array of Shape objects.  `shader` is
 
the Shader to use when rendering the model.  See below for more information
 
on shaders.
 
 
 
When a Model is created, its transformation matrix is set to the
 
identity matrix.  If `shader` is not provided, the default shader program
 
will be used (see `Shader.Default`).</pre>
 
Model#shader [read/write]
 
 
 
<pre>Gets or sets the Shader to use when drawing this model.</pre>
 
Model#transform [read/write]
 
 
 
<pre>Gets or sets the transformation matrix to use when drawing this model.</pre>
 
Model#draw(surface);
 
 
 
<pre>Draws the model on `surface`.  Any transformations defined for the model
 
(see below) are applied as if all the shapes comprising it were a single
 
primitive.</pre>
 
Model#setFloat(name, value); Model#setInt(name, value); Model#setMatrix(name, transform);
 
 
 
<pre>Sets the value of a GLSL uniform.  When the model is drawn, if its shader
 
program contains a uniform called `name` of the proper type, the value will
 
be uploaded to that uniform.  It is safe to call this even if the uniform
 
turns out not to exist (in which case the call is effectively a no-op).</pre>
 
Shader.Default [read-only]
 
 
 
<pre>Gets the default Galileo shader program.  This is a very barebones shader
 
which uses screen coordinates for vertices and performs only basic texture
 
mapping.</pre>
 
new Shader(options);
 
 
 
<pre>Constructs a Shader from a set of shader sources.  `options` should be an
 
object with the following properties:
 
 
 
    options.vertex
 
 
 
        The name of the file containing source code for the GLSL vertex
 
        shader.
 
 
 
    options.fragment
 
 
 
        The name of the file containing source code for the GLSL fragment
 
        shader.
 
 
 
Note that HLSL (DirectX) shaders are not supported, even on Windows.</pre>
 
ShapeType [enumeration]
 
 
 
<pre>Specifies the type of graphics primitive represented by a Shape object.
 
Can be one of the following:
 
 
 
    ShapeType.Auto
 
    ShapeType.Fan
 
    ShapeType.Lines
 
    ShapeType.LineLoop
 
    ShapeType.LineStrip
 
    ShapeType.Points
 
    ShapeType.Triangles
 
    ShapeType.TriStrip</pre>
 
new Shape(vertices[, texture[, type]]);
 
 
 
<pre>Constructs a primitive shape out of the provided array of vertices textured
 
with the Image specified by `texture`.
 
 
 
Each vertex can have the following properties:
 
 
 
    vertex.x, vertex.y
 
 
 
        The location of the vertex.  The final location of each vertex can
 
        be modified by using a transformation matrix (see Matrix above).
 
 
 
    vertex.u, vertex.v
 
 
 
        The texture coordinates of the vertex.  This is used to control
 
        which part of the texture will be applied to this vertex.  If u/v
 
        is not provided for a vertex, it will be assumed to be have its u/v
 
        at (0, 0).
 
 
 
    vertex.color
 
 
 
        The color of the vertex.  The vertex colors will be multiplied with
 
        texture pixels to determine the final color of each pixel in a
 
        shape.
 
 
 
`type` specifies the type of primitive (see ShapeType above).  If `type` is
 
ShapeType.Auto (the default), the type is determined automatically based on
 
the number of vertices.</pre>
 
Shape#texture [read/write]
 
 
 
<pre>The Image to use when texturing the shape. This can be null, in which case
 
the vertex colors alone will determine the shape's appearance.</pre>
 
Shape#draw(surface[, transform]);
 
 
 
<pre>Draws the shape.  `transform` is the Transform to use, and `surface` is the
 
Surface to draw on.  If `surface` is omitted, the shape is drawn on the
 
backbuffer.</pre>
 
new Surface(width, height[, fill_color]);
 
 
 
<pre>Constructs a new surface with the specified width and height, optionally
 
filled with 'fill_color'.  If a fill color is not provided, the created
 
surface will be filled with transparent pixels.
 
 
 
Surfaces are meant to used as render targets from drawing operations.  This
 
enables static elements of a scene, such as a HUD, to be rendered in
 
advance, potentially improving performance.</pre>
 
new Surface(filename);
 
 
 
<pre>Constructs a new Surface whose initial contents are taken from the
 
specified image file.</pre>
 
Surface#width [read-only] Surface#height [read-only]
 
 
 
<pre>Gets the width and height of the surface, in pixels.</pre>
 
Surface#toTexture();
 
 
 
<pre>Returns a Texture created from the current contents of this Surface.  Note
 
that drawing to the surface afterwards will not affect the texture, which
 
is read-only.</pre>
 
new Transform();
 
 
 
<pre>Constructs a transformation matrix.  The object represents a 4x4 matrix
 
and is initialized to identity.</pre>
 
Transform#identity();
 
 
 
<pre>Re-initializes this matrix as an identity matrix.</pre>
 
Transform#compose(otherMatrix);
 
 
 
<pre>Composes this transform with another.  `otherMatrix` is multiplied from the
 
left such that transformations are performed in the order you specify.</pre>
 
Transform#rotate(theta[, vx, vy, vz]);
 
 
 
<pre>Applies a rotation transformation to this matrix.  `theta` is the angle of
 
rotation, in radians.  (vx, vy, vz) is the vector to rotate about.  For
 
example the default is (0, 0, 1) which rotates about the Z axis.</pre>
 
Transform#scale(sx, sy);
 
 
 
<pre>Applies a scaling transformation to this matrix.  `sx` and `sy` are the
 
horizontal and vertical scaling factors, respectively.</pre>
 
Transform#translate(tx, ty);
 
 
 
<pre>Applies a translation transformation to this matrix.  `tx` and `ty` are the
 
horizontal and vertical translations, respectively.</pre>
 
== Audio API ==
 
 
 
Playing sounds and music are both handled in miniSphere by Audialis, the evolution of Sphere 1.x's audio subsystem. Audialis allows you to create mixers which can be used to adjust certain parameters across all sounds associated with that mixer. This is useful for implementing global volume controls, for example.
 
 
 
Mixer.Default [read-only]
 
 
 
<pre>Gets the default Audialis audio mixer.  The default mixer outputs 44.1 kHz
 
16-bit stereo sound, i.e. CD quality.</pre>
 
new Mixer(frequency, bits[, channels]);
 
 
 
<pre>Constructs a new Mixer object.  Any sounds played through the mixer will use
 
the format specified by the parameters above.  `frequency` is the sample
 
rate, `bits` specifies the bit depth (allowed values are 8, 16 and 24), and
 
`channels` is the number of channels, ranging [1-7].  Channel counts of 5 or
 
higher imply an additional LFE channel (i.e. 5.1, 6.1, 7.1).
 
 
 
Do note that this creates a _hardware_ mixer.  If the requested format is
 
not supported by the system, an error will be thrown (&quot;unable to create
 
hardware voice&quot;).</pre>
 
Mixer#volume [read/write]
 
 
 
<pre>Gets or sets the output volume of the mixer.  This will affect the volume
 
of any sounds played through the mixer.</pre>
 
new Sample(filename);
 
 
 
<pre>Constructs a Sample from the specified audio file.  The audio data is
 
loaded into memory in its entirety and multiple instances can be played
 
simultaneously with no latency, making this very useful for sound effects.
 
Supported formats are Ogg Vorbis (.ogg), WAV, and FLAC.
 
 
 
Note: Compressed formats like Vorbis will be decompressed during loading,
 
      potentially using a large amount of RAM.  It is therefore not
 
      recommend to use `Sample` objects for, e.g., background music.  Use a
 
      `Sound` instead.</pre>
 
Sample#fileName [read-only]
 
 
 
<pre>Gets the full, canonical SphereFS path of the audio file used to construct
 
this sample.</pre>
 
Sample#play(mixer[, options]);
 
 
 
<pre>Plays the sample on the specified mixer.  Each time this is called, a new
 
stream is started, allowing many instances of the sound to be playing
 
simultaneously.
 
 
 
`options`, if present, must be an object and can include the following
 
properties (all optional):
 
 
 
    options.volume
 
 
 
        The volume level to play the sound at.  1.0 is full volume, 0.0 is
 
        silent.  Volume levels higher than 1.0 will amplify the sound but
 
        may cause distortion.  Volume is 1.0 if not specified.
 
 
 
    options.pan
 
 
 
        A volume between -1.0 and 1.0 specifying the left/right balance.
 
        -1.0 is full left, +1.0 is full right, and 0.0 is dead center.  Pan
 
        is 0.0 (center) if not specified.
 
 
 
    options.speed
 
 
 
        Playback speed, where 1.0 is normal speed.  Also affects pitch.
 
        Speed is 1.0x if not specified.</pre>
 
Sample#stopAll();
 
 
 
<pre>Stops playback of all active instances of this sample.</pre>
 
new Sound(filename);
 
 
 
<pre>Constructs a Sound object from the specified audio file.  Supported sound
 
formats are Ogg Vorbis (.ogg), WAV, MOD, S3M, IT, and FLAC.  Note that
 
unlike in Sphere 1.x, mp3 and MIDI formats are not supported.</pre>
 
Sound#fileName [read-only]
 
 
 
<pre>Gets the full, canonical SphereFS filename of the file used to construct
 
this Sound object.</pre>
 
Sound#length [read-only]
 
 
 
<pre>Gets the length of the sound in microseconds.</pre>
 
Sound#pan [read/write]
 
 
 
<pre>Gets or sets the current pan (balance). 0.0 is dead center, -1.0 is full
 
left, and 1.0 is full right.</pre>
 
Sound#playing [read-only]
 
 
 
<pre>true if the sound is currently playing, false otherwise.</pre>
 
Sound#position [read/write]
 
 
 
<pre>Gets or sets the playback position within the sound, in seconds.</pre>
 
Sound#repeat [read/write]
 
 
 
<pre>Gets or sets whether the sound will automatically repeat when it reaches
 
the end.</pre>
 
Sound#speed [read/write]
 
 
 
<pre>Gets the current playback speed of the sound.  1.0 is normal, 2.0 is double
 
speed, etc.  Note that changing the playback speed affects the pitch as
 
well.</pre>
 
Sound#volume [read/write]
 
 
 
<pre>Gets or sets the current volume of the sound.  0.0 is silent, 1.0 is full
 
volume.  Higher values are allowed, but may introduce distortion due to
 
clipping.</pre>
 
Sound#pause();
 
 
 
<pre>Pauses the sound.  If it is already paused, this has no effect.</pre>
 
Sound#play([mixer]);
 
 
 
<pre>Begins or resumes sound playback.  When called with no `mixer` argument,
 
Sound#play() will resume playback for a paused sound.  Otherwise, the sound
 
is started from the beginning on the specified mixer.</pre>
 
Sound#stop();
 
 
 
<pre>Stops the sound.  Playback position will be reset to the beginning (0.0s),
 
even if the sound was not playing.</pre>
 
new SoundStream([frequency[, bits[, channels]]]);
 
 
 
<pre>Constructs a sound stream, which plays arbitrary sound data provided by the
 
game at runtime.  This may be used, for example, to generate sound
 
procedurally or add support for an unsupported audio format in script.
 
`frequency` specifies the stream's sample rate and 'channels' the number of
 
audio channels, ranging [1-7].  Channel counts of 5 and higher imply an
 
additional LFE (subwoofer) channel.
 
 
 
The default stream format is 8-bit 22050Hz with 1 channel.</pre>
 
SoundStream#bufferSize [read-only]
 
 
 
<pre>Gets the total number of samples in the stream's buffer.</pre>
 
SoundStream#buffer(data);
 
 
 
<pre>Writes audio data to the stream buffer.  `data` is an ArrayBuffer,
 
TypedArray or DataView containing the data to write.  While a stream is
 
playing, audio data should be fed into it continuously to prevent skipping.</pre>
 
SoundStream#pause();
 
 
 
<pre>Pauses playback of the stream.  Has no effect if the stream is already
 
paused.</pre>
 
SoundStream#play([mixer]);
 
 
 
<pre>Starts the stream playing, or if no mixer is specified, resumes a paused
 
stream.  Before beginning playback, it is recommended to pre-buffer a few
 
seconds of audio into the stream (see SoundStream:buffer() below).  This
 
will minimize the risk of a buffer underrun and subsequent skipping during
 
playback.</pre>
 
SoundStream#stop();
 
 
 
<pre>Stops playback of the stream and frees its buffer.  This should be called
 
when you are done using a stream.  The stream may be reused after a stop()
 
call, but you will have to feed new audio data.</pre>
 
== File System API ==
 
 
 
miniSphere provides the <code>FS</code> object to allow games to access asset and save files, create or remove directories, and so on.
 
 
 
FS.createDirectory(dir_name);
 
 
 
<pre>Creates the specified directory and any of its parent directories that
 
don't already exist.</pre>
 
FS.deleteFile(filename);
 
 
 
<pre>Deletes `filename` from the file system.</pre>
 
FS.exists(filename);
 
 
 
<pre>Checks whether the specified file exists and returns true if it does.
 
Otherwise, returns false.</pre>
 
FS.readFile(filename);
 
 
 
<pre>Reads all data from the specified file and returns it as an ArrayBuffer.
 
This avoids the need to explicitly open and close a file when all you want
 
to do is read its contents into memory.</pre>
 
FS.removeDirectory(dir_name);
 
 
 
<pre>Deletes the specified directory.  The directory must be empty or an error
 
will be thrown.</pre>
 
FS.rename(srcname, destname);
 
 
 
<pre>Renames the file named by `srcname` to `destname`, both of which are
 
assumed to be full SphereFS paths.  This can also be used to move a file
 
between directories; if so, the destination directory must already exist.</pre>
 
FS.resolve(path);
 
 
 
<pre>Resolves a path (which may contain relative components) to its canonical
 
SphereFS representation.  This can be useful when data is associated with
 
individual assets, such as map files, and you need to ensure the same data
 
is pulled for a given file regardless of the path used to access it.
 
 
 
Note that the resource referred to by the path doesn't need to exist.  As
 
with other FS methods, FS.resolve() will throw an error if an absolute path
 
is passed in.</pre>
 
FS.writeFile(filename, data);
 
 
 
<pre>Writes an entire file in one go.  If a file already exists with the given
 
filename, it will be overwritten.  'data' is an ArrayBuffer, TypedArray or
 
DataView containing the data to be written.</pre>
 
new FileStream(filename, op);
 
 
 
<pre>Constructs a FileStream that provides access to the contents of a specified
 
file.  `op` specifies the file operation requested and must be one of the
 
following:
 
 
 
    FileOp.Read
 
 
 
        Read data from the file.  The file must exist and will be opened in
 
        read-only mode.  Any attempt to write to the file will throw a
 
        TypeError.
 
 
 
    FileOp.Write
 
 
 
        Write data to the file.  Be careful: If the file already exists,
 
        its contents will be overwritten.  If that behavior is not desired,
 
        use `FileOp.Update` instead.
 
 
 
    FileOp.Update
 
 
 
        Amend the file.  If a file by the specified name doesn't exist, it
 
        will be created.  For convenience, the file pointer is initially
 
        placed at the end of the file.
 
 
 
Requesting write access to a file residing in a read-only directory (e.g.,
 
the system directory `#/`) will throw a TypeError.</pre>
 
FileStream#dispose();
 
 
 
<pre>Disposes of the FileStream object, after which it should not be used.
 
Attempting to read or write to a stream after it is disposed of will throw
 
an error.
 
 
 
Note: While it's not strictly necessary to call `dispose()` on FileStreams,
 
      it may take some time for the garbage collector to get to them.  If
 
      there's an active FileStream in write mode for a given file, an error
 
      will be thrown if you try to construct another one.</pre>
 
FileStream#fileName [read-only]
 
 
 
<pre>Gets the full, canonical SphereFS filename of the underlying file.</pre>
 
FileStream#position [read/write]
 
 
 
<pre>Gets or sets the file position, which determines where in the file the next
 
read or write will start from.  Expressed in bytes.
 
 
 
Note: For files opened for writing, it is valid to seek past the end of the
 
      stream.  In this case the next write will be at the new position and
 
      the intervening space filled with NUL bytes.</pre>
 
FileStream#size [read-only]
 
 
 
<pre>Gets the size of the underlying file, in bytes.</pre>
 
FileStream#read(num_bytes);
 
 
 
<pre>Reads data from the file, up to the specified number of bytes, and returns
 
it as an ArrayBuffer.  The file must be opened for reading.</pre>
 
FileStream#write(data);
 
 
 
<pre>Writes data to the file and advances the file pointer.  `data` should be an
 
ArrayBuffer, TypedArray or DataView containing the data to be written.</pre>
 
== Networking API ==
 
 
 
miniSphere provides basic support for TCP sockets. There are two object types: Socket and Server. A Server is persistent and listens for connections on a given port, while Sockets represent individual client connections.
 
 
 
new Server(port[, backlog_size]);
 
 
 
<pre>Constructs a new server which listens for connections on the specified
 
port.  `backlog_size` specifies the size of the backlog.  If the backlog
 
fills, new connections will be dropped.</pre>
 
Server#accept();
 
 
 
<pre>If one or more connections are waiting in the backlog, removes it from the
 
queue and returns a Socket object representing the connection.  Otherwise,
 
returns null.  This should be called regularly to prevent the backlog from
 
filling up.</pre>
 
Server#close();
 
 
 
<pre>Shuts down the server.  Any connections in the backlog will be dropped and
 
no new connections can be made until a new Server is created.</pre>
 
new Socket(hostname, port);
 
 
 
<pre>Connects to `hostname` on `port` and constructs an Socket representing the
 
connection.  The hostname can either be a named address (e.g. google.com)
 
or an IP address (e.g. 127.0.0.1).  As this operation is non-blocking, a
 
Socket object will be returned even if the connection can be not be made;
 
you must poll Socket#connected to find out when the connection has opened.</pre>
 
Socket#bytesPending [read-only]
 
 
 
<pre>Gets the number of bytes of data currently in the receive buffer.  Call
 
Socket#read() to retrieve this data.
 
 
 
Note that more data may be received between the time this is checked the
 
time a read is performed.  It's recommended to poll this value from time to
 
time and perform reads in order to keep the size of the receive buffer
 
down.</pre>
 
Socket#connected [read-only]
 
 
 
<pre>Gets whether the connection has been established.  As long as this is
 
false, you cannot call any other methods on the socket object.  Doing so
 
will cause an error to be thrown.</pre>
 
Socket#remoteAddress [read-only]
 
 
 
<pre>Gets the IP address of the upstream end of the socket.  Throws an error if
 
accessed before a connection has been established.</pre>
 
Socket#remotePort [read-only]
 
 
 
<pre>Gets the port that the remote machine is using for the connection.
 
Generally not a useful statistic, but it's there if you need it.  Throws an
 
error if accessed before a connection is established.</pre>
 
Socket#close();
 
 
 
<pre>Disconnects the socket.  Note that any given Socket object is tied to a
 
specific session and so cannot be reused after it has been closed.</pre>
 
Socket#read(num_bytes);
 
 
 
<pre>Reads up to `num_bytes` bytes from the socket and returns an ArrayBuffer
 
containing the data received.  This method is non-blocking: If more bytes
 
are requested than are available, only the available data will be returned.</pre>
 
Socket#write(data);
 
 
 
<pre>Writes data to the socket, which can be read at the other end.  `data` can
 
be either an ArrayBuffer, TypedArray view, or DataView.</pre>
 

Latest revision as of 16:05, 2 November 2017


The Sphere API is the collective name for the set of bindings (functions, objects, and methods) available for use by all Sphere games. The API provides access to a host of convenient features, allowing you to get up and running quickly.


Making new function/object pages

Simple steps:
  1. Before getting started, please check the Article standards and practices.
  2. Click a red link.
  3. Place the following code in the empty edit box:
    1. For a new function: {{subst:functemp|preamble=REPLACEME|function=REPLACEME|object=REPLACEME|returns=REPLACEME|params=REPLACEME}}
    2. For a new object: {{subst:objecttemp|preamble=REPLACEME|function=REPLACEME|object=REPLACEME|returns=REPLACEME|params=REPLACEME}}
  4. Check the minor edit flag and save.
  5. Click 'edit' at the top of the page to add content.
  6. Try to be objective when writing, and save when you're done.
  7. Remove description from this page, add page link to list at the top of the matching section.


Core API

The Core API provides low-level access to the engine's features and includes all bindings provided directly by the engine. These bindings are exposed to the global scope and can be used without importing any extra modules.

Sphere Game Platform

Debugging

Files and Directories

Random Number Generation

Sphere Runtime

The Sphere Runtime is a standard collection of JavaScript modules included with the engine. Some modules can even be used in Cellscripts as well! Unlike the Core API above which was organized by category, the following list is organized by module. Most modules export only a single object or function; to import more than one at a time, you can use an ES2015 import statement and import objects from the sphere-runtime or cell-runtime module, as appropriate:

In a Sphere game

import { from, Music, Thread } from 'sphere-runtime';

In a Cellscript

import { assert, transpile } from 'cell-runtime';

from Module

image Module

logger Module

music Module

prim Module

random Module

thread Module

Miscellaneous

  • SphereFS - How the file system prefixes work.