-
Notifications
You must be signed in to change notification settings - Fork 15
/
cellscript-api.txt
176 lines (121 loc) · 6.34 KB
/
cellscript-api.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
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.