{{DISPLAYTITLE:Sphere v2 API}}

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__

== 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 ===

<tt>
* [[API:Sphere.APILevel|Sphere.APILevel]]
* [[API:Sphere.Game|Sphere.Game]]
* [[API:Sphere.Platform|Sphere.Platform]]
* [[API:Sphere.Version|Sphere.Version]]
* [[API:Sphere.abort|Sphere.abort()]]
* [[API:Sphere.exit|Sphere.exit()]]
* [[API:Sphere.restart|Sphere.restart()]]
* [[API:Sphere.run|Sphere.run()]]
* [[API:Sphere.sleep|Sphere.sleep()]]
</tt>

=== Debugging ===

<tt>
* [[API:SSj.log|SSj.log()]]
* [[API:SSj.trace|SSj.trace()]]
</tt>

=== Files and Directories ===

<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>

=== Random Number Generation ===

<tt>
* [[API:RNG.fromSeed|RNG.fromSeed()]]
* [[API:RNG.fromState|RNG.fromState()]]
* [[API:RNG|new RNG()]]
** [[API:RNG::state|RNG::state]]
** [[API:RNG::next|RNG::next()]]
</tt>

== 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 <tt>import</tt> statement and import objects from the <tt>sphere-runtime</tt> or <tt>cell-runtime</tt> module, as appropriate:

==== In a Sphere game ====

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

==== In a Cellscript ====

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

=== <tt>from</tt> Module ===

<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>

=== <tt>image</tt> Module ===

<tt>
* [[API:Image|new Image()]]
** [[API:Image::blitTo|Image::blitTo()]]
</tt>

=== <tt>logger</tt> Module ===

<tt>
* [[API:Logger|new Logger()]]
** [[API:Logger::beginGroup|Logger::beginGroup()]]
** [[API:Logger::endGroup|Logger::endGroup()]]
** [[API:Logger::write|Logger::write()]]
</tt>

=== <tt>music</tt> Module ===

<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>

=== <tt>prim</tt> Module ===

