|
|
| (11 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 === |
| − | "version": 2,
| |
| − | "name": "Spectacles: Bruce's Story",
| |
| − | "author": "Fat Cerberus",
| |
| − | "summary": "Follow Scott Starcross in his quest to stop the Primus.",
| |
| − | "resolution": "320x240",
| |
| − | "main": "main.js"
| |
| − | }</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>.
| |
| | | | |
| − | "version" [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>
| |
| − | "author" [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: |
| − | "main" [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 "main" field is present, the game will not start.</pre>
| |
| − | "name" [default: "Untitled"]
| |
| | | | |
| − | <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>
| |
| − | "resolution" [required]
| |
| | | | |
| − | <pre>The default screen resolution of the game, expressed as a string of the
| + | ==== In a Cellscript ==== |
| − | form "WxH", specifying the number of pixels across and down. For example,
| |
| − | 720p resolution would be expressed as "1280x720".
| |
| | | | |
| − | Note: The resolution can be changed at runtime by calling screen.resize().</pre>
| + | import { assert, transpile } from 'cell-runtime'; |
| − | "summary" [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. "@/../maggie.fat", will be met with a sandbox violation error.
| + | * [[API:Image|new Image()]] |
| | + | ** [[API:Image::blitTo|Image::blitTo()]] |
| | + | </tt> |
| | | | |
| − | == Importing == | + | === <tt>logger</tt> Module === |
| | | | |
| − | * [[API:Require|require]]('module') | + | <tt> |
| − | * [[API:Import|import]] { FunctionName } from 'module' | + | * [[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 "miniSphere".</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. "X.X.X".</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 && 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 "a" (or "A" 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 "XInput Joystick <n>"</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. "chartreuse"), or an ARGB
| |
| − | signature such as "#800000FF". 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 ("unable to create
| |
| − | hardware voice").</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>
| |
