@bendyline/molen-client 0.0.1 → 0.0.3

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,120 @@
1
+ import { GamepadAxisBinding, InputProfile } from "@bendyline/molen-schema";
2
+
3
+ //#region src/input.d.ts
4
+ type Unsubscribe = () => void;
5
+ interface InputBindings {
6
+ bindings: Record<string, string>;
7
+ }
8
+ /** Resolve a key or Mouse<button> code to its bound action. */
9
+ declare function resolveAction(bindings: Record<string, string>, code: string): string | undefined;
10
+ /** Structural Gamepad API snapshot; also usable by custom device adapters and tests. */
11
+ interface InputGamepad {
12
+ id: string;
13
+ index: number;
14
+ connected: boolean;
15
+ mapping: string;
16
+ axes: readonly number[];
17
+ buttons: readonly {
18
+ pressed: boolean;
19
+ value: number;
20
+ }[];
21
+ }
22
+ type EventTargetLike = {
23
+ addEventListener(type: string, listener: (ev: unknown) => void): void;
24
+ removeEventListener(type: string, listener: (ev: unknown) => void): void;
25
+ };
26
+ interface InputMapOptions extends InputProfile {
27
+ profiles?: Record<string, InputProfile>;
28
+ profile?: string;
29
+ /** Event source (usually window); injectable for tests. */
30
+ target?: EventTargetLike;
31
+ /** Defaults to navigator.getGamepads. Inject an adapter for other browser facilities. */
32
+ getGamepads?: () => readonly (InputGamepad | null)[];
33
+ }
34
+ /** Calibrate and shape a raw axis. Invalid/non-finite hardware readings are neutral. */
35
+ declare function normalizeInputAxis(raw: number, binding: GamepadAxisBinding): number;
36
+ /**
37
+ * Keyboard/mouse + browser controllers mapped to numeric named actions. Call update() each
38
+ * frame (applyInputRules does this on its poller). Profiles are complete replacements.
39
+ */
40
+ declare class InputMap {
41
+ private base;
42
+ private readonly profiles;
43
+ private current;
44
+ private readonly keys;
45
+ private readonly blockedKeys;
46
+ private readonly blockedButtons;
47
+ private baselineButtons;
48
+ private values;
49
+ private padValues;
50
+ /** Software controls (touch joysticks, on-screen buttons): source → action → value. */
51
+ private readonly virtualValues;
52
+ private pads;
53
+ private enabled;
54
+ private disposed;
55
+ private focused;
56
+ private suspensions;
57
+ private revision;
58
+ private readonly pressHandlers;
59
+ private readonly releaseHandlers;
60
+ private readonly changeHandlers;
61
+ private readonly resetHandlers;
62
+ private readonly profileHandlers;
63
+ private readonly target;
64
+ private readonly provider;
65
+ private readonly listeners;
66
+ private status;
67
+ constructor(opts: InputMapOptions);
68
+ private get accepting();
69
+ private get profile();
70
+ get activeProfile(): string | undefined;
71
+ get gamepadStatus(): "available" | "unavailable" | "blocked";
72
+ profileNames(): string[];
73
+ /** Detached, serializable copy for custom editors and host-managed persistence. */
74
+ getProfile(...selection: [name?: string]): InputProfile;
75
+ /** Atomically validate and replace bindings; no held button becomes a new action. */
76
+ defineProfile(name: string | undefined, profile: InputProfile): void;
77
+ /** Undefined selects the root bindings. Held keys/buttons must be released before reuse. */
78
+ setProfile(name: string | undefined): void;
79
+ /** Snapshot of all detected devices and raw values, suitable for an axis/button inspector. */
80
+ devices(): InputGamepad[];
81
+ /** Poll fresh browser objects; unplugging or losing permission releases affected controls. */
82
+ update(): void;
83
+ /** Suspend while editing a form/menu; device discovery continues during update(). */
84
+ setEnabled(enabled: boolean): void;
85
+ /** Temporarily suppress gameplay while a remapping UI is open; returned release is idempotent. */
86
+ suspend(): Unsubscribe;
87
+ private attach;
88
+ press(code: string): void;
89
+ release(code: string): void;
90
+ /**
91
+ * Drive an action from a software control such as a touch joystick or an on-screen button.
92
+ * `source` names the control so several can feed one action; like every device, the strongest
93
+ * contribution wins. A value persists until changed, `clearVirtual`, or a reset (focus loss,
94
+ * suspension, profile switch), and is ignored while input is not accepted.
95
+ */
96
+ setVirtual(source: string, action: string, value: number): void;
97
+ /** Release every action a software control drives (all controls when `source` is omitted). */
98
+ clearVirtual(source?: string): void;
99
+ /** Numeric action value; strongest absolute contribution wins, keyboard wins ties. */
100
+ value(action: string): number;
101
+ isActive(action: string): boolean;
102
+ activeActions(): Set<string>;
103
+ private contribute;
104
+ private recompute;
105
+ private commit;
106
+ /** Release actions immediately; suppress held physical buttons until released. */
107
+ reset(): void;
108
+ private subscribe;
109
+ onPress(action: string, handler: (action: string) => void): Unsubscribe;
110
+ onRelease(action: string, handler: (action: string) => void): Unsubscribe;
111
+ /** Action values changed (including neutralization on reset/profile switch). */
112
+ onChange(handler: () => void): Unsubscribe;
113
+ /** Explicit neutralization on reset, focus loss, suspension or profile replacement. */
114
+ onReset(handler: () => void): Unsubscribe;
115
+ /** Profile selection or definitions changed. */
116
+ onProfilesChanged(handler: () => void): Unsubscribe;
117
+ dispose(): void;
118
+ }
119
+ //#endregion
120
+ export { normalizeInputAxis as a, InputMapOptions as i, InputGamepad as n, resolveAction as o, InputMap as r, InputBindings as t };
@@ -0,0 +1,361 @@
1
+ import { inputProfileIssues, inputProfileSchema } from "@bendyline/molen-schema";
2
+ //#region src/input.ts
3
+ /** Resolve a key or Mouse<button> code to its bound action. */
4
+ function resolveAction(bindings, code) {
5
+ return Object.hasOwn(bindings, code) ? bindings[code] : void 0;
6
+ }
7
+ function copyProfile(profile) {
8
+ const result = inputProfileSchema.parse(profile);
9
+ const issues = inputProfileIssues(result);
10
+ if (issues.length) throw new Error(issues[0]?.message);
11
+ return result;
12
+ }
13
+ function matches(device, pad) {
14
+ return (device?.id === void 0 || device.id === pad.id) && (device?.index === void 0 || device.index === pad.index);
15
+ }
16
+ /** Calibrate and shape a raw axis. Invalid/non-finite hardware readings are neutral. */
17
+ function normalizeInputAxis(raw, binding) {
18
+ if (!Number.isFinite(raw)) return 0;
19
+ const min = binding.min ?? -1;
20
+ const max = binding.max ?? 1;
21
+ const center = binding.center ?? 0;
22
+ let value = binding.mode === "unit" ? (raw - min) / (max - min) : raw >= center ? (raw - center) / (max - center) : (raw - center) / (center - min);
23
+ value = Math.max(binding.mode === "unit" ? 0 : -1, Math.min(1, value));
24
+ if (binding.invert) value = binding.mode === "unit" ? 1 - value : -value;
25
+ if (binding.mode === "positive") value = Math.max(0, value);
26
+ if (binding.mode === "negative") value = Math.max(0, -value);
27
+ const zone = binding.deadZone ?? (binding.mode === "unit" ? 0 : .12);
28
+ const magnitude = Math.max(0, (Math.abs(value) - zone) / (1 - zone));
29
+ return Math.sign(value) * magnitude ** (binding.curve ?? 1);
30
+ }
31
+ /**
32
+ * Keyboard/mouse + browser controllers mapped to numeric named actions. Call update() each
33
+ * frame (applyInputRules does this on its poller). Profiles are complete replacements.
34
+ */
35
+ var InputMap = class {
36
+ base;
37
+ profiles = /* @__PURE__ */ new Map();
38
+ current;
39
+ keys = /* @__PURE__ */ new Set();
40
+ blockedKeys = /* @__PURE__ */ new Set();
41
+ blockedButtons = /* @__PURE__ */ new Set();
42
+ baselineButtons = false;
43
+ values = /* @__PURE__ */ new Map();
44
+ padValues = /* @__PURE__ */ new Map();
45
+ /** Software controls (touch joysticks, on-screen buttons): source → action → value. */
46
+ virtualValues = /* @__PURE__ */ new Map();
47
+ pads = [];
48
+ enabled = true;
49
+ disposed = false;
50
+ focused = true;
51
+ suspensions = 0;
52
+ revision = 0;
53
+ pressHandlers = /* @__PURE__ */ new Map();
54
+ releaseHandlers = /* @__PURE__ */ new Map();
55
+ changeHandlers = /* @__PURE__ */ new Set();
56
+ resetHandlers = /* @__PURE__ */ new Set();
57
+ profileHandlers = /* @__PURE__ */ new Set();
58
+ target;
59
+ provider;
60
+ listeners = [];
61
+ status = "unavailable";
62
+ constructor(opts) {
63
+ this.base = copyProfile({
64
+ bindings: opts.bindings,
65
+ axes: opts.axes,
66
+ buttons: opts.buttons
67
+ });
68
+ for (const [name, profile] of Object.entries(opts.profiles ?? {})) this.profiles.set(name, copyProfile(profile));
69
+ if (opts.profile !== void 0 && !this.profiles.has(opts.profile)) throw new Error(`Unknown input profile "${opts.profile}".`);
70
+ this.current = opts.profile;
71
+ this.target = opts.target;
72
+ this.provider = opts.getGamepads ?? (() => typeof navigator !== "undefined" && typeof navigator.getGamepads === "function" ? navigator.getGamepads() : []);
73
+ if (opts.getGamepads || typeof navigator !== "undefined" && typeof navigator.getGamepads === "function") this.status = "available";
74
+ if (this.target) this.attach(this.target);
75
+ }
76
+ get accepting() {
77
+ return this.enabled && this.focused && this.suspensions === 0;
78
+ }
79
+ get profile() {
80
+ return this.current === void 0 ? this.base : this.profiles.get(this.current);
81
+ }
82
+ get activeProfile() {
83
+ return this.current;
84
+ }
85
+ get gamepadStatus() {
86
+ return this.status;
87
+ }
88
+ profileNames() {
89
+ return [...this.profiles.keys()];
90
+ }
91
+ /** Detached, serializable copy for custom editors and host-managed persistence. */
92
+ getProfile(...selection) {
93
+ const name = selection.length === 0 ? this.current : selection[0];
94
+ const profile = name === void 0 ? this.base : this.profiles.get(name);
95
+ if (!profile) throw new Error(`Unknown input profile "${name}".`);
96
+ return copyProfile(profile);
97
+ }
98
+ /** Atomically validate and replace bindings; no held button becomes a new action. */
99
+ defineProfile(name, profile) {
100
+ const next = copyProfile(profile);
101
+ if (name === "") throw new Error("Profile names must not be empty.");
102
+ if (name === void 0) this.base = next;
103
+ else this.profiles.set(name, next);
104
+ if (name === this.current) this.reset();
105
+ for (const fn of this.profileHandlers) fn();
106
+ }
107
+ /** Undefined selects the root bindings. Held keys/buttons must be released before reuse. */
108
+ setProfile(name) {
109
+ if (name !== void 0 && !this.profiles.has(name)) throw new Error(`Unknown input profile "${name}".`);
110
+ if (name === this.current) return;
111
+ this.current = name;
112
+ this.reset();
113
+ for (const fn of this.profileHandlers) fn();
114
+ }
115
+ /** Snapshot of all detected devices and raw values, suitable for an axis/button inspector. */
116
+ devices() {
117
+ return this.pads.map((pad) => ({
118
+ ...pad,
119
+ axes: [...pad.axes],
120
+ buttons: pad.buttons.map((button) => ({ ...button }))
121
+ }));
122
+ }
123
+ /** Poll fresh browser objects; unplugging or losing permission releases affected controls. */
124
+ update() {
125
+ if (this.disposed) return;
126
+ try {
127
+ this.pads = this.provider().filter((pad) => pad?.connected === true).map((pad) => ({
128
+ id: pad.id,
129
+ index: pad.index,
130
+ connected: pad.connected,
131
+ mapping: pad.mapping,
132
+ axes: Array.from(pad.axes),
133
+ buttons: Array.from(pad.buttons, (button) => ({
134
+ pressed: button.pressed,
135
+ value: button.value
136
+ }))
137
+ }));
138
+ if (this.status === "blocked") this.status = "available";
139
+ } catch {
140
+ this.pads = [];
141
+ this.status = "blocked";
142
+ }
143
+ const down = /* @__PURE__ */ new Set();
144
+ for (const pad of this.pads) pad.buttons.forEach((button, index) => {
145
+ if (button.pressed || button.value > 0) down.add(JSON.stringify([
146
+ pad.id,
147
+ pad.index,
148
+ index
149
+ ]));
150
+ });
151
+ if (this.baselineButtons || !this.accepting) for (const key of down) this.blockedButtons.add(key);
152
+ for (const key of this.blockedButtons) if (!down.has(key)) this.blockedButtons.delete(key);
153
+ this.baselineButtons = false;
154
+ this.padValues.clear();
155
+ if (this.accepting) for (const pad of this.pads) {
156
+ for (const binding of this.profile.axes ?? []) {
157
+ const raw = pad.axes[binding.axis];
158
+ if (matches(binding.device, pad) && raw !== void 0) this.contribute(this.padValues, binding.action, normalizeInputAxis(raw, binding));
159
+ }
160
+ for (const binding of this.profile.buttons ?? []) {
161
+ const button = pad.buttons[binding.button];
162
+ const key = JSON.stringify([
163
+ pad.id,
164
+ pad.index,
165
+ binding.button
166
+ ]);
167
+ if (matches(binding.device, pad) && button && !this.blockedButtons.has(key) && (button.value >= (binding.threshold ?? .5) || binding.threshold === void 0 && button.pressed)) this.contribute(this.padValues, binding.action, 1);
168
+ }
169
+ }
170
+ this.recompute();
171
+ }
172
+ /** Suspend while editing a form/menu; device discovery continues during update(). */
173
+ setEnabled(enabled) {
174
+ if (this.enabled === enabled) return;
175
+ this.enabled = enabled;
176
+ this.reset();
177
+ }
178
+ /** Temporarily suppress gameplay while a remapping UI is open; returned release is idempotent. */
179
+ suspend() {
180
+ this.suspensions++;
181
+ this.reset();
182
+ let released = false;
183
+ return () => {
184
+ if (released) return;
185
+ released = true;
186
+ this.suspensions--;
187
+ this.reset();
188
+ };
189
+ }
190
+ attach(target) {
191
+ const editable = (ev) => {
192
+ return !!ev.target?.closest?.("input, textarea, select, button, [contenteditable]:not([contenteditable=\"false\"]), [data-molen-input-editor]");
193
+ };
194
+ const add = (type, fn) => {
195
+ target.addEventListener(type, fn);
196
+ this.listeners.push([type, fn]);
197
+ };
198
+ add("keydown", (ev) => {
199
+ if (!editable(ev)) this.press(ev.code);
200
+ });
201
+ add("keyup", (ev) => this.release(ev.code));
202
+ add("mousedown", (ev) => {
203
+ if (!editable(ev)) this.press(`Mouse${ev.button}`);
204
+ });
205
+ add("mouseup", (ev) => this.release(`Mouse${ev.button}`));
206
+ add("blur", () => {
207
+ this.focused = false;
208
+ this.reset();
209
+ });
210
+ add("focus", () => {
211
+ this.focused = true;
212
+ this.blockedKeys.clear();
213
+ });
214
+ }
215
+ press(code) {
216
+ if (this.disposed || !this.accepting || this.blockedKeys.has(code) || this.keys.has(code)) return;
217
+ this.keys.add(code);
218
+ this.recompute();
219
+ }
220
+ release(code) {
221
+ this.blockedKeys.delete(code);
222
+ if (this.keys.delete(code)) this.recompute();
223
+ }
224
+ /**
225
+ * Drive an action from a software control such as a touch joystick or an on-screen button.
226
+ * `source` names the control so several can feed one action; like every device, the strongest
227
+ * contribution wins. A value persists until changed, `clearVirtual`, or a reset (focus loss,
228
+ * suspension, profile switch), and is ignored while input is not accepted.
229
+ */
230
+ setVirtual(source, action, value) {
231
+ if (this.disposed || !Number.isFinite(value)) return;
232
+ let values = this.virtualValues.get(source);
233
+ if (value === 0) {
234
+ if (values?.delete(action) !== true) return;
235
+ if (values.size === 0) this.virtualValues.delete(source);
236
+ } else {
237
+ if (!this.accepting) return;
238
+ if (values === void 0) {
239
+ values = /* @__PURE__ */ new Map();
240
+ this.virtualValues.set(source, values);
241
+ }
242
+ if (values.get(action) === value) return;
243
+ values.set(action, value);
244
+ }
245
+ this.recompute();
246
+ }
247
+ /** Release every action a software control drives (all controls when `source` is omitted). */
248
+ clearVirtual(source) {
249
+ if (source !== void 0) {
250
+ if (this.virtualValues.delete(source)) this.recompute();
251
+ return;
252
+ }
253
+ if (this.virtualValues.size === 0) return;
254
+ this.virtualValues.clear();
255
+ this.recompute();
256
+ }
257
+ /** Numeric action value; strongest absolute contribution wins, keyboard wins ties. */
258
+ value(action) {
259
+ return this.values.get(action) ?? 0;
260
+ }
261
+ isActive(action) {
262
+ return this.value(action) !== 0;
263
+ }
264
+ activeActions() {
265
+ return new Set(this.values.keys());
266
+ }
267
+ contribute(values, action, value) {
268
+ if (Number.isFinite(value) && Math.abs(value) > Math.abs(values.get(action) ?? 0)) values.set(action, value);
269
+ }
270
+ recompute() {
271
+ const next = /* @__PURE__ */ new Map();
272
+ if (this.accepting) {
273
+ for (const code of this.keys) {
274
+ const action = resolveAction(this.profile.bindings, code);
275
+ if (action !== void 0) this.contribute(next, action, 1);
276
+ }
277
+ for (const [action, value] of this.padValues) this.contribute(next, action, value);
278
+ for (const values of this.virtualValues.values()) for (const [action, value] of values) this.contribute(next, action, value);
279
+ }
280
+ this.commit(next);
281
+ }
282
+ commit(next) {
283
+ const prev = this.values;
284
+ this.values = next;
285
+ const revision = ++this.revision;
286
+ for (const action of new Set([...prev.keys(), ...next.keys()])) {
287
+ const before = prev.get(action) ?? 0;
288
+ const after = next.get(action) ?? 0;
289
+ const handlers = before === 0 && after !== 0 ? this.pressHandlers : before !== 0 && after === 0 ? this.releaseHandlers : void 0;
290
+ for (const fn of handlers?.get(action) ?? []) {
291
+ if (this.revision !== revision) return;
292
+ fn(action);
293
+ }
294
+ }
295
+ if (this.revision !== revision) return;
296
+ if ([...new Set([...prev.keys(), ...next.keys()])].some((action) => prev.get(action) !== next.get(action))) for (const fn of this.changeHandlers) fn();
297
+ }
298
+ /** Release actions immediately; suppress held physical buttons until released. */
299
+ reset() {
300
+ for (const key of this.keys) this.blockedKeys.add(key);
301
+ this.keys.clear();
302
+ this.padValues.clear();
303
+ this.virtualValues.clear();
304
+ this.baselineButtons = true;
305
+ this.commit(/* @__PURE__ */ new Map());
306
+ for (const fn of this.resetHandlers) fn();
307
+ }
308
+ subscribe(map, action, handler) {
309
+ let set = map.get(action);
310
+ if (!set) {
311
+ set = /* @__PURE__ */ new Set();
312
+ map.set(action, set);
313
+ }
314
+ set.add(handler);
315
+ return () => {
316
+ set.delete(handler);
317
+ };
318
+ }
319
+ onPress(action, handler) {
320
+ return this.subscribe(this.pressHandlers, action, handler);
321
+ }
322
+ onRelease(action, handler) {
323
+ return this.subscribe(this.releaseHandlers, action, handler);
324
+ }
325
+ /** Action values changed (including neutralization on reset/profile switch). */
326
+ onChange(handler) {
327
+ this.changeHandlers.add(handler);
328
+ return () => {
329
+ this.changeHandlers.delete(handler);
330
+ };
331
+ }
332
+ /** Explicit neutralization on reset, focus loss, suspension or profile replacement. */
333
+ onReset(handler) {
334
+ this.resetHandlers.add(handler);
335
+ return () => {
336
+ this.resetHandlers.delete(handler);
337
+ };
338
+ }
339
+ /** Profile selection or definitions changed. */
340
+ onProfilesChanged(handler) {
341
+ this.profileHandlers.add(handler);
342
+ return () => {
343
+ this.profileHandlers.delete(handler);
344
+ };
345
+ }
346
+ dispose() {
347
+ if (this.disposed) return;
348
+ this.disposed = true;
349
+ if (this.target) for (const [type, fn] of this.listeners) this.target.removeEventListener(type, fn);
350
+ this.listeners.length = 0;
351
+ this.reset();
352
+ this.pressHandlers.clear();
353
+ this.releaseHandlers.clear();
354
+ this.changeHandlers.clear();
355
+ this.resetHandlers.clear();
356
+ this.profileHandlers.clear();
357
+ this.pads = [];
358
+ }
359
+ };
360
+ //#endregion
361
+ export { normalizeInputAxis as n, resolveAction as r, InputMap as t };
@@ -0,0 +1,127 @@
1
+ import * as THREE from "three";
2
+
3
+ //#region src/markers/marker-image.d.ts
4
+ type CanvasLike = HTMLCanvasElement | OffscreenCanvas;
5
+ interface MarkerImageStyle {
6
+ /** Image edge length in CSS pixels, before border and tail (default 52). */
7
+ size?: number;
8
+ /** Border width in CSS pixels (default 3). */
9
+ borderWidth?: number;
10
+ borderColor?: string;
11
+ /** Corner radius in CSS pixels (default 8). */
12
+ radius?: number;
13
+ /** Pointer tail height in CSS pixels; 0 for none (default 9). */
14
+ tail?: number;
15
+ /** Shadow blur in CSS pixels; 0 for none (default 6). */
16
+ shadow?: number;
17
+ shadowColor?: string;
18
+ /** Resolution multiplier (default 2 for sharp sprites on high-DPI screens). */
19
+ pixelRatio?: number;
20
+ /** Canvas factory; defaults to OffscreenCanvas, then `document.createElement('canvas')`. */
21
+ createCanvas?: (width: number, height: number) => CanvasLike;
22
+ }
23
+ /**
24
+ * Draw `image` (cover-cropped to a square) inside a bordered, rounded frame with an optional tail,
25
+ * returning a canvas ready for `MarkerSpec.image`. Its bottom-center is the pin point.
26
+ */
27
+ declare function composeMarkerImage(image: CanvasImageSource & {
28
+ width: number;
29
+ height: number;
30
+ }, style?: MarkerImageStyle): CanvasLike;
31
+ //#endregion
32
+ //#region src/markers/marker-layer.d.ts
33
+ /** What a marker layer needs from a renderer; `Renderer` satisfies it, tests can fake it. */
34
+ interface MarkerHost {
35
+ readonly camera: THREE.Camera;
36
+ /** Parent for world-space objects (rebased near the camera by the renderer). */
37
+ readonly worldRoot: THREE.Object3D;
38
+ /** Drawing size in CSS pixels. */
39
+ getViewportSize(): [number, number];
40
+ }
41
+ /** An image a marker shows: a canvas, bitmap or image element, or a URL to load. */
42
+ type MarkerImage = TexImageSource | OffscreenCanvas | string;
43
+ interface MarkerSpec {
44
+ id: string;
45
+ /** World X in meters. */
46
+ x: number;
47
+ /** World Z in meters. */
48
+ z: number;
49
+ /** Absolute world height; omit to sit on the ground (`groundHeight` + `elevation`). */
50
+ y?: number;
51
+ /** Meters above the ground when ground-snapped (default 0). */
52
+ elevation?: number;
53
+ image: MarkerImage;
54
+ /** On-screen height in CSS pixels (default 56). */
55
+ size?: number;
56
+ /** Which image point sits on the position: `'bottom'` for pins (default), or `'center'`. */
57
+ anchor?: "bottom" | "center";
58
+ /** Higher priority markers are kept first when over budget (default 0). */
59
+ priority?: number;
60
+ }
61
+ interface MarkerLayerOptions {
62
+ /** Ground height at world X/Z, or undefined while unknown. Required for ground-snapped markers. */
63
+ groundHeight?: (x: number, z: number) => number | undefined;
64
+ /** Most markers drawn at once; extras nearest last are hidden (default 256). */
65
+ maxVisible?: number;
66
+ /** Distances (meters) over which markers fade out: full at `near`, gone at `far`. */
67
+ fade?: {
68
+ near: number;
69
+ far: number;
70
+ };
71
+ /** Hide markers behind terrain and buildings (default true). */
72
+ occlude?: boolean;
73
+ /** Hide ground-snapped markers until their ground height is known (default true). */
74
+ hideUntilGrounded?: boolean;
75
+ renderOrder?: number;
76
+ }
77
+ interface MarkerScreenPosition {
78
+ /** CSS pixels from the viewport's left edge. */
79
+ x: number;
80
+ /** CSS pixels from the viewport's top edge. */
81
+ y: number;
82
+ /** Distance from the camera in meters. */
83
+ distance: number;
84
+ /** In front of the camera and inside the viewport. */
85
+ visible: boolean;
86
+ }
87
+ /**
88
+ * Project an absolute world position (the coordinates you give markers and cameras) to CSS
89
+ * pixels, accounting for the renderer's floating-origin rebase.
90
+ */
91
+ declare function projectWorldToScreen(host: MarkerHost, position: readonly [number, number, number]): MarkerScreenPosition;
92
+ /** A group of screen-sized world markers; add markers with `set`, advance with `update`. */
93
+ declare class MarkerLayer {
94
+ private readonly host;
95
+ private readonly options;
96
+ readonly object: THREE.Group;
97
+ private readonly entries;
98
+ private readonly textures;
99
+ private readonly loader;
100
+ private visible;
101
+ private disposed;
102
+ constructor(host: MarkerHost, options?: MarkerLayerOptions);
103
+ /** Replace the marker set. Markers are matched by id, so unchanged images are not reloaded. */
104
+ set(markers: readonly MarkerSpec[]): void;
105
+ /** Marker ids currently in the layer. */
106
+ ids(): string[];
107
+ /**
108
+ * Per frame: snap to ground, fade, budget, and size markers for the current camera. Pass the
109
+ * camera's absolute world position (the one given to `setCamera`).
110
+ */
111
+ update(cameraPosition: readonly [number, number, number]): void;
112
+ /** The front-most drawn marker under a CSS-pixel point, if any. */
113
+ pick(x: number, y: number): string | undefined;
114
+ /** Where a marker's anchor point appears on screen (for DOM callouts), if it exists. */
115
+ screenPosition(id: string): MarkerScreenPosition | undefined;
116
+ setVisible(visible: boolean): void;
117
+ dispose(): void;
118
+ private worldPerPixel;
119
+ private create;
120
+ private remove;
121
+ private acquire;
122
+ private release;
123
+ }
124
+ /** Create a marker layer and attach it under the host's world root. */
125
+ declare function createMarkerLayer(host: MarkerHost, options?: MarkerLayerOptions): MarkerLayer;
126
+ //#endregion
127
+ export { type MarkerHost, type MarkerImage, type MarkerImageStyle, MarkerLayer, type MarkerLayerOptions, type MarkerScreenPosition, type MarkerSpec, composeMarkerImage, createMarkerLayer, projectWorldToScreen };