cellscript-api.txt

Cellscript API Reference
========================

Cell is a scriptable build system and compiler for Sphere games. Like Sphere
itself, it uses JavaScript to control the build process.  This file documents
the public API used to write build scripts.


SphereFS File System
--------------------

Cell, like miniSphere, uses the SphereFS standard for file paths.  Under
SphereFS, when a relative path is used in an API call, it will usually be
resolved relative to the entrypoint (in Cell, the location of Cellscript.js).
To load files from a different location, you can use one of the SphereFS
prefixes:

    @/: The root of the game package being compiled.
    $/: The source directory, i.e. the directory containing the Cellscript.
    ~/: When used in a Sphere game, this specifies the current user's save data
        directory.  In Cell, using this prefix is a sandboxing violation.
    #/: The Sphere system directory.  This contains assets included with the
        engine.  In most cases this directory is read-only.  Build scripts
        should NOT try to write anything here as doing so can damage the host
        miniSphere installation.

As an example, the following will create a FileStream to write the file
`EatyPig.bin` in the root of the game package:

    var file = new FileStream("@/EatyPig.bin", FileOp.Write);

Absolute paths are NOT allowed, and any attempt to circumvent the sandbox, e.g.
"@/../maggie.fat", will be met with a sandbox violation error.


Sphere v2 API
-------------

To make things easier for Sphere v2 developers, Cell provides a subset of the
Sphere v2 API and standard library for use in Cellscripts.  Specifically, the
following are provided:

    - Text Encoding API (`TextEncoder`, `TextDecoder`)
    - File System API (`FS`, 'DirectoryStream', `FileStream`)
    - Random Number Generator API (`RNG`)
    - Data Compression API (`Z`)

    - Sphere Runtime modules:
        - `assert` module
        - `dataStream` module
        - `delegate` module
        - `from` module
        - `logger` module
        - `random` module
        - `test` module
        - `xml` module

Refer to `sphere2-api.txt` and/or `miniRT-api.txt` for more information on how
to use those APIs.


Core Cellscript API
-------------------

The functions and properties below are available for use at all times, by all
Cellscripts and modules.  No `require()` or `import` statements are necessary
to use them.

Sphere.Compiler [read-only]

    A string specifying the name and version number of the compiler.  The
    version number takes the form X.Y.Z, where X is the major version, Y is the
    minor version, and Z is the patch level.

Sphere.Version [read-only]

    An integer specifying which version of the Cellscript API is supported by
    the compiler (e.g., 2).

Sphere.Game [non-replaceable]

    An object whose properties will be written to the game's JSON manifest at
    the end of the build.  For example, `Sphere.Game.name` is the game title.
    If you need to set multiple fields at once, use `Object.assign()`.

    Note: You are free to do as you please with this object, but keep in mind
          that only JSON-compatible values will actually be written out to
          `game.json`.

error(message);

    Produces an error.  Errors generated during Cellscript evaluation will
    prevent any targets from being built, while errors generated during a build
    will not (Cell tries to build as many targets as possible).  In both cases
    the build will ultimately fail and a game manifest will not be generated.

files(pattern[, recursive]);

    Constructs a target for every file matching the specified pattern.  File
    targets are unique: They have no sources, and are always considered to be
    up to date.

    `pattern` is a wildcard (e.g. "*.png") combined with an optional SphereFS
    path specifying the directory to be searched.  If 'recursive' is true,
    subdirectories are searched as well.

install(directory, sources);

    Copies all specified Targets into a given directory at build time.  To copy
    existing files, you can use a files() builder to populate `sources`. (see
    above).

warn(message);

    Produces a warning.  Warnings will be reported to the user but will not
    prevent a successful build.

new Image(fileName);

    Constructs a new Image object from the image file named by `fileName`.  The
    `Image` class allows you to work with images directly at the pixel level.

    Note: Cell currently only supports loading PNG images.

Image#bitmap [non-replaceable]

    A Uint8Array containing the pixel data for the image.  The pixel format is
    always RGBA and pixels are encoded from left-to-right, top-to-bottom.  Each
    four bytes in the array represent a single pixel of the image.

Image#width [read-only]
Image#height [read-only]

    The width and height of the image, in pixels.

Image#saveAs(fileName);

    Writes the image out to a PNG file named `fileName`.  Be careful: if a file
    by the specified name already exists, it will be overwritten!

Image#slice(x, y, width, height);

    Returns a new Image object from the specified portion of this image.

Target#fileName [read-only]

    Gets the full SphereFS path of the output file represented by this Target.

Target#name [read-only]

    Gets the name of this Target.  Usually this is just the output filename
    without any path information; however, targets constructed by files() may
    include a relative path to make it possible to reconstruct the original
    directory structure elsewhere.

new Tool(buildFunc[, status_text]);

    Constructs a Tool which can be used to build custom targets.  For example,
    you might create a Tool to build minified scripts or compress files.

    For each target built by the Tool, `buildFunc` is called and provided with
    the target filename as well as an array of filenames for the sources needed
    to build it.  The function is expected to create the target file or, if
    it already exists, to update its modification date.  If it doesn't, a build
    warning or error will result.

    `buildFunc` has the signature:
        function(outFileName, inFileNames)

    `status_text` is how Cell will describe the build step, e.g. "compiling" or
    "compressing".  If the status text is omitted, "building" is the default.

Tool#stage(filename, sources);

    Instructs Cell to build `filename` using this Tool.  Returns a Target
    object representing the target file.