@guinetik/gcanvas 1.0.1 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/demos/coordinates.html +698 -0
- package/demos/cube3d.html +23 -0
- package/demos/demos.css +17 -3
- package/demos/dino.html +42 -0
- package/demos/gameobjects.html +626 -0
- package/demos/index.html +17 -7
- package/demos/js/coordinates.js +840 -0
- package/demos/js/cube3d.js +789 -0
- package/demos/js/dino.js +1420 -0
- package/demos/js/gameobjects.js +176 -0
- package/demos/js/plane3d.js +256 -0
- package/demos/js/platformer.js +1579 -0
- package/demos/js/sphere3d.js +229 -0
- package/demos/js/sprite.js +473 -0
- package/demos/js/tde/accretiondisk.js +3 -3
- package/demos/js/tde/tidalstream.js +2 -2
- package/demos/plane3d.html +24 -0
- package/demos/platformer.html +43 -0
- package/demos/sphere3d.html +24 -0
- package/demos/sprite.html +18 -0
- package/docs/concepts/coordinate-system.md +384 -0
- package/docs/concepts/shapes-vs-gameobjects.md +187 -0
- package/docs/fluid-dynamics.md +99 -97
- package/package.json +1 -1
- package/src/game/game.js +11 -5
- package/src/game/objects/index.js +3 -0
- package/src/game/objects/platformer-scene.js +411 -0
- package/src/game/objects/scene.js +14 -0
- package/src/game/objects/sprite.js +529 -0
- package/src/game/pipeline.js +20 -16
- package/src/game/ui/theme.js +123 -121
- package/src/io/input.js +75 -45
- package/src/io/mouse.js +44 -19
- package/src/io/touch.js +35 -12
- package/src/shapes/cube3d.js +599 -0
- package/src/shapes/index.js +2 -0
- package/src/shapes/plane3d.js +687 -0
- package/src/shapes/sphere3d.js +75 -6
- package/src/util/camera2d.js +315 -0
- package/src/util/index.js +1 -0
- package/src/webgl/shaders/plane-shaders.js +332 -0
- package/src/webgl/shaders/sphere-shaders.js +4 -2
|
@@ -0,0 +1,698 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
|
|
4
|
+
<head>
|
|
5
|
+
<meta charset="UTF-8">
|
|
6
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
7
|
+
<title>GCanvas Coordinate System Documentation</title>
|
|
8
|
+
<!-- Prism.js - base theme then override -->
|
|
9
|
+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-okaidia.css">
|
|
10
|
+
<style>
|
|
11
|
+
/* Terminal-style Prism overrides */
|
|
12
|
+
code[class*="language-"],
|
|
13
|
+
pre[class*="language-"] {
|
|
14
|
+
color: #ccc;
|
|
15
|
+
background: #0a0a0a;
|
|
16
|
+
text-shadow: none;
|
|
17
|
+
}
|
|
18
|
+
pre[class*="language-"] {
|
|
19
|
+
background: #0a0a0a;
|
|
20
|
+
border: 1px solid #1a1a1a;
|
|
21
|
+
}
|
|
22
|
+
.token.comment,
|
|
23
|
+
.token.prolog,
|
|
24
|
+
.token.doctype,
|
|
25
|
+
.token.cdata { color: #555; }
|
|
26
|
+
.token.punctuation { color: #888; }
|
|
27
|
+
.token.property,
|
|
28
|
+
.token.tag,
|
|
29
|
+
.token.constant,
|
|
30
|
+
.token.symbol,
|
|
31
|
+
.token.deleted { color: #0f0; }
|
|
32
|
+
.token.boolean,
|
|
33
|
+
.token.number { color: #0ff; }
|
|
34
|
+
.token.selector,
|
|
35
|
+
.token.attr-name,
|
|
36
|
+
.token.string,
|
|
37
|
+
.token.char,
|
|
38
|
+
.token.builtin,
|
|
39
|
+
.token.inserted { color: #7fff7f; }
|
|
40
|
+
.token.operator,
|
|
41
|
+
.token.entity,
|
|
42
|
+
.token.url,
|
|
43
|
+
.language-css .token.string,
|
|
44
|
+
.style .token.string,
|
|
45
|
+
.token.variable { color: #ccc; }
|
|
46
|
+
.token.atrule,
|
|
47
|
+
.token.attr-value,
|
|
48
|
+
.token.function,
|
|
49
|
+
.token.class-name { color: #0f0; }
|
|
50
|
+
.token.keyword { color: #0f0; font-weight: bold; }
|
|
51
|
+
.token.regex,
|
|
52
|
+
.token.important { color: #fd8; }
|
|
53
|
+
</style>
|
|
54
|
+
<style>
|
|
55
|
+
*, *::before, *::after {
|
|
56
|
+
box-sizing: border-box;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
html, body {
|
|
60
|
+
overflow-x: hidden;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
body {
|
|
64
|
+
font-family: 'Courier New', 'Consolas', monospace;
|
|
65
|
+
line-height: 1.6;
|
|
66
|
+
color: #333;
|
|
67
|
+
max-width: 1200px;
|
|
68
|
+
margin: 0 auto;
|
|
69
|
+
padding: 20px;
|
|
70
|
+
background-color: #000;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
header {
|
|
74
|
+
margin-bottom: 40px;
|
|
75
|
+
padding: 20px;
|
|
76
|
+
border-bottom: 2px solid #0f0;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
h1 {
|
|
80
|
+
font-size: 2.5em;
|
|
81
|
+
margin-bottom: 10px;
|
|
82
|
+
color: #0f0;
|
|
83
|
+
font-family: 'Courier New', monospace;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
h2 {
|
|
87
|
+
font-size: 1.8em;
|
|
88
|
+
margin-top: 40px;
|
|
89
|
+
margin-bottom: 20px;
|
|
90
|
+
padding-bottom: 10px;
|
|
91
|
+
border-bottom: 2px solid #0f0;
|
|
92
|
+
color: #0f0;
|
|
93
|
+
font-family: 'Courier New', monospace;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
h3 {
|
|
97
|
+
font-size: 1.4em;
|
|
98
|
+
margin-top: 30px;
|
|
99
|
+
color: #0f0;
|
|
100
|
+
font-family: 'Courier New', monospace;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
h4 {
|
|
104
|
+
font-size: 1.2em;
|
|
105
|
+
margin-top: 20px;
|
|
106
|
+
color: #0f0;
|
|
107
|
+
font-family: 'Courier New', monospace;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
p {
|
|
111
|
+
margin-bottom: 15px;
|
|
112
|
+
color: #aaa;
|
|
113
|
+
font-family: 'Courier New', monospace;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
pre {
|
|
117
|
+
background-color: #0a0a0a;
|
|
118
|
+
color: #ccc;
|
|
119
|
+
padding: 15px;
|
|
120
|
+
border: 1px solid #1a1a1a;
|
|
121
|
+
overflow-x: auto;
|
|
122
|
+
margin: 15px 0;
|
|
123
|
+
font-family: 'Courier New', monospace;
|
|
124
|
+
max-width: 100%;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
code {
|
|
128
|
+
font-family: 'Courier New', monospace;
|
|
129
|
+
background-color: #111;
|
|
130
|
+
color: #0f0;
|
|
131
|
+
padding: 2px 6px;
|
|
132
|
+
border: none;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
pre code {
|
|
136
|
+
background-color: transparent;
|
|
137
|
+
color: #ccc;
|
|
138
|
+
padding: 0;
|
|
139
|
+
border: none;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
.feature-list {
|
|
143
|
+
list-style-type: none;
|
|
144
|
+
padding-left: 0;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
.feature-list li {
|
|
148
|
+
position: relative;
|
|
149
|
+
padding-left: 30px;
|
|
150
|
+
margin-bottom: 10px;
|
|
151
|
+
color: #aaa;
|
|
152
|
+
font-family: 'Courier New', monospace;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
.feature-list li:before {
|
|
156
|
+
content: "> ";
|
|
157
|
+
color: #0f0;
|
|
158
|
+
position: absolute;
|
|
159
|
+
left: 0;
|
|
160
|
+
top: 0;
|
|
161
|
+
font-weight: bold;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
.note {
|
|
165
|
+
background-color: #0a1a0a;
|
|
166
|
+
padding: 15px;
|
|
167
|
+
border-left: 2px solid #0f0;
|
|
168
|
+
margin: 20px 0;
|
|
169
|
+
color: #7fff7f;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
.example {
|
|
173
|
+
background-color: #0a0a0a;
|
|
174
|
+
border: 1px solid #1a1a1a;
|
|
175
|
+
margin: 20px 0;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
.example-title {
|
|
179
|
+
font-weight: bold;
|
|
180
|
+
color: #0f0;
|
|
181
|
+
background-color: #050505;
|
|
182
|
+
padding: 10px 15px;
|
|
183
|
+
margin: 0;
|
|
184
|
+
border-bottom: 1px solid #1a1a1a;
|
|
185
|
+
font-family: 'Courier New', monospace;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
.example-code {
|
|
189
|
+
padding: 15px;
|
|
190
|
+
margin: 0;
|
|
191
|
+
border-radius: 0;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
.canvas-demo {
|
|
195
|
+
width: 100%;
|
|
196
|
+
height: 250px;
|
|
197
|
+
background-color: #050505;
|
|
198
|
+
border-top: 1px solid #1a1a1a;
|
|
199
|
+
position: relative;
|
|
200
|
+
overflow: hidden;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
.canvas-demo canvas {
|
|
204
|
+
display: block;
|
|
205
|
+
width: 100%;
|
|
206
|
+
height: 100%;
|
|
207
|
+
border: 1px solid #1a1a1a;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
.canvas-label {
|
|
211
|
+
position: absolute;
|
|
212
|
+
bottom: 10px;
|
|
213
|
+
right: 10px;
|
|
214
|
+
background-color: rgba(0, 0, 0, 0.8);
|
|
215
|
+
color: #0f0;
|
|
216
|
+
padding: 4px 8px;
|
|
217
|
+
font-size: 12px;
|
|
218
|
+
font-family: 'Courier New', monospace;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
table {
|
|
222
|
+
width: 100%;
|
|
223
|
+
border-collapse: collapse;
|
|
224
|
+
margin: 20px 0;
|
|
225
|
+
font-family: 'Courier New', monospace;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
th, td {
|
|
229
|
+
border: 1px solid #1a1a1a;
|
|
230
|
+
padding: 10px 15px;
|
|
231
|
+
text-align: left;
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
th {
|
|
235
|
+
background-color: #0a1a0a;
|
|
236
|
+
color: #0f0;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
td {
|
|
240
|
+
background-color: #0a0a0a;
|
|
241
|
+
color: #aaa;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
td code {
|
|
245
|
+
background-color: #111;
|
|
246
|
+
padding: 2px 6px;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
.tldr-box {
|
|
250
|
+
background-color: #0a1a0a;
|
|
251
|
+
border: 1px solid #0f0;
|
|
252
|
+
padding: 20px;
|
|
253
|
+
margin: 20px 0;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
.tldr-box h3 {
|
|
257
|
+
margin-top: 0;
|
|
258
|
+
color: #0f0;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
.ascii-diagram {
|
|
262
|
+
background-color: #0a0a0a;
|
|
263
|
+
border: 1px solid #1a1a1a;
|
|
264
|
+
padding: 20px;
|
|
265
|
+
margin: 20px 0;
|
|
266
|
+
overflow-x: auto;
|
|
267
|
+
font-family: 'Courier New', monospace;
|
|
268
|
+
color: #0f0;
|
|
269
|
+
line-height: 1.4;
|
|
270
|
+
white-space: pre;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
@media (max-width: 768px) {
|
|
274
|
+
body {
|
|
275
|
+
padding: 10px;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
h1 {
|
|
279
|
+
font-size: 1.8em;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
h2 {
|
|
283
|
+
font-size: 1.4em;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
.canvas-demo {
|
|
287
|
+
height: 200px;
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
</style>
|
|
291
|
+
</head>
|
|
292
|
+
|
|
293
|
+
<body>
|
|
294
|
+
<header>
|
|
295
|
+
<h1>GCanvas Coordinate System</h1>
|
|
296
|
+
<p>Understanding how positioning works throughout the library</p>
|
|
297
|
+
</header>
|
|
298
|
+
|
|
299
|
+
<section>
|
|
300
|
+
<h2>Overview</h2>
|
|
301
|
+
<p>
|
|
302
|
+
GCanvas uses a <strong>center-based coordinate system</strong> where <code>x</code> and <code>y</code>
|
|
303
|
+
refer to an object's center point, not its top-left corner. This makes rotation and scaling more
|
|
304
|
+
intuitive since transforms happen around the object's center.
|
|
305
|
+
</p>
|
|
306
|
+
|
|
307
|
+
<div class="tldr-box">
|
|
308
|
+
<h3>TL;DR - Quick Reference</h3>
|
|
309
|
+
<table>
|
|
310
|
+
<tr>
|
|
311
|
+
<th>Situation</th>
|
|
312
|
+
<th>How It Works</th>
|
|
313
|
+
</tr>
|
|
314
|
+
<tr>
|
|
315
|
+
<td>Object at <code>(100, 100)</code></td>
|
|
316
|
+
<td>Center is at screen position (100, 100)</td>
|
|
317
|
+
</tr>
|
|
318
|
+
<tr>
|
|
319
|
+
<td>Child at <code>(10, 20)</code> in Scene at <code>(100, 100)</code></td>
|
|
320
|
+
<td>Child center is at screen (110, 120)</td>
|
|
321
|
+
</tr>
|
|
322
|
+
<tr>
|
|
323
|
+
<td>Camera3D <code>project()</code> returns <code>(0, 0)</code></td>
|
|
324
|
+
<td>Object is at the center of the 3D view</td>
|
|
325
|
+
</tr>
|
|
326
|
+
<tr>
|
|
327
|
+
<td>Scene3D at <code>(width/2, height/2)</code></td>
|
|
328
|
+
<td>3D origin appears at canvas center</td>
|
|
329
|
+
</tr>
|
|
330
|
+
</table>
|
|
331
|
+
</div>
|
|
332
|
+
</section>
|
|
333
|
+
|
|
334
|
+
<section>
|
|
335
|
+
<h2>1. Center-Based Positioning</h2>
|
|
336
|
+
<p>
|
|
337
|
+
Unlike many graphics libraries that use top-left corners, GCanvas positions objects by their
|
|
338
|
+
<strong>center point</strong>. When you set <code>x: 100, y: 100</code>, the object's center
|
|
339
|
+
is at that position.
|
|
340
|
+
</p>
|
|
341
|
+
|
|
342
|
+
<h4>Why Center-Based?</h4>
|
|
343
|
+
<ul class="feature-list">
|
|
344
|
+
<li>Rotation happens around the center naturally</li>
|
|
345
|
+
<li>Scaling expands/contracts from the center</li>
|
|
346
|
+
<li>No need to manually adjust pivot points</li>
|
|
347
|
+
<li>More intuitive for game development</li>
|
|
348
|
+
</ul>
|
|
349
|
+
|
|
350
|
+
<div class="example">
|
|
351
|
+
<div class="example-title">Interactive Demo: Center vs Bounds</div>
|
|
352
|
+
<pre><code class="language-javascript">// This circle's CENTER is at (100, 100)
|
|
353
|
+
const circle = new Circle(50, { x: 100, y: 100, color: "#0f0" });
|
|
354
|
+
|
|
355
|
+
// The circle extends from:
|
|
356
|
+
// - Left edge: 50 (100 - radius)
|
|
357
|
+
// - Right edge: 150 (100 + radius)
|
|
358
|
+
// - Top edge: 50 (100 - radius)
|
|
359
|
+
// - Bottom edge: 150 (100 + radius)</code></pre>
|
|
360
|
+
<div class="canvas-demo">
|
|
361
|
+
<canvas id="center-based-canvas"></canvas>
|
|
362
|
+
<div class="canvas-label">Drag to move - watch center point</div>
|
|
363
|
+
</div>
|
|
364
|
+
</div>
|
|
365
|
+
|
|
366
|
+
<table>
|
|
367
|
+
<tr>
|
|
368
|
+
<th>System</th>
|
|
369
|
+
<th><code>x: 100, y: 100</code> means...</th>
|
|
370
|
+
<th>Rotation pivot</th>
|
|
371
|
+
</tr>
|
|
372
|
+
<tr>
|
|
373
|
+
<td><strong>GCanvas (center)</strong></td>
|
|
374
|
+
<td>Center at (100, 100)</td>
|
|
375
|
+
<td>Around center</td>
|
|
376
|
+
</tr>
|
|
377
|
+
<tr>
|
|
378
|
+
<td>Top-left systems</td>
|
|
379
|
+
<td>Top-left at (100, 100)</td>
|
|
380
|
+
<td>Around top-left corner</td>
|
|
381
|
+
</tr>
|
|
382
|
+
</table>
|
|
383
|
+
</section>
|
|
384
|
+
|
|
385
|
+
<section>
|
|
386
|
+
<h2>2. Basic Positioning</h2>
|
|
387
|
+
<p>
|
|
388
|
+
When you add an object directly to the pipeline, its coordinates are <strong>absolute screen
|
|
389
|
+
coordinates</strong>. Canvas origin <code>(0, 0)</code> is the top-left corner.
|
|
390
|
+
</p>
|
|
391
|
+
|
|
392
|
+
<div class="example">
|
|
393
|
+
<div class="example-title">Interactive Demo: Screen Coordinates</div>
|
|
394
|
+
<pre><code class="language-javascript">// Circle centered at screen position (200, 150)
|
|
395
|
+
const circle = new Circle(30, { x: 200, y: 150, color: "#0ff" });
|
|
396
|
+
this.pipeline.add(circle);
|
|
397
|
+
|
|
398
|
+
// X increases going right
|
|
399
|
+
// Y increases going down</code></pre>
|
|
400
|
+
<div class="canvas-demo">
|
|
401
|
+
<canvas id="basic-position-canvas"></canvas>
|
|
402
|
+
<div class="canvas-label">Click anywhere to place shapes</div>
|
|
403
|
+
</div>
|
|
404
|
+
</div>
|
|
405
|
+
</section>
|
|
406
|
+
|
|
407
|
+
<section>
|
|
408
|
+
<h2>3. Parent-Child Relationships</h2>
|
|
409
|
+
<p>
|
|
410
|
+
When you add objects to a <strong>Scene</strong>, their coordinates become
|
|
411
|
+
<strong>relative to the parent's center</strong>. This is the key to understanding
|
|
412
|
+
hierarchical positioning.
|
|
413
|
+
</p>
|
|
414
|
+
|
|
415
|
+
<div class="ascii-diagram">
|
|
416
|
+
Canvas (0,0)────────────────────────────────►X
|
|
417
|
+
│
|
|
418
|
+
│ Scene at (200, 150)
|
|
419
|
+
│ ┌─────────────────────┐
|
|
420
|
+
│ │ Scene's local │
|
|
421
|
+
│ │ origin (0, 0) │
|
|
422
|
+
│ │ ●───────────┼──► Scene's X
|
|
423
|
+
│ │ │ │
|
|
424
|
+
│ │ │ Child at │
|
|
425
|
+
│ │ │ (50, 30) │
|
|
426
|
+
│ │ ▼ ◉ │
|
|
427
|
+
│ │ Scene's Y │
|
|
428
|
+
│ └─────────────────────┘
|
|
429
|
+
│
|
|
430
|
+
▼
|
|
431
|
+
Y
|
|
432
|
+
|
|
433
|
+
Child screen position = Scene position + Child local position
|
|
434
|
+
= (200, 150) + (50, 30)
|
|
435
|
+
= (250, 180)</div>
|
|
436
|
+
|
|
437
|
+
<div class="example">
|
|
438
|
+
<div class="example-title">Interactive Demo: Parent-Child Coordinates</div>
|
|
439
|
+
<pre><code class="language-javascript">// Scene centered at (200, 150)
|
|
440
|
+
const scene = new Scene(this, { x: 200, y: 150 });
|
|
441
|
+
|
|
442
|
+
// Child at (50, 30) relative to scene
|
|
443
|
+
const child = new Circle(20, { x: 50, y: 30, color: "#0f0" });
|
|
444
|
+
scene.add(child);
|
|
445
|
+
|
|
446
|
+
// Child's screen position: (200 + 50, 150 + 30) = (250, 180)</code></pre>
|
|
447
|
+
<div class="canvas-demo">
|
|
448
|
+
<canvas id="parent-child-canvas"></canvas>
|
|
449
|
+
<div class="canvas-label">Drag the scene (green box) - children follow</div>
|
|
450
|
+
</div>
|
|
451
|
+
</div>
|
|
452
|
+
|
|
453
|
+
<h3>Nested Scenes</h3>
|
|
454
|
+
<p>Coordinates stack through the hierarchy:</p>
|
|
455
|
+
|
|
456
|
+
<div class="example">
|
|
457
|
+
<div class="example-title">Interactive Demo: Nested Hierarchy</div>
|
|
458
|
+
<pre><code class="language-javascript">const outer = new Scene(this, { x: 100, y: 100 });
|
|
459
|
+
const inner = new Scene(this, { x: 50, y: 50 });
|
|
460
|
+
const shape = new Circle(10, { x: 25, y: 25, color: "#ff0" });
|
|
461
|
+
|
|
462
|
+
inner.add(shape);
|
|
463
|
+
outer.add(inner);
|
|
464
|
+
this.pipeline.add(outer);
|
|
465
|
+
|
|
466
|
+
// Screen position: 100 + 50 + 25 = 175 for both X and Y</code></pre>
|
|
467
|
+
<div class="canvas-demo">
|
|
468
|
+
<canvas id="nested-canvas"></canvas>
|
|
469
|
+
<div class="canvas-label">Drag any level - nested items follow</div>
|
|
470
|
+
</div>
|
|
471
|
+
</div>
|
|
472
|
+
</section>
|
|
473
|
+
|
|
474
|
+
<section>
|
|
475
|
+
<h2>4. Camera3D and Scene3D</h2>
|
|
476
|
+
<p>
|
|
477
|
+
When using 3D projection, an additional coordinate transformation layer is introduced.
|
|
478
|
+
<code>Camera3D.project()</code> transforms 3D world positions to 2D screen coordinates
|
|
479
|
+
<strong>centered at the origin</strong>.
|
|
480
|
+
</p>
|
|
481
|
+
|
|
482
|
+
<div class="note">
|
|
483
|
+
<strong>Key Insight:</strong> Camera3D returns coordinates centered at (0, 0). That's why
|
|
484
|
+
Scene3D must be positioned at canvas center - so the 3D origin appears in the middle of
|
|
485
|
+
the screen.
|
|
486
|
+
</div>
|
|
487
|
+
|
|
488
|
+
<div class="example">
|
|
489
|
+
<div class="example-title">Interactive Demo: 3D Projection</div>
|
|
490
|
+
<pre><code class="language-javascript">const camera = new Camera3D({ perspective: 800 });
|
|
491
|
+
|
|
492
|
+
// Scene3D MUST be centered for 3D projection to work correctly
|
|
493
|
+
const scene = new Scene3D(this, {
|
|
494
|
+
x: this.width / 2,
|
|
495
|
+
y: this.height / 2,
|
|
496
|
+
camera: camera
|
|
497
|
+
});
|
|
498
|
+
|
|
499
|
+
// Object at 3D origin (0, 0, 0) appears at screen center
|
|
500
|
+
// Object at (100, 0, 0) appears right of center</code></pre>
|
|
501
|
+
<div class="canvas-demo" style="height: 300px;">
|
|
502
|
+
<canvas id="camera3d-canvas"></canvas>
|
|
503
|
+
<div class="canvas-label">Drag to rotate camera - watch projection</div>
|
|
504
|
+
</div>
|
|
505
|
+
</div>
|
|
506
|
+
|
|
507
|
+
<h3>The Projection Formula</h3>
|
|
508
|
+
<table>
|
|
509
|
+
<tr>
|
|
510
|
+
<th>Step</th>
|
|
511
|
+
<th>What Happens</th>
|
|
512
|
+
</tr>
|
|
513
|
+
<tr>
|
|
514
|
+
<td>1. World Position</td>
|
|
515
|
+
<td>Object at 3D coordinates (x, y, z)</td>
|
|
516
|
+
</tr>
|
|
517
|
+
<tr>
|
|
518
|
+
<td>2. Camera Transform</td>
|
|
519
|
+
<td>Subtract camera position, apply rotation</td>
|
|
520
|
+
</tr>
|
|
521
|
+
<tr>
|
|
522
|
+
<td>3. Perspective</td>
|
|
523
|
+
<td><code>scale = perspective / (perspective + z)</code></td>
|
|
524
|
+
</tr>
|
|
525
|
+
<tr>
|
|
526
|
+
<td>4. Screen Offset</td>
|
|
527
|
+
<td>Returns (screenX, screenY) relative to origin</td>
|
|
528
|
+
</tr>
|
|
529
|
+
<tr>
|
|
530
|
+
<td>5. Scene3D Centering</td>
|
|
531
|
+
<td>Adds (width/2, height/2) to get final position</td>
|
|
532
|
+
</tr>
|
|
533
|
+
</table>
|
|
534
|
+
|
|
535
|
+
<h3>Common Gotcha: Manual Centering</h3>
|
|
536
|
+
<p>
|
|
537
|
+
If you're rendering 3D-projected content <strong>outside</strong> of Scene3D, you must
|
|
538
|
+
manually center:
|
|
539
|
+
</p>
|
|
540
|
+
|
|
541
|
+
<div class="example">
|
|
542
|
+
<div class="example-title">Manual Centering Pattern</div>
|
|
543
|
+
<pre><code class="language-javascript">// When NOT inside a Scene3D, you must translate to center yourself
|
|
544
|
+
Painter.useCtx((ctx) => {
|
|
545
|
+
ctx.save();
|
|
546
|
+
ctx.translate(this.game.width / 2, this.game.height / 2);
|
|
547
|
+
|
|
548
|
+
// Now draw at projected coordinates
|
|
549
|
+
const projected = camera.project(x, y, z);
|
|
550
|
+
ctx.fillRect(projected.x - 5, projected.y - 5, 10, 10);
|
|
551
|
+
|
|
552
|
+
ctx.restore();
|
|
553
|
+
});</code></pre>
|
|
554
|
+
</div>
|
|
555
|
+
</section>
|
|
556
|
+
|
|
557
|
+
<section>
|
|
558
|
+
<h2>5. Anchoring and Layouts</h2>
|
|
559
|
+
<p>
|
|
560
|
+
The <code>applyAnchor</code> mixin and layout utilities help position objects relative
|
|
561
|
+
to the canvas edges or other containers.
|
|
562
|
+
</p>
|
|
563
|
+
|
|
564
|
+
<div class="example">
|
|
565
|
+
<div class="example-title">Interactive Demo: Anchor Positions</div>
|
|
566
|
+
<pre><code class="language-javascript">import { applyAnchor, Position } from "gcanvas";
|
|
567
|
+
|
|
568
|
+
// Anchor text to top-center of canvas
|
|
569
|
+
const title = new Text(this, "Game Title", { font: "24px sans-serif" });
|
|
570
|
+
applyAnchor(title, {
|
|
571
|
+
anchor: Position.TOP_CENTER,
|
|
572
|
+
anchorMargin: 20 // 20px from top edge
|
|
573
|
+
});
|
|
574
|
+
|
|
575
|
+
// Available positions:
|
|
576
|
+
// TOP_LEFT, TOP_CENTER, TOP_RIGHT
|
|
577
|
+
// CENTER_LEFT, CENTER, CENTER_RIGHT
|
|
578
|
+
// BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT</code></pre>
|
|
579
|
+
<div class="canvas-demo">
|
|
580
|
+
<canvas id="anchor-canvas"></canvas>
|
|
581
|
+
<div class="canvas-label">Resize window to see anchors adjust</div>
|
|
582
|
+
</div>
|
|
583
|
+
</div>
|
|
584
|
+
|
|
585
|
+
<h3>Layouts</h3>
|
|
586
|
+
<p>Layouts automatically position multiple items:</p>
|
|
587
|
+
|
|
588
|
+
<div class="example">
|
|
589
|
+
<div class="example-title">Interactive Demo: Vertical Layout</div>
|
|
590
|
+
<pre><code class="language-javascript">import { verticalLayout, applyLayout } from "gcanvas";
|
|
591
|
+
|
|
592
|
+
const items = [
|
|
593
|
+
new Text(this, "Option 1", {}),
|
|
594
|
+
new Text(this, "Option 2", {}),
|
|
595
|
+
new Text(this, "Option 3", {})
|
|
596
|
+
];
|
|
597
|
+
|
|
598
|
+
// Compute vertical layout
|
|
599
|
+
const layout = verticalLayout(items, {
|
|
600
|
+
spacing: 15,
|
|
601
|
+
padding: 10,
|
|
602
|
+
align: "center"
|
|
603
|
+
});
|
|
604
|
+
|
|
605
|
+
// Apply positions to items
|
|
606
|
+
applyLayout(items, layout.positions);</code></pre>
|
|
607
|
+
<div class="canvas-demo">
|
|
608
|
+
<canvas id="layout-canvas"></canvas>
|
|
609
|
+
<div class="canvas-label">Click buttons to add/remove items</div>
|
|
610
|
+
</div>
|
|
611
|
+
</div>
|
|
612
|
+
</section>
|
|
613
|
+
|
|
614
|
+
<section>
|
|
615
|
+
<h2>6. Practical Tips</h2>
|
|
616
|
+
|
|
617
|
+
<h3>Quick Reference</h3>
|
|
618
|
+
<table>
|
|
619
|
+
<tr>
|
|
620
|
+
<th>I want to...</th>
|
|
621
|
+
<th>Do this</th>
|
|
622
|
+
</tr>
|
|
623
|
+
<tr>
|
|
624
|
+
<td>Place object at screen position</td>
|
|
625
|
+
<td>Set <code>x</code>, <code>y</code> directly, add to pipeline</td>
|
|
626
|
+
</tr>
|
|
627
|
+
<tr>
|
|
628
|
+
<td>Place object relative to parent</td>
|
|
629
|
+
<td>Add to Scene, set local <code>x</code>, <code>y</code></td>
|
|
630
|
+
</tr>
|
|
631
|
+
<tr>
|
|
632
|
+
<td>Center object on screen</td>
|
|
633
|
+
<td><code>x: game.width / 2, y: game.height / 2</code></td>
|
|
634
|
+
</tr>
|
|
635
|
+
<tr>
|
|
636
|
+
<td>Anchor to screen edge</td>
|
|
637
|
+
<td>Use <code>applyAnchor</code> with <code>Position</code> constant</td>
|
|
638
|
+
</tr>
|
|
639
|
+
<tr>
|
|
640
|
+
<td>Use 3D projection</td>
|
|
641
|
+
<td>Use <code>Scene3D</code> centered at canvas center</td>
|
|
642
|
+
</tr>
|
|
643
|
+
</table>
|
|
644
|
+
|
|
645
|
+
<h3>Common Mistakes</h3>
|
|
646
|
+
|
|
647
|
+
<div class="example">
|
|
648
|
+
<div class="example-title">Mistake 1: Forgetting to center Scene3D</div>
|
|
649
|
+
<pre><code class="language-javascript">// WRONG - 3D origin appears at top-left
|
|
650
|
+
const scene = new Scene3D(this, { x: 0, y: 0, camera });
|
|
651
|
+
|
|
652
|
+
// CORRECT - 3D origin appears at canvas center
|
|
653
|
+
const scene = new Scene3D(this, {
|
|
654
|
+
x: this.width / 2,
|
|
655
|
+
y: this.height / 2,
|
|
656
|
+
camera
|
|
657
|
+
});</code></pre>
|
|
658
|
+
</div>
|
|
659
|
+
|
|
660
|
+
<div class="example">
|
|
661
|
+
<div class="example-title">Mistake 2: Confusing local and screen coordinates</div>
|
|
662
|
+
<pre><code class="language-javascript">const scene = new Scene(this, { x: 100, y: 100 });
|
|
663
|
+
const child = new Circle(20, { x: 50, y: 50 });
|
|
664
|
+
scene.add(child);
|
|
665
|
+
|
|
666
|
+
// WRONG assumption: child is at screen (50, 50)
|
|
667
|
+
// CORRECT: child is at screen (150, 150)</code></pre>
|
|
668
|
+
</div>
|
|
669
|
+
|
|
670
|
+
<div class="example">
|
|
671
|
+
<div class="example-title">Mistake 3: Not updating Camera3D in game loop</div>
|
|
672
|
+
<pre><code class="language-javascript">update(dt) {
|
|
673
|
+
super.update(dt);
|
|
674
|
+
// If using auto-rotation or inertia, camera needs update
|
|
675
|
+
this.camera.update(dt);
|
|
676
|
+
}</code></pre>
|
|
677
|
+
</div>
|
|
678
|
+
</section>
|
|
679
|
+
|
|
680
|
+
<section>
|
|
681
|
+
<h2>See Also</h2>
|
|
682
|
+
<ul class="feature-list">
|
|
683
|
+
<li><a href="pipeline.html" style="color: #0f0;">Rendering Pipeline</a> - How objects are rendered each frame</li>
|
|
684
|
+
<li><a href="gameobjects.html" style="color: #0f0;">Game Objects</a> - Understanding the object hierarchy</li>
|
|
685
|
+
<li><a href="scene.html" style="color: #0f0;">Scene Demo</a> - Interactive scene examples</li>
|
|
686
|
+
<li><a href="layouts.html" style="color: #0f0;">Layout Demo</a> - Layout system in action</li>
|
|
687
|
+
</ul>
|
|
688
|
+
</section>
|
|
689
|
+
|
|
690
|
+
<!-- Prism.js scripts -->
|
|
691
|
+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
|
|
692
|
+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-javascript.min.js"></script>
|
|
693
|
+
|
|
694
|
+
<!-- Demo scripts -->
|
|
695
|
+
<script type="module" src="./js/coordinates.js"></script>
|
|
696
|
+
</body>
|
|
697
|
+
|
|
698
|
+
</html>
|