@umicat/three-sdk 1.13.0 → 1.14.0

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.
@@ -1,5 +1,13 @@
1
1
  import type { ThreeUmicat } from './ThreeUmicat.js';
2
- /** The size a game should render at: the upper panel when folded, else the window. */
2
+ /**
3
+ * The size a game should render at: the upper panel when folded, else the
4
+ * window.
5
+ *
6
+ * Only needed by a game that wants to keep driving its own canvas — hand
7
+ * `installDualScreen` the renderer instead and none of this is your problem.
8
+ * Kept because a game with several views, or one that renders at a fraction of
9
+ * the panel, has a real reason to do the sizing itself.
10
+ */
3
11
  export declare function viewportSize(umicat: ThreeUmicat): {
4
12
  width: number;
5
13
  height: number;
@@ -16,4 +24,39 @@ export declare function viewportSize(umicat: ThreeUmicat): {
16
24
  * All in CSS pixels; all `0` when there is no fold, so a stylesheet that uses
17
25
  * them is correct on a flat screen too.
18
26
  */
19
- export declare function installDualScreen(umicat: ThreeUmicat): () => void;
27
+ /** What the SDK will resize for you. Everything is optional. */
28
+ export interface DualScreenTargets {
29
+ /** The game's renderer. Hand it over and the SDK owns the upper panel
30
+ * completely — buffer, CSS box and all. Leave it out and the canvas is not
31
+ * touched at all (see below). */
32
+ renderer?: {
33
+ setSize(width: number, height: number, updateStyle?: boolean): void;
34
+ domElement: HTMLCanvasElement;
35
+ };
36
+ /** Kept in step with the panel's aspect. Without it the picture is correctly
37
+ * sized and wrongly shaped. */
38
+ camera?: {
39
+ aspect: number;
40
+ updateProjectionMatrix(): void;
41
+ };
42
+ }
43
+ /**
44
+ * Starts keeping the page laid out for the fold. Call once, after `init`.
45
+ *
46
+ * **Hand over `renderer` and `camera` and the game needs no other change.** The
47
+ * SDK then re-applies the panel size after every resize — its listener is
48
+ * registered after the game's, so the game's own
49
+ * `setSize(innerWidth, innerHeight)` runs first and is corrected, and a frame
50
+ * is re-applied on the next rAF in case a game registers its listener later.
51
+ *
52
+ * **Leave them out and the canvas is left ALONE.** That is deliberate, and it
53
+ * is a correction: an earlier version moved the canvas's CSS box into the
54
+ * upper panel without owning the buffer, so a game whose resize still asked
55
+ * the window rendered a 669x951 buffer at aspect 0.70 squeezed into a
56
+ * 669x455.5 box — visibly squashed. Half-owning a canvas is worse than not
57
+ * touching it, so now it is one or the other.
58
+ *
59
+ * The control layer moves either way: the SDK built it, so it is always the
60
+ * SDK's to place.
61
+ */
62
+ export declare function installDualScreen(umicat: ThreeUmicat, targets?: DualScreenTargets): () => void;
@@ -26,7 +26,15 @@
26
26
  // crease. That is a worse picture, not a broken one, and it degrades without
27
27
  // anybody having to ship anything.
28
28
  const TOUCH_ROOT = '[data-umicat-touch]';
29
- /** The size a game should render at: the upper panel when folded, else the window. */
29
+ /**
30
+ * The size a game should render at: the upper panel when folded, else the
31
+ * window.
32
+ *
33
+ * Only needed by a game that wants to keep driving its own canvas — hand
34
+ * `installDualScreen` the renderer instead and none of this is your problem.
35
+ * Kept because a game with several views, or one that renders at a fraction of
36
+ * the panel, has a real reason to do the sizing itself.
37
+ */
30
38
  export function viewportSize(umicat) {
31
39
  const { dualScreen, top } = umicat.fold.layout;
32
40
  if (dualScreen && top)
@@ -36,24 +44,52 @@ export function viewportSize(umicat) {
36
44
  /**
37
45
  * Starts keeping the page laid out for the fold. Call once, after `init`.
38
46
  *
39
- * Publishes the geometry as CSS custom properties on `<html>` so a game's own
40
- * DOM/HUD can use it without reading the SDK:
47
+ * **Hand over `renderer` and `camera` and the game needs no other change.** The
48
+ * SDK then re-applies the panel size after every resize — its listener is
49
+ * registered after the game's, so the game's own
50
+ * `setSize(innerWidth, innerHeight)` runs first and is corrected, and a frame
51
+ * is re-applied on the next rAF in case a game registers its listener later.
41
52
  *
42
- * --umicat-top-height, --umicat-bottom-top, --umicat-bottom-height,
43
- * --umicat-fold-top, --umicat-fold-height
53
+ * **Leave them out and the canvas is left ALONE.** That is deliberate, and it
54
+ * is a correction: an earlier version moved the canvas's CSS box into the
55
+ * upper panel without owning the buffer, so a game whose resize still asked
56
+ * the window rendered a 669x951 buffer at aspect 0.70 squeezed into a
57
+ * 669x455.5 box — visibly squashed. Half-owning a canvas is worse than not
58
+ * touching it, so now it is one or the other.
44
59
  *
45
- * All in CSS pixels; all `0` when there is no fold, so a stylesheet that uses
46
- * them is correct on a flat screen too.
60
+ * The control layer moves either way: the SDK built it, so it is always the
61
+ * SDK's to place.
47
62
  */
48
- export function installDualScreen(umicat) {
49
- return umicat.fold.subscribe((layout) => {
63
+ export function installDualScreen(umicat, targets = {}) {
64
+ let current = null;
65
+ const applyCanvas = () => {
66
+ if (!targets.renderer || !current)
67
+ return;
68
+ const size = current.dualScreen && current.top
69
+ ? { width: current.top.width, height: current.top.height }
70
+ : { width: window.innerWidth, height: window.innerHeight };
71
+ targets.renderer.setSize(size.width, size.height, false);
72
+ if (targets.camera) {
73
+ targets.camera.aspect = size.width / size.height;
74
+ targets.camera.updateProjectionMatrix();
75
+ }
76
+ placeCanvas(current, targets.renderer.domElement);
77
+ };
78
+ const onResize = () => { applyCanvas(); requestAnimationFrame(applyCanvas); };
79
+ window.addEventListener('resize', onResize);
80
+ const off = umicat.fold.subscribe((layout) => {
81
+ current = layout;
50
82
  publishVariables(layout);
51
83
  placeControls(layout);
52
- // The game sizes its own renderer off a resize listener. Folding is a size
53
- // change as far as it is concerned, but no window resize accompanies it —
54
- // the window is exactly as big as it was, the usable part of it is not.
55
- window.dispatchEvent(new Event('resize'));
84
+ applyCanvas();
85
+ // A game that drives its own canvas (no `renderer` here) still needs to
86
+ // hear about it. Folding is a size change as far as it is concerned, but
87
+ // no window resize accompanies it — the window is exactly as big as it
88
+ // was, the usable part of it is not.
89
+ if (!targets.renderer)
90
+ window.dispatchEvent(new Event('resize'));
56
91
  });
92
+ return () => { window.removeEventListener('resize', onResize); off(); };
57
93
  }
58
94
  function publishVariables(layout) {
59
95
  const root = document.documentElement;
@@ -82,18 +118,52 @@ function publishVariables(layout) {
82
118
  * Done by moving the LAYER rather than each control, so every control the SDK
83
119
  * places — and any it grows later — follows for free.
84
120
  */
121
+ /**
122
+ * Constrains the canvas's CSS box to the upper panel.
123
+ *
124
+ * `viewportSize` alone is not enough, and the reason is a three.js argument
125
+ * nobody thinks about: `setSize(w, h, false)` — which every template uses —
126
+ * sizes the DRAWING BUFFER and deliberately leaves the CSS box alone, because
127
+ * normally the canvas is stretched to the window by a stylesheet. Shrink only
128
+ * the buffer and the result is the same full-screen picture at a lower
129
+ * resolution, which looks like nothing happened at all.
130
+ *
131
+ * Found by doing exactly that: the fold arrived, the buffer shrank, and the
132
+ * screenshot was unchanged.
133
+ *
134
+ * Defaults to the document's only canvas. A game with several passes its own.
135
+ */
136
+ function placeCanvas(layout, explicit) {
137
+ const canvas = explicit ?? document.querySelector('canvas');
138
+ if (!canvas)
139
+ return;
140
+ if (layout.dualScreen && layout.top) {
141
+ Object.assign(canvas.style, {
142
+ position: 'fixed',
143
+ left: `${layout.top.x}px`,
144
+ top: `${layout.top.y}px`,
145
+ width: `${layout.top.width}px`,
146
+ height: `${layout.top.height}px`,
147
+ });
148
+ }
149
+ else {
150
+ Object.assign(canvas.style, { position: '', left: '', top: '', width: '', height: '' });
151
+ }
152
+ }
85
153
  function placeControls(layout) {
86
154
  const root = document.querySelector(TOUCH_ROOT);
87
155
  if (!root)
88
156
  return; // desktop: the SDK mounts no touch layer at all
157
+ // Write the shorthand FIRST and the longhands after. `inset` sets all four
158
+ // edges, so assigning it last — which is what an object literal written in
159
+ // the obvious order does — silently wipes the `top` set two lines above and
160
+ // collapses the layer to nothing. The controls do not move; they vanish.
89
161
  if (layout.dualScreen && layout.bottom) {
90
- Object.assign(root.style, {
91
- top: `${layout.bottom.y}px`,
92
- bottom: '0px',
93
- inset: '',
94
- });
162
+ root.style.inset = '0';
163
+ root.style.top = `${layout.bottom.y}px`;
95
164
  }
96
165
  else {
97
- Object.assign(root.style, { inset: '0', top: '', bottom: '' });
166
+ root.style.inset = '0';
167
+ root.style.top = '';
98
168
  }
99
169
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.13.0",
3
+ "version": "1.14.0",
4
4
  "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",