-
Notifications
You must be signed in to change notification settings - Fork 4
/
docs.html
368 lines (323 loc) · 10.2 KB
/
docs.html
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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
<!doctype html>
<html>
<head>
<meta charset="utf-8"/>
<title>DRAFT Gladius Status Board</title>
<link rel="stylesheet" href="css/screen.css"/>
<link rel="stylesheet" href="css/gladiusjs.css"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<!-- Adding "maximum-scale=1" fixes the Mobile Safari auto-zoom bug: http://filamentgroup.com/examples/iosScaleBug/ -->
</head>
<body>
<header id="masthead">
<nav id="nav-main" role="navigation">
<ul>
<li>
<a href="index.html">Home</a>
</li>
<li>
<a href="about.html">About</a>
</li>
<li>
<a href="features.html">Features</a>
</li>
<li>
<a href="roadmap.html">Roadmap</a>
</li>
<li>
<b>Docs</b>
</li>
<li>
<a href="https://wiki.mozilla.org/Gladius">Community</a>
</li>
</ul>
</nav>
</header>
<!-- XXX link people to Mozillians -->
<h4>
<font color="red"><b>DRAFT</b></font> Docs
</h4>
<h2>
Getting started
</h2>
In order to start using gladius, you will need to add a new script tag to your
web page:
<div style="background-color:white;">
<pre>
<script src="gladius.js"></script>
</pre>
</div>
We should also make a canvas on the page:
<div style="background-color:white;">
<pre>
<canvas id="test-canvas" width="320" height="240">
</pre>
</div>
Once this script is loaded you will have access to the gladius object. Now you
should create an engine instance:
<div style="background-color:white;">
<pre>
gladius.create(
{
services: {
graphics: {
src: 'graphics/service',
options: {
canvas: document.getElementById( "test-canvas" )
}
}
}
},
game
);
</pre>
</div>
Engine instances are constructed asynchronously and your callback, game, will
be invoked, with the engine instance as a parameter, when the engine is ready.
Your game callback function should look like this:
<div style="background-color:white;">
<pre>
function game( engine ) {
...
}
</pre>
</div>
<h2>
Engine instance
</h2>
Once you have access to an engine instance you can build the pieces of your
simulation. Start by creating a new space:
<div style="background-color:white;">
<pre>
var space = new engine.core.Space();
</pre>
</div>
A space manages a collection of entities. Entities represent game objects in
your simulation. Let's create one (a cube) and add it to the space:
<div style="background-color:white;">
<pre>
var cube = new engine.core.Entity({ name: 'MyCube' });
space.add( cube );
</pre>
</div>
Every entity may have a name that allows it to be found in the space. An entity
isn't very interesting unless it has some components. Components carry data and
logic for a particular aspect of a simulation, like graphics or physics. Let's
add some graphics to our cube.
<h2>
Loading resources
</h2>
We will need a mesh and a material. The engine instance has an API for
loading resources, and we can use it to produce a mesh and a material using
an external script:
<div style="background-color:white;">
<pre>
var resources = {};
engine.core.resource.get(
[
{
load: engine.core.resource.proceduralLoad,
url: 'procedural-mesh.js',
type: engine.graphics.resource.Mesh,
onsuccess: function( mesh ) {
resources.mesh = mesh;
},
onfailure: function( error ) {
}
},
{
load: engine.core.resource.proceduralLoad,
url: 'procedural-material.js',
type: engine.graphics.resource.Material,
onsuccess: function( material ) {
resources.material = material;
},
onfailure: function( error ) {
}
}
],
{
oncomplete: run
}
);
function run() {
...
};
</pre>
</div>
The engine's resource loader allows your simulation to fetch a collection of
resources and execute a callback for each load, as well as a final callback
when all the loads have completed. The load parameter specifies the method for
fetching the raw data. In this case we will procedurally generate the data. The
url parameter is passed to the load method. For this method the url is the
script we will run. The type parameter gives a constructor to invoke with the
raw data. In this case we are making a mesh and a material, so those are the
constructors we give.
<p>
Finally, onsuccess is invoked when the whole process is complete and it receives
a resource instance of the expected type. In the code above, we capture the
instances so we can use them later. The last callback, oncomplete, is invoked
when all the resources have been loaded. We can call run() when all our
resources have loaded and finish setting up the simulation.
<h2>
Graphics
</h2>
In order to add graphics to the cube entity, we will need to add a transform
component and a model component. The transform holds data about the cube's
position, rotation and scale. The model will store the mesh and material we
want to use.
<div style="background-color:white;">
<pre>
cube.add( new engine.core.component.Transform({
rotation: math.Vector3( 1, 2, 3 )
});
</pre>
</div>
The code above will create a new transform with an initial rotation of [1, 2, 3]
radians. Now we can add a new model to the entity:
<div style="background-color:white;">
<pre>
cube.add( new engine.graphics.component.Model({
mesh: resources.mesh,
material: resources.material
});
</pre>
</div>
We need to add a camera to the space in order to render the simulation. We need
a second entity to represent the camera:
<div style="background-color:white;">
<pre>
var camera = new engine.core.Entity({
name: 'Mycamera',
components: [
new engine.core.component.Transform({
position: math.Vector3( 0, 0, 2 )
}),
new engine.graphics.component.Camera({
active: true,
width: 320,
height: 240
}),
new engine.graphics.component.Light()
]
});
space.add( camera );
camera.target = cube.find( 'Transform' ).position;
</pre>
</div>
Notice that the camera also requires a transform. The width and height
parameters should match the dimensions of the test canvas we created earlier.
<p>
Finally, notice that we offset the camera from the origin by setting its
position, and we set its target to point at the position of the cube.
<h2>
Putting it all together
</h2>
Now that we've set up our simulation, we need to start the engine:
<div style="background-color:white;">
<pre>
engine.run();
</pre>
</div>
Doing this will start the scheduler, which is responsible for running scheduled
tasks each frame in the correct order. In this simulation, the graphics service
has a task that runs and is responsible for rendering the simulation to the
canvas. A more complicated simulation would have tasks to handle input, physics,
sound, and other simulation elements.
<p>
Below is the entire program:
<div style="background-color:white;">
<pre>
<!DOCTYPE html>
<html>
<head>
<script src='gladius.js'>
</script>
<script>
document.addEventListener("DOMContentLoaded", function( event ) {
function game( engine ) {
var math = engine.math;
var space = new engine.core.Space();
var cube = new engine.core.Entity({ name: 'MyCube' });
space.add( cube );
var resources = {};
engine.core.resource.get(
[
{
load: engine.core.resource.proceduralLoad,
url: 'procedural-mesh.js',
type: engine.graphics.resource.Mesh,
onsuccess: function( mesh ) {
resources.mesh = mesh;
},
onfailure: function( error ) {
}
},
{
load: engine.core.resource.proceduralLoad,
url: 'procedural-material.js',
type: engine.graphics.resource.Material,
onsuccess: function( material ) {
resources.material = material;
},
onfailure: function( error ) {
}
}
],
{
oncomplete: run
}
);
function run() {
cube.add( new engine.core.component.Transform({
rotation: math.Vector3( 1, 2, 3 )
}));
cube.add( new engine.graphics.component.Model({
mesh: resources.mesh,
material: resources.material
}));
var camera = new engine.core.Entity({
name: 'Mycamera',
components: [
new engine.core.component.Transform({
position: math.Vector3( 0, 0, 2 )
}),
new engine.graphics.component.Camera({
active: true,
width: 320,
height: 240
}),
new engine.graphics.component.Light()
]
});
space.add( camera );
camera.target = cube.find( 'Transform' ).position;
engine.run();
};
};
var testCanvas = document.getElementById( "test-canvas" );
gladius.create(
{
services: {
graphics: {
src: 'graphics/service',
options: {
canvas: testCanvas
}
}
}
},
game
);
});
</script>
</head>
<body>
<canvas id="test-canvas" width="320" height="240">
</canvas>
</body>
</html>
</pre>
</div>
</body>
</html>