<tt>
* [[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>

=== <tt>random</tt> Module ===

<tt>
* [[API:Random.chance|Random.chance()]]
* [[API:Random.discrete|Random.discrete()]]
* [[API:Random.normal|Random.normal()]]
* [[API:Random.sample|Random.sample()]]
* [[API:Random.string|Random.string()]]
* [[API:Random.uniform|Random.uniform()]]
</tt>

=== <tt>thread</tt> Module ===

<tt>
* [[API:Thread.create|Thread.create()]]
* [[API:Thread.isRunning|Thread.isRunning()]]
* [[API:Thread.join|Thread.join()]]
* [[API:Thread.kill|Thread.kill()]]
* [[API:Thread.self|Thread.self()]]
* [[API:Thread|new Thread()]]
** [[API:Thread::running|Thread::running]]
** [[API:Thread::dispose|Thread::dispose()]]
** [[API:Thread::join|Thread::join()]]
** [[API:Thread::start|Thread::start()]]
** [[API:Thread::stop|Thread::stop()]]
</tt>

= ...and more to come! =

API:Functions

2017-08-18T02:53:10Z

Bruce Pascoe: /* Sphere Runtime */ Add more modules to list

{{DISPLAYTITLE:Sphere v2 API}}

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__

== 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 ===

<tt>
* [[API:Sphere.APILevel|Sphere.APILevel]]
* [[API:Sphere.Game|Sphere.Game]]
* [[API:Sphere.Platform|Sphere.Platform]]
* [[API:Sphere.Version|Sphere.Version]]
* [[API:Sphere.abort|Sphere.abort()]]
* [[API:Sphere.exit|Sphere.exit()]]
* [[API:Sphere.restart|Sphere.restart()]]
* [[API:Sphere.run|Sphere.run()]]
* [[API:Sphere.sleep|Sphere.sleep()]]
</tt>

=== Debugging ===

<tt>
* [[API:SSj.log|SSj.log()]]
* [[API:SSj.trace|SSj.trace()]]
</tt>

=== Files and Directories ===

<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>

=== Random Number Generation ===

<tt>
* [[API:RNG.fromSeed|RNG.fromSeed()]]
* [[API:RNG.fromState|RNG.fromState()]]
* [[API:RNG|new RNG()]]
** [[API:RNG::state|RNG::state]]
** [[API:RNG::next|RNG::next()]]
</tt>

== 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 <tt>import</tt> statement and specify the <tt>sphere-runtime</tt> module, like so:

import { from, Music, Thread } from 'sphere-runtime'; // in a Sphere game
import { transpile } from 'cell-runtime'; // in a Cellscript

=== <tt>from</tt> Module ===

<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>

=== <tt>image</tt> Module ===

<tt>
* [[API:Image|new Image()]]
** [[API:Image::blitTo|Image::blitTo()]]
</tt>

=== <tt>logger</tt> Module ===

<tt>
* [[API:Logger|new Logger()]]
** [[API:Logger::beginGroup|Logger::beginGroup()]]
** [[API:Logger::endGroup|Logger::endGroup()]]
** [[API:Logger::write|Logger::write()]]
</tt>

=== <tt>music</tt> Module ===

<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>

=== <tt>prim</tt> Module ===

<tt>
* [[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>

=== <tt>random</tt> Module ===

<tt>
* [[API:Random.chance|Random.chance()]]
* [[API:Random.discrete|Random.discrete()]]
* [[API:Random.normal|Random.normal()]]
* [[API:Random.sample|Random.sample()]]
* [[API:Random.string|Random.string()]]
* [[API:Random.uniform|Random.uniform()]]
</tt>

=== <tt>thread</tt> Module ===

<tt>
* [[API:Thread.create|Thread.create()]]
* [[API:Thread.isRunning|Thread.isRunning()]]
* [[API:Thread.join|Thread.join()]]
* [[API:Thread.kill|Thread.kill()]]
* [[API:Thread.self|Thread.self()]]
* [[API:Thread|new Thread()]]
** [[API:Thread::running|Thread::running]]
** [[API:Thread::dispose|Thread::dispose()]]
** [[API:Thread::join|Thread::join()]]
** [[API:Thread::start|Thread::start()]]
** [[API:Thread::stop|Thread::stop()]]
</tt>

= ...and more to come! =

API:Functions

2017-08-17T19:24:20Z

Bruce Pascoe: Start cataloguing Sphere v2 functions

SphereFS

2017-08-17T18:10:47Z

Bruce Pascoe: Add WIP SphereFS page

'''SphereFS''' is a standardized system used by Sphere for unambiguously specifying pathnames of files and directories within the sandboxed JavaScript environment.

A canonical SphereFS pathname consists of a prefix, for example <tt>@/</tt> or <tt>~/</tt>, followed by one or more directory components separated by slashes, and finally an optional filename. Each prefix is either a unique root in itself or else an alias for a directory within one of those roots. Prefixes other than <tt>~/</tt> are write-protected, and it is not possible to reference files outside the sandbox. OS paths such as '''C:\file.txt''' or '''/usr/bin/eatypig''' are not legal within the SphereFS sandbox, nor are relative paths that extend uplevel from a prefix, e.g. '''@/../../maggie.fat'''. Passing such a path to a Sphere API function expecting a file or directory name will cause an exception.

__TOC__

== Introduction ==

TODO: write this section

== Prefixes ==

TODO: write this section

== Path Resolution ==

TODO: write this section too

== Save ID ==

In order for a game to use the <tt>~/</tt> prefix, it must include a '''save ID ''' in its JSON manifest. The save ID should be unique for each game or series and typically takes the form <tt>''authorName''.''gameName''</tt>, where both parts are written in camelCase. For example, ''Spectacles: Bruce's Story'''s save ID is <tt>fatCerberus.spectacles</tt>.

== See Also ==

* [[THE PIG]]: It eats you in 2 seconds
* [[THE COW]]: It eats a bunch of cats
* [[THE APE]]: It's the size of the universe. Bye bye cow and pig!

[[Category:Sphere 2 API]]

API:FS.fullPath

2017-08-17T17:34:35Z

Bruce Pascoe: FS.fullPath() API page

{{DISPLAYTITLE:FS.fullPath()}}

The '''<tt>FS.fullPath()</tt>''' function computes the canonical [[SphereFS]] pathname for a specified relative path and base directory.

===== Usage =====

''canon_path'' = '''FS.fullPath'''(''file_or_dir_name''[, ''base_path'']);

__TOC__

== API Information ==

=== Description ===

'''<tt>FS.fullPath()</tt>''' returns the complete, canonical SphereFS pathname for a given file or directory. If the path to be resolved already includes a SphereFS prefix such as <tt>@/</tt> or <tt>~/</tt>, then Sphere simply canonicalizes it (by removing any relative components); otherwise the path itself is considered relative and will be rebased before canonicalization. This allows you to get the full pathname of a file or directory given only its name and a known base directory, which can be useful in libraries.

=== Parameters ===

:{| class="wikitable"
!Name
!Type
!Default Value
!Description
|-
|''<tt>file_or_dir_name</tt>''
|style="text-align: center;"|''string''
|''n/a (Required)''
|The name of a file or directory. May include path components. It doesn't need to actually exist.
|-
|''<tt>base_path</tt>''
|style="text-align: center;"|''string''
|<tt>"@/"</tt>
|Specifies the base directory onto which relative paths will be rebased.
|}

=== Return Value ===

The full SphereFS pathname of the specified file or directory.

== See Also ==

<tt>
* [[API:FS.relativePath|FS.relativePath()]]
</tt>

[[Category:Sphere 2 API]]

API:DirectoryStream::next

2017-08-17T16:32:33Z

Bruce Pascoe: Note that return value is iterator-like

{{DISPLAYTITLE:DirectoryStream::next()}}

The '''<tt>DirectoryStream::next()</tt>''' method reads the next directory entry from a directory stream.

===== Usage =====

''dir_entry'' = ''dirstream_obj''.'''next'''();

__TOC__

== API Information ==

=== Description ===

<tt>'''DirectoryStream::next()'''</tt> reads the next directory entry from the stream and advances the stream position. The value of <tt>[[API:DirectoryStream::position|DirectoryStream::position]]</tt> determines which entry is read.

=== Parameters ===

This method has no parameters.

=== Return Value ===

An object with two properties, <tt>.done</tt> and <tt>.value</tt>, with semantics compatible with the ES2015 iterator protocol. If there are no more entries to retrieve, <tt>.done</tt> is <tt>true</tt> and <tt>.value</tt> is <tt>undefined</tt>. Otherwise, <tt>.done</tt> is <tt>false</tt> and <tt>.value</tt> is an object describing the directory entry:

:{| class="wikitable"
!Property
!Type
!Description
|-
|<tt>.fileName</tt>
|style="text-align: center;"|''string''
|The name of the file or directory, e.g. <tt>pig.js</tt>. If the entry is a directory, <tt>.fileName</tt> will end in a slash (<tt>/</tt>).
|-
|<tt>.fullPath</tt>
|style="text-align: center;"|''string''
|The full SphereFS pathname of the file or directory, e.g. <tt>@/scripts/pig.js</tt>.
|-
|<tt>.isDirectory</tt>
|style="text-align: center;"|''boolean''
|<tt>true</tt> if the entry is a directory, otherwise <tt>false</tt>.
|}

== See Also ==

<tt>
* [[API:DirectoryStream|new DirectoryStream()]]
* [[API:DirectoryStream::position|DirectoryStream::position]]
* [[API:DirectoryStream::rewind|DirectoryStream::rewind()]]
</tt>

[[Category:Sphere 2 API]]

API:DirectoryStream::next

2017-08-15T18:31:45Z

Bruce Pascoe: Add page for DirectoryStream::next()

{{DISPLAYTITLE:DirectoryStream::next()}}

The '''<tt>DirectoryStream::next()</tt>''' method reads the next directory entry from a directory stream.

===== Usage =====

''dir_entry'' = ''dirstream_obj''.'''next'''();

__TOC__

== API Information ==

=== Description ===

<tt>'''DirectoryStream::next()'''</tt> reads the next directory entry from the stream and advances the stream position. The value of <tt>[[API:DirectoryStream::position|DirectoryStream::position]]</tt> determines which entry is read.

=== Parameters ===

This method has no parameters.

=== Return Value ===

An object with two properties, <tt>.done</tt> and <tt>.value</tt>. If there are no more entries to retrieve, <tt>.done</tt> is <tt>true</tt> and <tt>.value</tt> is <tt>undefined</tt>. Otherwise, <tt>.done</tt> is <tt>false</tt> and <tt>.value</tt> is an object describing the directory entry:

:{| class="wikitable"
!Property
!Type
!Description
|-
|<tt>.fileName</tt>
|style="text-align: center;"|''string''
|The name of the file or directory, e.g. <tt>pig.js</tt>. If the entry is a directory, <tt>.fileName</tt> will end in a slash (<tt>/</tt>).
|-
|<tt>.fullPath</tt>
|style="text-align: center;"|''string''
|The full SphereFS pathname of the file or directory, e.g. <tt>@/scripts/pig.js</tt>.
|-
|<tt>.isDirectory</tt>
|style="text-align: center;"|''boolean''
|<tt>true</tt> if the entry is a directory, otherwise <tt>false</tt>.
|}

== See Also ==

<tt>
* [[API:DirectoryStream|new DirectoryStream()]]
* [[API:DirectoryStream::position|DirectoryStream::position]]
* [[API:DirectoryStream::rewind|DirectoryStream::rewind()]]
</tt>

[[Category:Sphere 2 API]]

API:DirectoryStream

2017-08-14T03:26:34Z

Bruce Pascoe: Add DirectoryStream::dispose()

{{DISPLAYTITLE:new DirectoryStream()}}

The '''<tt>new DirectoryStream()</tt>''' constructor initializes an object that allows you to enumerate the contents of a directory.

===== Usage =====

''dirstream_obj'' = '''new DirectoryStream'''(''dir_name'');

__TOC__

== API Information ==

=== Description ===

<tt>'''new DirectoryStream()'''</tt> constructs a Directory Stream object, which allows you to enumerate the contents of a directory. Directory streams only provide filenames; you must use a <tt>[[API:FileStream|FileStream]]</tt> to access the contents of a file.

<table>
<tr>
<td>''Note:''</td>
<td>The <tt>DirectoryStream</tt> class implements the JavaScript ''iterator protocol'', which means you can use them in <tt>[[API:from|from()]]</tt> queries and <tt>for-of</tt> loops.</td>
</tr>
</table>

=== Parameters ===

<table>
<tr>
<td align=right width=100>'''''dir_name'''''</td>
<td>Path to the directory to be enumerated. Relative to the game manifest unless a SphereFS prefix is included.</td>
</tr>
</table>

=== Return Value ===

A newly constructed <tt>DirectoryStream</tt> object pointing at <tt>''dir_name''</tt>.

== Class Information ==

=== Properties ===

<tt>
* [[API:DirectoryStream::fileCount|DirectoryStream::fileCount]]
* [[API:DirectoryStream::fileName|DirectoryStream::fileName]]
* [[API:DirectoryStream::position|DirectoryStream::position]]
</tt>

=== Methods ===

<tt>
* [[API:DirectoryStream::dispose|DirectoryStream::dispose()]]
* [[API:DirectoryStream::next|DirectoryStream::next()]]
* [[API:DirectoryStream::rewind|DirectoryStream::rewind()]]
</tt>

== See Also ==

<tt>
* [[API:from|from()]]
* [[API:FileStream|new FileStream()]]
</tt>

[[Category:Sphere 2 API]]

API:DirectoryStream

2017-08-12T14:34:02Z

Bruce Pascoe: More organization - split function and class info

{{DISPLAYTITLE:new DirectoryStream()}}

The '''<tt>new DirectoryStream()</tt>''' constructor initializes an object that allows you to enumerate the contents of a directory.

===== Usage =====

''dirstream_obj'' = '''new DirectoryStream'''(''dir_name'');

__TOC__

== API Information ==

=== Description ===

<tt>'''new DirectoryStream()'''</tt> constructs a Directory Stream object, which allows you to enumerate the contents of a directory. Directory streams only provide filenames; you must use a <tt>[[API:FileStream|FileStream]]</tt> to access the contents of a file.

<table>
<tr>
<td>''Note:''</td>
<td>The <tt>DirectoryStream</tt> class implements the JavaScript ''iterator protocol'', which means you can use them in <tt>[[API:from|from()]]</tt> queries and <tt>for-of</tt> loops.</td>
</tr>
</table>

=== Parameters ===

<table>
<tr>
<td align=right width=100>'''''dir_name'''''</td>
<td>Path to the directory to be enumerated. Relative to the game manifest unless a SphereFS prefix is included.</td>
</tr>
</table>

=== Return Value ===

A newly constructed <tt>DirectoryStream</tt> object pointing at <tt>''dir_name''</tt>.

== Class Information ==

=== Properties ===

<tt>
* [[API:DirectoryStream::fileCount|DirectoryStream::fileCount]]
* [[API:DirectoryStream::fileName|DirectoryStream::fileName]]
* [[API:DirectoryStream::position|DirectoryStream::position]]
</tt>

=== Methods ===

<tt>
* [[API:DirectoryStream::next|DirectoryStream::next()]]
* [[API:DirectoryStream::rewind|DirectoryStream::rewind()]]
</tt>

== See Also ==

<tt>
* [[API:from|from()]]
* [[API:FileStream|new FileStream()]]
</tt>

[[Category:Sphere 2 API]]

API:DirectoryStream

2017-08-12T04:31:07Z

Bruce Pascoe: Add See Also section

{{DISPLAYTITLE:new DirectoryStream()}}

The '''<tt>new DirectoryStream()</tt>''' constructor initializes an object that allows you to enumerate the contents of a directory.

===== Usage =====

''dirstream_obj'' = '''new DirectoryStream'''(''dir_name'');

__TOC__

== API Information ==

=== Description ===

<tt>'''new DirectoryStream()'''</tt> constructs a Directory Stream object, which allows you to enumerate the contents of a directory. Directory streams only provide filenames; you must use a <tt>[[API:FileStream|FileStream]]</tt> to access the contents of a file.

<table>
<tr>
<td>''Note:''</td>
<td><tt>DirectoryStream</tt> objects are compatible with the JavaScript ''iterator protocol'', so you can use them in a <tt>[[API:from|from()]]</tt> query.</td>
</tr>
</table>

=== Parameters ===

<table>
<tr>
<td align=right width=100>'''''dir_name'''''</td>
<td>Path to the directory to be enumerated. Relative to the game manifest unless a SphereFS prefix is included.</td>
</tr>
</table>

=== Properties ===

<tt>
* [[API:DirectoryStream::fileCount|DirectoryStream::fileCount]]
* [[API:DirectoryStream::fileName|DirectoryStream::fileName]]
* [[API:DirectoryStream::position|DirectoryStream::position]]
</tt>

=== Methods ===

<tt>
* [[API:DirectoryStream::next|DirectoryStream::next()]]
* [[API:DirectoryStream::rewind|DirectoryStream::rewind()]]
</tt>

== See Also ==

<tt>
* [[API:from|from()]]
* [[API:FileStream|new FileStream()]]
</tt>

[[Category:Sphere 2 API]]

API:DirectoryStream

2017-08-12T04:27:53Z

Bruce Pascoe: Create DirectoryStream constructor page

{{DISPLAYTITLE:new DirectoryStream()}}

The '''<tt>new DirectoryStream()</tt>''' constructor initializes an object that allows you to enumerate the contents of a directory.

===== Usage =====

''dirstream_obj'' = '''new DirectoryStream'''(''dir_name'');

__TOC__

== API Information ==

=== Description ===

<tt>'''new DirectoryStream()'''</tt> constructs a Directory Stream object, which allows you to enumerate the contents of a directory. Directory streams only provide filenames; you must use a <tt>[[API:FileStream|FileStream]]</tt> to access the contents of a file.

<table>
<tr>
<td>''Note:''</td>
<td><tt>DirectoryStream</tt> objects are compatible with the JavaScript ''iterator protocol'', so you can use them in a <tt>[[API:from|from()]]</tt> query.</td>
</tr>
</table>

=== Parameters ===

<table>
<tr>
<td align=right width=100>'''''dir_name'''''</td>
<td>Path to the directory to be enumerated. Relative to the game manifest unless a SphereFS prefix is included.</td>
</tr>
</table>

=== Properties ===

<tt>
* [[API:DirectoryStream::fileCount|DirectoryStream::fileCount]]
* [[API:DirectoryStream::fileName|DirectoryStream::fileName]]
* [[API:DirectoryStream::position|DirectoryStream::position]]
</tt>

=== Methods ===

<tt>
* [[API:DirectoryStream::next|DirectoryStream::next()]]
* [[API:DirectoryStream::rewind|DirectoryStream::rewind()]]
</tt>

[[Category:Sphere 2 API]]

API:RNG

2017-08-12T04:08:56Z

Bruce Pascoe: Add some subheadings

{{DISPLAYTITLE:new RNG()}}

The '''<tt>RNG()</tt> constructor''' initializes a new instance of the pseudorandom number generator, seeded using the current time and date.

===== Usage =====

''rng_object'' = '''new RNG'''();

__TOC__

== API Information ==

=== Description ===

<tt>'''new RNG()'''</tt> initializes a new instance of the built-in pseudorandom number generator, seeded based on the current time and date. Unlike <tt>Math.random()</tt> which uses a very basic linear generator, Sphere uses the ''xoroshiro128+'' algorithm, providing games with a very high-quality source of pseudorandom numbers.

To control the initial state of the generator, use <tt>[[API:RNG.fromSeed|RNG.fromSeed()]]</tt> or <tt>[[API:RNG.fromState|RNG.fromState()]]</tt>.

=== Properties ===

<tt>
* [[API:RNG::state|RNG::state]]
</tt>

=== Methods ===

==== Static Methods ====

<tt>
* [[API:RNG.fromSeed|RNG.fromSeed()]]
* [[API:RNG.fromState|RNG.fromState()]]
</tt>

==== Instance Methods ====

<tt>
* [[API:RNG::next|RNG::next()]]
</tt>

[[Category:Sphere 2 API]]

API:RNG::next

2017-08-10T03:53:10Z

Bruce Pascoe: Improving headings some more

{{DISPLAYTITLE:RNG::next()}}

The <tt>'''RNG::next()'''</tt> method generates a random floating-point number in the range <tt>[0,1)</tt>.

=== Usage ===
''number'' = ''rng_object''.'''next'''();

__TOC__

== API Information ==

=== Description ===

<tt>'''RNG::next()'''</tt> generates a pseudorandom floating-point number greater than or equal to 0 but less than 1 and returns the value generated. The number generated is entirely determined by the current state of the <tt>RNG</tt> instance before the call (see <tt>[[API:RNG::state|RNG::state]]</tt>). After calling this function, the state is advanced so a different value will be generated next time. Therefore if you save the RNG's state before calling <tt>RNG.next()</tt>, then restore it afterwards and call <tt>RNG.next()</tt> again, the same value will be returned.

=== Parameters ===

This method has no parameters.

=== Return Value ===

A floating-point number in the range <tt>[0,1)</tt>.

== Examples ==

=== Shuffle an array ===

let items = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]

let rnGen = new RNG();
for (let i = items.length - 1; i > 0; --i) {
let j = Math.floor(rnGen.next() * (i + 1)); // discrete [0,i]
let orig_i = items[i];
items[i] = items[j];
items[j] = orig_i;
}

== See Also ==

<tt>
* [[API:RNG::state|RNG::state]]
</tt>

[[Category:Sphere 2 API]]

API:RNG::next

2017-08-09T15:45:10Z

Bruce Pascoe: Reorganize page, add sub-headings for organization, add description

{{DISPLAYTITLE:RNG::next()}}

The <tt>'''RNG::next()'''</tt> method returns a random floating-point number in the range <tt>[0,1)</tt>.

=== Usage ===
''number'' = ''rng_object''.'''next'''();

__TOC__

== API Information ==

=== Description ===

<tt>'''RNG::next()'''</tt> generates a pseudorandom floating-point value greater than or equal to 0 but less than 1 and returns the value so generated. The value this function returns is entirely determined by the current state of the <tt>RNG</tt> instance before the call (see <tt>[[API:RNG::state|RNG::state]]</tt>). After calling this function, the state is advanced so a different value will be generated next time. If you save the state before <tt>RNG.next()</tt>, then restore it afterwards and call <tt>RNG.next()</tt> again, the same value will be generated.

=== Examples ===

==== Shuffle items in an array ====

let items = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
let rnGen = new RNG();
for (let i = items.length - 1; i > 0; --i) {
let j = Math.floor(rnGen.next() * (i + 1)); // discrete [0,i]
let orig_i = items[i];
items[i] = items[j];
items[j] = orig_i;
}

[[Category:Sphere 2 API]]

API:RNG::state

2017-08-09T15:31:42Z

Bruce Pascoe: Created page with "{{DISPLAYTITLE:RNG::state}} '''<tt>RNG::state</tt>''' is an accessor property which allows you to get or set the current state of the random number generator instance. === U..."

{{DISPLAYTITLE:RNG::state}}

'''<tt>RNG::state</tt>''' is an accessor property which allows you to get or set the current state of the random number generator instance.

=== Usage ===

''current_state'' = ''rng_object''.'''state''';
''rng_object''.'''state''' = ''new_state'';

__TOC__

== API Information ==

=== Description ===

<tt>'''RNG::state'''</tt> is a 32-byte hexadecimal string that encodes the exact state of the <tt>RNG</tt> instance. If you save the value of this property to a file and load it in a later session, you can resume a random number sequence from where you left off. This is distinct from seeding (see <tt>[[API:RNG::fromSeed|RNG.fromSeed()]]</tt>), which starts a sequence from the beginning.

One use of this is to combat "save scumming", where a player saves a game before a randomly-determined event and reloads until they get a result they like (in Pokémon, for instance). If you save the state of the random number generator along with the other game data, the RNG becomes much harder to exploit since the same sequence of numbers will be generated again after the reload. This is also why Sphere allows you to construct multiple <tt>RNG</tt> instances: by having separate instances for different events and persisting their states across saves, you can combat RNG manipulation.

=== Examples ===

==== Saving ====

let save = {
name: heroGuy.name,
level: heroGuy.level,
rngState: myRNG.state,
// etc...
};
let saveData = JSON.stringify(save); // JSON encode
FS.writeFile('~/saveGame.json', saveData);

==== Loading ====

let saveData = FS.readFile('~/saveGame.json');
let save = JSON.parse(saveData); // JSON decode
heroGuy.name = save.name;
heroGuy.level = save.level;
myRNG = RNG.fromState(save.state); // or: myRNG.state = save.state;
// etc...

== See Also ==

<tt>
* [[API:RNG.fromSeed|RNG.fromSeed()]]
</tt>

[[Category:Sphere 2 API]]

API:RNG

2017-08-08T15:01:03Z

Bruce Pascoe: Improve documentation conventions a bit

{{DISPLAYTITLE:new RNG()}}

The '''<tt>RNG()</tt> constructor''' initializes a new instance of the pseudorandom number generator, seeded using the current time and date.

===== Usage =====

''rng_object'' = '''new RNG'''();

__TOC__

== Description ==

<tt>'''new RNG()'''</tt> initializes a new instance of the built-in pseudorandom number generator, seeded based on the current time and date. Unlike <tt>Math.random()</tt> which uses a very basic linear generator, Sphere uses the ''xoroshiro128+'' algorithm, providing games with a very high-quality source of pseudorandom numbers.

To control the initial state of the generator, use <tt>[[API:RNG.fromSeed|RNG.fromSeed()]]</tt> or <tt>[[API:RNG.fromState|RNG.fromState()]]</tt>.

== Properties ==

<tt>
* [[API:RNG::state|RNG::state]]
</tt>

== Methods ==

==== Static Methods ====

<tt>
* [[API:RNG.fromSeed|RNG.fromSeed()]]
* [[API:RNG.fromState|RNG.fromState()]]
</tt>

==== Instance Methods ====

<tt>
* [[API:RNG::next|RNG::next()]]
</tt>

[[Category:Sphere 2 API]]

API:RNG::next

2017-08-08T14:55:58Z

Bruce Pascoe: New page: RNG::next()

{{DISPLAYTITLE:RNG::next()}}

<tt>'''RNG::next()'''</tt> generates a pseudorandom floating-point number between 0.0 and 1.0 (exclusive).

==== Usage ====
''number'' = ''rng_object''.'''next'''();

__TOC__

== Example ==

/*
* Shuffle a list of numbers (Fisher-Yates)
*/

let numbers = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
let rnGen = new RNG();
for (let i = numbers.length - 1; i > 0; --i) {
let j = Math.floor(rnGen.next() * (i + 1)); // integer, [0,i]
let orig_i = numbers[i];
numbers[i] = numbers[j];
numbers[j] = orig_i;
}

[[Category:Sphere 2 API]]

API:RNG

2017-08-08T06:14:10Z

Bruce Pascoe:

{{DISPLAYTITLE:RNG Constructor}}

Constructs a new instance of the pseudorandom number generator.

===== Usage =====

rng_obj = '''new RNG'''();

__TOC__

== Description ==

The <tt>'''RNG'''</tt> constructor initializes a new instance of the Sphere random number generator, seeded based on the current time and date. Unlike <tt>Math.random()</tt> which uses a very basic linear generator, Sphere uses the ''xoroshiro128+'' algorithm, providing games with a very high-quality source of pseudorandom numbers.

To control the initial state of the generator, use <tt>[[API:RNG.fromSeed|RNG.fromSeed()]]</tt> or <tt>[[API:RNG.fromState|RNG.fromState()]]</tt>.

== Properties ==

<tt>
* [[API:RNG::state|RNG::state]]
</tt>

== Methods ==

==== Static Methods ====

<tt>
* [[API:RNG.fromSeed|RNG.fromSeed()]]
* [[API:RNG.fromState|RNG.fromState()]]
</tt>

==== Instance Methods ====

<tt>
* [[API:RNG::next|RNG::next()]]
</tt>

[[Category:Sphere 2 API]]

API:RNG

2017-08-08T06:12:58Z

Bruce Pascoe:

Constructs a new instance of the pseudorandom number generator.

===== Usage =====

rng_obj = '''new RNG'''();

__TOC__

== Description ==

The <tt>'''RNG'''</tt> constructor initializes a new instance of the Sphere random number generator, seeded based on the current time and date. Unlike <tt>Math.random()</tt> which uses a very basic linear generator, Sphere uses the ''xoroshiro128+'' algorithm, providing games with a very high-quality source of pseudorandom numbers.

To control the initial state of the generator, use <tt>[[API:RNG.fromSeed|RNG.fromSeed()]]</tt> or <tt>[[API:RNG.fromState|RNG.fromState()]]</tt>.

== Properties ==

<tt>
* [[API:RNG::state|RNG::state]]
</tt>

== Methods ==

==== Static Methods ====

<tt>
* [[API:RNG.fromSeed|RNG.fromSeed()]]
* [[API:RNG.fromState|RNG.fromState()]]
</tt>

==== Instance Methods ====

<tt>
* [[API:RNG::next|RNG::next()]]
</tt>

[[Category:Sphere 2 API]]

2015-06-20T04:55:10Z

Bruce Pascoe: /* Usage */

Returns a Sphere [[API:Color|Color]] Object, to be used in color masks or drawing primitives.

==Usage==

<center>'''Sphere 1.0 API'''</center>
{{Usage|func=CreateColor|params=r, g, b, a}}
<center>'''Sphere 2.0 API'''</center>
{{Usage|func=new Color|params=r, g, b, a}}

* '''r''' the red component
* '''g''' the green component
* '''b''' the blue component
* '''a''' the alpha component

==Notes==

The alpha component is optional. By default it's complete opaque (255).

==Examples==

Create some colors:

<syntaxhighlight>
var Red = CreateColor(255, 0 , 0);
var Green = CreateColor(0 , 255, 0);
var Yellow = CreateColor(255, 255, 0);

var TransparentRed = CreateColor(255, 0, 0, 125);
</syntaxhighlight>

==See also==

* Sphere [[API:Color|Color]] Object
* [[API:Line|Line]](x1, x2, y1, y2, color)
* [[API:Point|Point]](x, y, color)
* [[API:Rectangle|Rectangle]](x, y, width, height, color)
* [[API:Image/blitMask|Image.blitMask]](x, y, color)
* [[API:FlipScreen|FlipScreen]]()

{{API:Color/navbox}}

MiniSphere

2015-06-13T03:05:50Z

Bruce Pascoe:

MiniSphere

2015-06-10T06:47:00Z

Bruce Pascoe:

MiniSphere

2015-06-10T06:46:23Z

Bruce Pascoe:

[http://forums.spheredev.org/index.php/topic,1215.0.html '''minisphere'''] is a modern replacement for the aging [[Sphere|Sphere 1.5]] engine. It is not a fork of the original engine's codebase; it is a completely new implementation written from the ground up in C and is based on [http://alleg.sourceforge.net/ Allegro] and [http://duktape.org/ Duktape] and includes support for modern features such as OpenGL shaders and CommonJS modules. The vast majority of the Sphere 1.5 JavaScript API is also available for use in minisphere, with only a few functions missing from the implementation. A complete implementation of the Sphere 1.5 map engine is also included and built in.

The minisphere engine is available in both x86 (32-bit) and x64 (64-bit) variants, the latter of which is recommended as it typically provides better performance. The engine is tiny, requiring only 1.7 MB for the 64-bit engine and the official Windows build is completely self-contained in a single executable. As it is coded in C, it is also very portable and has been successfully compiled on both Linux and OS X platforms.

As of this writing (June 10, 2015), there is not yet an official site on the Web for minisphere, but the engine is available for download and discussion on the Spherical forums [http://forums.spheredev.org/index.php/topic,1215.0.html here]. The current official release is '''minisphere 1.2.3'''.

{{DISPLAYTITLE:minisphere}}

MiniSphere

2015-06-10T06:43:17Z

Bruce Pascoe:

[http://forums.spheredev.org/index.php/topic,1215.0.html '''minisphere'''] is a modern replacement for the aging [[Sphere 1.5]] engine. It is not a fork of the original engine's codebase; it is a completely new implementation written from the ground up in C and is based on [http://alleg.sourceforge.net/ Allegro] and [http://duktape.org/ Duktape] and includes support for modern features such as OpenGL shaders and CommonJS modules. The vast majority of the Sphere 1.5 JavaScript API is also available for use in minisphere, with only a few functions missing from the implementation. A complete implementation of the Sphere 1.5 map engine is also included and built in.

The minisphere engine is available in both x86 (32-bit) and x64 (64-bit) variants, the latter of which is recommended as it typically provides better performance. The engine is tiny, requiring only 1.7 MB for the 64-bit engine and the official Windows build is completely self-contained in a single executable. As it is coded in C, it is also very portable and has been successfully compiled on both Linux and OS X platforms.

As of this writing (June 10, 2015), there is not yet an official site on the Web for minisphere, but the engine is available for download and discussion on the Spherical forums [http://forums.spheredev.org/index.php/topic,1215.0.html here]. The current official release is '''minisphere 1.2.3'''.

{{DISPLAYTITLE:minisphere}}