@umicat/three-sdk 1.12.0 → 1.13.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.
@@ -0,0 +1,19 @@
1
+ import type { ThreeUmicat } from './ThreeUmicat.js';
2
+ /** The size a game should render at: the upper panel when folded, else the window. */
3
+ export declare function viewportSize(umicat: ThreeUmicat): {
4
+ width: number;
5
+ height: number;
6
+ };
7
+ /**
8
+ * Starts keeping the page laid out for the fold. Call once, after `init`.
9
+ *
10
+ * Publishes the geometry as CSS custom properties on `<html>` so a game's own
11
+ * DOM/HUD can use it without reading the SDK:
12
+ *
13
+ * --umicat-top-height, --umicat-bottom-top, --umicat-bottom-height,
14
+ * --umicat-fold-top, --umicat-fold-height
15
+ *
16
+ * All in CSS pixels; all `0` when there is no fold, so a stylesheet that uses
17
+ * them is correct on a flat screen too.
18
+ */
19
+ export declare function installDualScreen(umicat: ThreeUmicat): () => void;
@@ -0,0 +1,99 @@
1
+ // Laying a 3D game across a folded device, NDS-style: the world above the
2
+ // crease, the controls below it.
3
+ //
4
+ // **The split is owned by two different parties, and that is not a design
5
+ // choice — it is where the code already lives.**
6
+ //
7
+ // • The SDK owns the touch-control layer (`Input3D` builds it), so moving the
8
+ // controls into the lower panel works on every 3D game that exists, with no
9
+ // game-side change at all.
10
+ //
11
+ // • The GAME owns its renderer and canvas — three-sdk has no central wrapper
12
+ // the way the Phaser SDK does, so every `main.ts` calls
13
+ // `renderer.setSize(window.innerWidth, window.innerHeight)` itself. The SDK
14
+ // cannot resize a renderer it was never handed. So a game that wants its
15
+ // world in the UPPER panel asks for the size instead of reading the window:
16
+ //
17
+ // const { width, height } = viewportSize(umicat);
18
+ // renderer.setSize(width, height, false);
19
+ // camera.aspect = width / height;
20
+ //
21
+ // `viewportSize` is the whole window when there is no fold, so that line is
22
+ // correct everywhere and the game never branches.
23
+ //
24
+ // A game that does NOT adopt `viewportSize` still gets the controls moved down,
25
+ // which is the half that matters for reach; its world simply still spans the
26
+ // crease. That is a worse picture, not a broken one, and it degrades without
27
+ // anybody having to ship anything.
28
+ const TOUCH_ROOT = '[data-umicat-touch]';
29
+ /** The size a game should render at: the upper panel when folded, else the window. */
30
+ export function viewportSize(umicat) {
31
+ const { dualScreen, top } = umicat.fold.layout;
32
+ if (dualScreen && top)
33
+ return { width: top.width, height: top.height };
34
+ return { width: window.innerWidth, height: window.innerHeight };
35
+ }
36
+ /**
37
+ * Starts keeping the page laid out for the fold. Call once, after `init`.
38
+ *
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:
41
+ *
42
+ * --umicat-top-height, --umicat-bottom-top, --umicat-bottom-height,
43
+ * --umicat-fold-top, --umicat-fold-height
44
+ *
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.
47
+ */
48
+ export function installDualScreen(umicat) {
49
+ return umicat.fold.subscribe((layout) => {
50
+ publishVariables(layout);
51
+ 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'));
56
+ });
57
+ }
58
+ function publishVariables(layout) {
59
+ const root = document.documentElement;
60
+ const px = (n) => `${Math.round(n ?? 0)}px`;
61
+ const on = layout.dualScreen;
62
+ root.style.setProperty('--umicat-top-height', px(on ? layout.top?.height : 0));
63
+ root.style.setProperty('--umicat-bottom-top', px(on ? layout.bottom?.y : 0));
64
+ root.style.setProperty('--umicat-bottom-height', px(on ? layout.bottom?.height : 0));
65
+ root.style.setProperty('--umicat-fold-top', px(on ? layout.division?.y : 0));
66
+ root.style.setProperty('--umicat-fold-height', px(on ? layout.division?.height : 0));
67
+ // A stylesheet cannot ask the SDK a question, so the state is an attribute.
68
+ if (on)
69
+ root.dataset.umicatDualScreen = '';
70
+ else
71
+ delete root.dataset.umicatDualScreen;
72
+ }
73
+ /**
74
+ * Moves the SDK's touch layer into the lower panel.
75
+ *
76
+ * It is `position:fixed; inset:0` normally — the full window, with the stick
77
+ * and buttons pinned near the bottom corners, which is where thumbs are on a
78
+ * flat phone. Folded, thumbs are on the lower half and the upper half is
79
+ * propped away from them, so "near the bottom of the window" is the wrong place
80
+ * twice over: too far to reach, and sitting on top of the world.
81
+ *
82
+ * Done by moving the LAYER rather than each control, so every control the SDK
83
+ * places — and any it grows later — follows for free.
84
+ */
85
+ function placeControls(layout) {
86
+ const root = document.querySelector(TOUCH_ROOT);
87
+ if (!root)
88
+ return; // desktop: the SDK mounts no touch layer at all
89
+ if (layout.dualScreen && layout.bottom) {
90
+ Object.assign(root.style, {
91
+ top: `${layout.bottom.y}px`,
92
+ bottom: '0px',
93
+ inset: '',
94
+ });
95
+ }
96
+ else {
97
+ Object.assign(root.style, { inset: '0', top: '', bottom: '' });
98
+ }
99
+ }
package/dist/index.d.ts CHANGED
@@ -27,6 +27,8 @@ export { resolveAnchor3D } from './hud3d/anchor3d.js';
27
27
  export { setHudBinding3D, getHudBinding3D } from './hud3d/HudDynamicBinding3D.js';
28
28
  export type { Attachment } from './Sockets.js';
29
29
  export type { LoadedScene3D, LoadSceneOptions } from './SceneLoader3D.js';
30
+ export { installDualScreen, viewportSize } from './DualScreen3D.js';
31
+ export type { FoldLayout, FoldRect } from '@umicat/platform-sdk/fold/FoldModule.js';
30
32
  export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';
31
33
  export type { Orientation } from '@umicat/platform-sdk/orientation.js';
32
34
  export { RpcError } from '@umicat/platform-sdk/core/Transport.js';
package/dist/index.js CHANGED
@@ -24,5 +24,6 @@ export { setHudBinding3D, getHudBinding3D } from './hud3d/HudDynamicBinding3D.js
24
24
  // Re-exported so a game imports one package for the common case. A game should
25
25
  // not have to know that identity and saves come from a different package than
26
26
  // the renderer.
27
+ export { installDualScreen, viewportSize } from './DualScreen3D.js';
27
28
  export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';
28
29
  export { RpcError } from '@umicat/platform-sdk/core/Transport.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.12.0",
3
+ "version": "1.13.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",
@@ -19,7 +19,7 @@
19
19
  "dependencies": {
20
20
  "@dimforge/rapier3d-compat": "^0.14.0",
21
21
  "three": "0.186.0",
22
- "@umicat/platform-sdk": "^0.2.0"
22
+ "@umicat/platform-sdk": "^0.3.0"
23
23
  },
24
24
  "devDependencies": {
25
25
  "@types/three": "^0.185.4",