@guinetik/gcanvas 1.0.2 → 1.0.4

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 (217) hide show
  1. package/dist/gcanvas.es.js +25656 -0
  2. package/dist/gcanvas.es.min.js +1 -0
  3. package/dist/gcanvas.umd.js +1 -0
  4. package/dist/gcanvas.umd.min.js +1 -0
  5. package/package.json +23 -6
  6. package/src/game/objects/index.js +1 -0
  7. package/src/game/objects/spritesheet.js +260 -0
  8. package/src/game/ui/theme.js +6 -0
  9. package/src/io/keys.js +9 -1
  10. package/src/math/boolean.js +481 -0
  11. package/src/math/index.js +1 -0
  12. package/.github/workflows/release.yaml +0 -70
  13. package/.jshintrc +0 -4
  14. package/.vscode/settings.json +0 -22
  15. package/CLAUDE.md +0 -310
  16. package/blackhole.jpg +0 -0
  17. package/demo.png +0 -0
  18. package/demos/CNAME +0 -1
  19. package/demos/animations.html +0 -31
  20. package/demos/basic.html +0 -38
  21. package/demos/baskara.html +0 -31
  22. package/demos/bezier.html +0 -35
  23. package/demos/beziersignature.html +0 -29
  24. package/demos/blackhole.html +0 -28
  25. package/demos/blob.html +0 -35
  26. package/demos/coordinates.html +0 -698
  27. package/demos/cube3d.html +0 -23
  28. package/demos/demos.css +0 -303
  29. package/demos/dino.html +0 -42
  30. package/demos/easing.html +0 -28
  31. package/demos/events.html +0 -195
  32. package/demos/fluent.html +0 -647
  33. package/demos/fluid-simple.html +0 -22
  34. package/demos/fluid.html +0 -37
  35. package/demos/fractals.html +0 -36
  36. package/demos/gameobjects.html +0 -626
  37. package/demos/genart.html +0 -26
  38. package/demos/gendream.html +0 -26
  39. package/demos/group.html +0 -36
  40. package/demos/home.html +0 -587
  41. package/demos/index.html +0 -376
  42. package/demos/isometric.html +0 -34
  43. package/demos/js/animations.js +0 -452
  44. package/demos/js/basic.js +0 -204
  45. package/demos/js/baskara.js +0 -751
  46. package/demos/js/bezier.js +0 -692
  47. package/demos/js/beziersignature.js +0 -241
  48. package/demos/js/blackhole/accretiondisk.obj.js +0 -379
  49. package/demos/js/blackhole/blackhole.obj.js +0 -318
  50. package/demos/js/blackhole/index.js +0 -409
  51. package/demos/js/blackhole/particle.js +0 -56
  52. package/demos/js/blackhole/starfield.obj.js +0 -218
  53. package/demos/js/blob.js +0 -2276
  54. package/demos/js/coordinates.js +0 -840
  55. package/demos/js/cube3d.js +0 -789
  56. package/demos/js/dino.js +0 -1420
  57. package/demos/js/easing.js +0 -477
  58. package/demos/js/fluent.js +0 -183
  59. package/demos/js/fluid-simple.js +0 -253
  60. package/demos/js/fluid.js +0 -527
  61. package/demos/js/fractals.js +0 -931
  62. package/demos/js/fractalworker.js +0 -93
  63. package/demos/js/gameobjects.js +0 -176
  64. package/demos/js/genart.js +0 -268
  65. package/demos/js/gendream.js +0 -209
  66. package/demos/js/group.js +0 -140
  67. package/demos/js/info-toggle.js +0 -25
  68. package/demos/js/isometric.js +0 -863
  69. package/demos/js/kerr.js +0 -1556
  70. package/demos/js/lavalamp.js +0 -590
  71. package/demos/js/layout.js +0 -354
  72. package/demos/js/mondrian.js +0 -285
  73. package/demos/js/opacity.js +0 -275
  74. package/demos/js/painter.js +0 -484
  75. package/demos/js/particles-showcase.js +0 -514
  76. package/demos/js/particles.js +0 -299
  77. package/demos/js/patterns.js +0 -397
  78. package/demos/js/penrose/artifact.js +0 -69
  79. package/demos/js/penrose/blackhole.js +0 -121
  80. package/demos/js/penrose/constants.js +0 -73
  81. package/demos/js/penrose/game.js +0 -943
  82. package/demos/js/penrose/lore.js +0 -278
  83. package/demos/js/penrose/penrosescene.js +0 -892
  84. package/demos/js/penrose/ship.js +0 -216
  85. package/demos/js/penrose/sounds.js +0 -211
  86. package/demos/js/penrose/voidparticle.js +0 -55
  87. package/demos/js/penrose/voidscene.js +0 -258
  88. package/demos/js/penrose/voidship.js +0 -144
  89. package/demos/js/penrose/wormhole.js +0 -46
  90. package/demos/js/pipeline.js +0 -555
  91. package/demos/js/plane3d.js +0 -256
  92. package/demos/js/platformer.js +0 -1579
  93. package/demos/js/scene.js +0 -304
  94. package/demos/js/scenes.js +0 -320
  95. package/demos/js/schrodinger.js +0 -410
  96. package/demos/js/schwarzschild.js +0 -1023
  97. package/demos/js/shapes.js +0 -628
  98. package/demos/js/space/alien.js +0 -171
  99. package/demos/js/space/boom.js +0 -98
  100. package/demos/js/space/boss.js +0 -353
  101. package/demos/js/space/buff.js +0 -73
  102. package/demos/js/space/bullet.js +0 -102
  103. package/demos/js/space/constants.js +0 -85
  104. package/demos/js/space/game.js +0 -1884
  105. package/demos/js/space/hud.js +0 -112
  106. package/demos/js/space/laserbeam.js +0 -179
  107. package/demos/js/space/lightning.js +0 -277
  108. package/demos/js/space/minion.js +0 -192
  109. package/demos/js/space/missile.js +0 -212
  110. package/demos/js/space/player.js +0 -430
  111. package/demos/js/space/powerup.js +0 -90
  112. package/demos/js/space/starfield.js +0 -58
  113. package/demos/js/space/starpower.js +0 -90
  114. package/demos/js/spacetime.js +0 -559
  115. package/demos/js/sphere3d.js +0 -229
  116. package/demos/js/sprite.js +0 -473
  117. package/demos/js/svgtween.js +0 -204
  118. package/demos/js/tde/accretiondisk.js +0 -471
  119. package/demos/js/tde/blackhole.js +0 -219
  120. package/demos/js/tde/blackholescene.js +0 -209
  121. package/demos/js/tde/config.js +0 -59
  122. package/demos/js/tde/index.js +0 -820
  123. package/demos/js/tde/jets.js +0 -290
  124. package/demos/js/tde/lensedstarfield.js +0 -154
  125. package/demos/js/tde/tdestar.js +0 -297
  126. package/demos/js/tde/tidalstream.js +0 -372
  127. package/demos/js/tde_old/blackhole.obj.js +0 -354
  128. package/demos/js/tde_old/debris.obj.js +0 -791
  129. package/demos/js/tde_old/flare.obj.js +0 -239
  130. package/demos/js/tde_old/index.js +0 -448
  131. package/demos/js/tde_old/star.obj.js +0 -812
  132. package/demos/js/tiles.js +0 -312
  133. package/demos/js/tweendemo.js +0 -79
  134. package/demos/js/visibility.js +0 -102
  135. package/demos/kerr.html +0 -28
  136. package/demos/lavalamp.html +0 -27
  137. package/demos/layouts.html +0 -37
  138. package/demos/logo.svg +0 -4
  139. package/demos/loop.html +0 -84
  140. package/demos/mondrian.html +0 -32
  141. package/demos/og_image.png +0 -0
  142. package/demos/opacity.html +0 -36
  143. package/demos/painter.html +0 -39
  144. package/demos/particles-showcase.html +0 -28
  145. package/demos/particles.html +0 -24
  146. package/demos/patterns.html +0 -33
  147. package/demos/penrose-game.html +0 -31
  148. package/demos/pipeline.html +0 -737
  149. package/demos/plane3d.html +0 -24
  150. package/demos/platformer.html +0 -43
  151. package/demos/scene.html +0 -33
  152. package/demos/scenes.html +0 -96
  153. package/demos/schrodinger.html +0 -27
  154. package/demos/schwarzschild.html +0 -27
  155. package/demos/shapes.html +0 -16
  156. package/demos/space.html +0 -85
  157. package/demos/spacetime.html +0 -27
  158. package/demos/sphere3d.html +0 -24
  159. package/demos/sprite.html +0 -18
  160. package/demos/svgtween.html +0 -29
  161. package/demos/tde.html +0 -28
  162. package/demos/tiles.html +0 -28
  163. package/demos/transforms.html +0 -400
  164. package/demos/tween.html +0 -45
  165. package/demos/visibility.html +0 -33
  166. package/docs/README.md +0 -230
  167. package/docs/api/FluidSystem.md +0 -173
  168. package/docs/concepts/architecture-overview.md +0 -204
  169. package/docs/concepts/coordinate-system.md +0 -384
  170. package/docs/concepts/lifecycle.md +0 -255
  171. package/docs/concepts/rendering-pipeline.md +0 -279
  172. package/docs/concepts/shapes-vs-gameobjects.md +0 -187
  173. package/docs/concepts/tde-zorder.md +0 -106
  174. package/docs/concepts/two-layer-architecture.md +0 -229
  175. package/docs/fluid-dynamics.md +0 -99
  176. package/docs/getting-started/first-game.md +0 -354
  177. package/docs/getting-started/hello-world.md +0 -269
  178. package/docs/getting-started/installation.md +0 -175
  179. package/docs/modules/collision/README.md +0 -453
  180. package/docs/modules/fluent/README.md +0 -1075
  181. package/docs/modules/game/README.md +0 -303
  182. package/docs/modules/isometric-camera.md +0 -210
  183. package/docs/modules/isometric.md +0 -275
  184. package/docs/modules/painter/README.md +0 -328
  185. package/docs/modules/particle/README.md +0 -559
  186. package/docs/modules/shapes/README.md +0 -221
  187. package/docs/modules/shapes/base/euclidian.md +0 -123
  188. package/docs/modules/shapes/base/geometry2d.md +0 -204
  189. package/docs/modules/shapes/base/renderable.md +0 -215
  190. package/docs/modules/shapes/base/shape.md +0 -262
  191. package/docs/modules/shapes/base/transformable.md +0 -243
  192. package/docs/modules/shapes/hierarchy.md +0 -218
  193. package/docs/modules/state/README.md +0 -577
  194. package/docs/modules/util/README.md +0 -99
  195. package/docs/modules/util/camera3d.md +0 -412
  196. package/docs/modules/util/scene3d.md +0 -395
  197. package/index.html +0 -17
  198. package/jsdoc.json +0 -50
  199. package/scripts/build-demo.js +0 -69
  200. package/scripts/bundle4llm.js +0 -276
  201. package/scripts/clearconsole.js +0 -48
  202. package/test/math/orbital.test.js +0 -61
  203. package/test/math/tensor.test.js +0 -114
  204. package/test/particle/emitter.test.js +0 -204
  205. package/test/particle/particle-system.test.js +0 -310
  206. package/test/particle/particle.test.js +0 -116
  207. package/test/particle/updaters.test.js +0 -386
  208. package/test/setup.js +0 -120
  209. package/test/shapes/euclidian.test.js +0 -44
  210. package/test/shapes/geometry.test.js +0 -86
  211. package/test/shapes/group.test.js +0 -86
  212. package/test/shapes/rectangle.test.js +0 -64
  213. package/test/shapes/transform.test.js +0 -379
  214. package/test/util/camera3d.test.js +0 -428
  215. package/test/util/scene3d.test.js +0 -352
  216. package/vite.config.js +0 -50
  217. package/vitest.config.js +0 -13
package/demos/coordinates.html DELETED
@@ -1,698 +0,0 @@
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>