@guinetik/gcanvas 1.0.4 → 1.0.5

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.
Files changed (193) hide show
  1. package/dist/CNAME +1 -0
  2. package/dist/animations.html +31 -0
  3. package/dist/basic.html +38 -0
  4. package/dist/baskara.html +31 -0
  5. package/dist/bezier.html +35 -0
  6. package/dist/beziersignature.html +29 -0
  7. package/dist/blackhole.html +28 -0
  8. package/dist/blob.html +35 -0
  9. package/dist/coordinates.html +698 -0
  10. package/dist/cube3d.html +23 -0
  11. package/dist/demos.css +303 -0
  12. package/dist/dino.html +42 -0
  13. package/dist/easing.html +28 -0
  14. package/dist/events.html +195 -0
  15. package/dist/fluent.html +647 -0
  16. package/dist/fluid-simple.html +22 -0
  17. package/dist/fluid.html +37 -0
  18. package/dist/fractals.html +36 -0
  19. package/dist/gameobjects.html +626 -0
  20. package/dist/gcanvas.es.js +517 -0
  21. package/dist/gcanvas.es.min.js +1 -1
  22. package/dist/gcanvas.umd.js +1 -1
  23. package/dist/gcanvas.umd.min.js +1 -1
  24. package/dist/genart.html +26 -0
  25. package/dist/gendream.html +26 -0
  26. package/dist/group.html +36 -0
  27. package/dist/home.html +587 -0
  28. package/dist/hyperbolic001.html +23 -0
  29. package/dist/hyperbolic002.html +23 -0
  30. package/dist/hyperbolic003.html +23 -0
  31. package/dist/hyperbolic004.html +23 -0
  32. package/dist/hyperbolic005.html +22 -0
  33. package/dist/index.html +398 -0
  34. package/dist/isometric.html +34 -0
  35. package/dist/js/animations.js +452 -0
  36. package/dist/js/basic.js +204 -0
  37. package/dist/js/baskara.js +751 -0
  38. package/dist/js/bezier.js +692 -0
  39. package/dist/js/beziersignature.js +241 -0
  40. package/dist/js/blackhole/accretiondisk.obj.js +379 -0
  41. package/dist/js/blackhole/blackhole.obj.js +318 -0
  42. package/dist/js/blackhole/index.js +409 -0
  43. package/dist/js/blackhole/particle.js +56 -0
  44. package/dist/js/blackhole/starfield.obj.js +218 -0
  45. package/dist/js/blob.js +2276 -0
  46. package/dist/js/coordinates.js +840 -0
  47. package/dist/js/cube3d.js +789 -0
  48. package/dist/js/dino.js +1420 -0
  49. package/dist/js/easing.js +477 -0
  50. package/dist/js/fluent.js +183 -0
  51. package/dist/js/fluid-simple.js +253 -0
  52. package/dist/js/fluid.js +527 -0
  53. package/dist/js/fractals.js +932 -0
  54. package/dist/js/fractalworker.js +93 -0
  55. package/dist/js/gameobjects.js +176 -0
  56. package/dist/js/genart.js +268 -0
  57. package/dist/js/gendream.js +209 -0
  58. package/dist/js/group.js +140 -0
  59. package/dist/js/hyperbolic001.js +310 -0
  60. package/dist/js/hyperbolic002.js +388 -0
  61. package/dist/js/hyperbolic003.js +319 -0
  62. package/dist/js/hyperbolic004.js +345 -0
  63. package/dist/js/hyperbolic005.js +340 -0
  64. package/dist/js/info-toggle.js +25 -0
  65. package/dist/js/isometric.js +863 -0
  66. package/dist/js/kerr.js +1547 -0
  67. package/dist/js/lavalamp.js +590 -0
  68. package/dist/js/layout.js +354 -0
  69. package/dist/js/mondrian.js +285 -0
  70. package/dist/js/opacity.js +275 -0
  71. package/dist/js/painter.js +484 -0
  72. package/dist/js/particles-showcase.js +514 -0
  73. package/dist/js/particles.js +299 -0
  74. package/dist/js/patterns.js +397 -0
  75. package/dist/js/penrose/artifact.js +69 -0
  76. package/dist/js/penrose/blackhole.js +121 -0
  77. package/dist/js/penrose/constants.js +73 -0
  78. package/dist/js/penrose/game.js +943 -0
  79. package/dist/js/penrose/lore.js +278 -0
  80. package/dist/js/penrose/penrosescene.js +892 -0
  81. package/dist/js/penrose/ship.js +216 -0
  82. package/dist/js/penrose/sounds.js +211 -0
  83. package/dist/js/penrose/voidparticle.js +55 -0
  84. package/dist/js/penrose/voidscene.js +258 -0
  85. package/dist/js/penrose/voidship.js +144 -0
  86. package/dist/js/penrose/wormhole.js +46 -0
  87. package/dist/js/pipeline.js +555 -0
  88. package/dist/js/plane3d.js +256 -0
  89. package/dist/js/platformer.js +1579 -0
  90. package/dist/js/scene.js +304 -0
  91. package/dist/js/scenes.js +320 -0
  92. package/dist/js/schrodinger.js +410 -0
  93. package/dist/js/schwarzschild.js +1015 -0
  94. package/dist/js/shapes.js +628 -0
  95. package/dist/js/space/alien.js +171 -0
  96. package/dist/js/space/boom.js +98 -0
  97. package/dist/js/space/boss.js +353 -0
  98. package/dist/js/space/buff.js +73 -0
  99. package/dist/js/space/bullet.js +102 -0
  100. package/dist/js/space/constants.js +85 -0
  101. package/dist/js/space/game.js +1884 -0
  102. package/dist/js/space/hud.js +112 -0
  103. package/dist/js/space/laserbeam.js +179 -0
  104. package/dist/js/space/lightning.js +277 -0
  105. package/dist/js/space/minion.js +192 -0
  106. package/dist/js/space/missile.js +212 -0
  107. package/dist/js/space/player.js +430 -0
  108. package/dist/js/space/powerup.js +90 -0
  109. package/dist/js/space/starfield.js +58 -0
  110. package/dist/js/space/starpower.js +90 -0
  111. package/dist/js/spacetime.js +559 -0
  112. package/dist/js/sphere3d.js +229 -0
  113. package/dist/js/sprite.js +473 -0
  114. package/dist/js/starfaux/config.js +118 -0
  115. package/dist/js/starfaux/enemy.js +353 -0
  116. package/dist/js/starfaux/hud.js +78 -0
  117. package/dist/js/starfaux/index.js +482 -0
  118. package/dist/js/starfaux/laser.js +182 -0
  119. package/dist/js/starfaux/player.js +468 -0
  120. package/dist/js/starfaux/terrain.js +560 -0
  121. package/dist/js/study001.js +275 -0
  122. package/dist/js/study002.js +366 -0
  123. package/dist/js/study003.js +331 -0
  124. package/dist/js/study004.js +389 -0
  125. package/dist/js/study005.js +209 -0
  126. package/dist/js/study006.js +194 -0
  127. package/dist/js/study007.js +192 -0
  128. package/dist/js/study008.js +413 -0
  129. package/dist/js/svgtween.js +204 -0
  130. package/dist/js/tde/accretiondisk.js +471 -0
  131. package/dist/js/tde/blackhole.js +219 -0
  132. package/dist/js/tde/blackholescene.js +209 -0
  133. package/dist/js/tde/config.js +59 -0
  134. package/dist/js/tde/index.js +820 -0
  135. package/dist/js/tde/jets.js +290 -0
  136. package/dist/js/tde/lensedstarfield.js +154 -0
  137. package/dist/js/tde/tdestar.js +297 -0
  138. package/dist/js/tde/tidalstream.js +372 -0
  139. package/dist/js/tde_old/blackhole.obj.js +354 -0
  140. package/dist/js/tde_old/debris.obj.js +791 -0
  141. package/dist/js/tde_old/flare.obj.js +239 -0
  142. package/dist/js/tde_old/index.js +448 -0
  143. package/dist/js/tde_old/star.obj.js +812 -0
  144. package/dist/js/tetris/config.js +157 -0
  145. package/dist/js/tetris/grid.js +286 -0
  146. package/dist/js/tetris/index.js +1195 -0
  147. package/dist/js/tetris/renderer.js +634 -0
  148. package/dist/js/tetris/tetrominos.js +280 -0
  149. package/dist/js/tiles.js +312 -0
  150. package/dist/js/tweendemo.js +79 -0
  151. package/dist/js/visibility.js +102 -0
  152. package/dist/kerr.html +28 -0
  153. package/dist/lavalamp.html +27 -0
  154. package/dist/layouts.html +37 -0
  155. package/dist/logo.svg +4 -0
  156. package/dist/loop.html +84 -0
  157. package/dist/mondrian.html +32 -0
  158. package/dist/og_image.png +0 -0
  159. package/dist/opacity.html +36 -0
  160. package/dist/painter.html +39 -0
  161. package/dist/particles-showcase.html +28 -0
  162. package/dist/particles.html +24 -0
  163. package/dist/patterns.html +33 -0
  164. package/dist/penrose-game.html +31 -0
  165. package/dist/pipeline.html +737 -0
  166. package/dist/plane3d.html +24 -0
  167. package/dist/platformer.html +43 -0
  168. package/dist/scene.html +33 -0
  169. package/dist/scenes.html +96 -0
  170. package/dist/schrodinger.html +27 -0
  171. package/dist/schwarzschild.html +27 -0
  172. package/dist/shapes.html +16 -0
  173. package/dist/space.html +85 -0
  174. package/dist/spacetime.html +27 -0
  175. package/dist/sphere3d.html +24 -0
  176. package/dist/sprite.html +18 -0
  177. package/dist/starfaux.html +22 -0
  178. package/dist/study001.html +23 -0
  179. package/dist/study002.html +23 -0
  180. package/dist/study003.html +23 -0
  181. package/dist/study004.html +23 -0
  182. package/dist/study005.html +22 -0
  183. package/dist/study006.html +24 -0
  184. package/dist/study007.html +24 -0
  185. package/dist/study008.html +22 -0
  186. package/dist/svgtween.html +29 -0
  187. package/dist/tde.html +28 -0
  188. package/dist/tetris3d.html +25 -0
  189. package/dist/tiles.html +28 -0
  190. package/dist/transforms.html +400 -0
  191. package/dist/tween.html +45 -0
  192. package/dist/visibility.html +33 -0
  193. package/package.json +1 -1
package/dist/coordinates.html ADDED
@@ -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>