laymur 0.2.11 → 0.2.13

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,4 +1,3 @@
1
- import type { WebGLRenderer } from "three";
2
1
  import { type Object3D } from "three";
3
2
  import type { UILayer } from "../layers/UILayer";
4
3
  import type { UILayerElement, UIPlaneElement } from "../miscellaneous/asserts";
@@ -130,15 +129,4 @@ export declare abstract class UIElement<T extends Object3D = Object3D> extends U
130
129
  * @returns True if the click was handled by this element
131
130
  */
132
131
  protected ["onClickInternal"](x: number, y: number): boolean;
133
- /**
134
- * Internal method called before rendering each frame.
135
- *
136
- * This is a hook method that can be overridden by subclasses to perform
137
- * pre-render operations such as updating animations, transforms, or
138
- * other dynamic properties.
139
- *
140
- * @param renderer - The WebGL renderer instance
141
- * @param deltaTime - Time elapsed since the last frame in seconds
142
- */
143
- protected ["onBeforeRenderInternal"](renderer: WebGLRenderer, deltaTime: number): void;
144
132
  }
@@ -1,11 +1,143 @@
1
- import type { Texture, WebGLRenderer } from "three";
1
+ import type { Texture } from "three";
2
2
  import { Mesh } from "three";
3
- import type { UILayer } from "../layers/UILayer";
3
+ import { type UILayer } from "../layers/UILayer";
4
+ import { type UINineSliceBorder } from "../miscellaneous/UINineSliceBorder";
4
5
  import { UIElement } from "./UIElement";
6
+ /**
7
+ * Configuration options for creating a UINineSlice element.
8
+ */
9
+ export interface UINineSliceOptions {
10
+ /** Nine-slice border configuration (can be number, object with horizontal/vertical, or full border object) */
11
+ sliceBorder: UINineSliceBorder;
12
+ /** X position of the element */
13
+ x: number;
14
+ /** Y position of the element */
15
+ y: number;
16
+ }
17
+ /**
18
+ * Nine-slice UI element for scalable images with preserved border regions.
19
+ *
20
+ * Nine-slice scaling divides an image into 9 regions: 4 corners, 4 edges, and 1 center.
21
+ * The corners maintain their original size, edges scale in one dimension, and the center
22
+ * scales in both dimensions. This technique is commonly used for creating scalable UI
23
+ * panels, buttons, and borders that maintain visual quality at any size.
24
+ */
5
25
  export declare class UINineSlice extends UIElement<Mesh> {
6
26
  private readonly material;
7
27
  private readonly textureInternal;
8
- constructor(layer: UILayer, texture: Texture, x?: number, y?: number);
28
+ /**
29
+ * Creates a new nine-slice UI element.
30
+ *
31
+ * @param layer - The UI layer to add this element to
32
+ * @param texture - The texture to use for nine-slice rendering
33
+ * @param options - Configuration options for the nine-slice element
34
+ */
35
+ constructor(layer: UILayer, texture: Texture, options?: Partial<UINineSliceOptions>);
36
+ /**
37
+ * Gets the left border size for nine-slice scaling.
38
+ * @returns The left border size in texture UV coordinates
39
+ */
40
+ get sliceBorderLeft(): number;
41
+ /**
42
+ * Gets the right border size for nine-slice scaling.
43
+ * @returns The right border size in texture UV coordinates
44
+ */
45
+ get sliceBorderRight(): number;
46
+ /**
47
+ * Gets the top border size for nine-slice scaling.
48
+ * @returns The top border size in texture UV coordinates
49
+ */
50
+ get sliceBorderTop(): number;
51
+ /**
52
+ * Gets the bottom border size for nine-slice scaling.
53
+ * @returns The bottom border size in texture UV coordinates
54
+ */
55
+ get sliceBorderBottom(): number;
56
+ /**
57
+ * Gets the current texture being displayed.
58
+ * @returns The current Three.js texture
59
+ */
60
+ get texture(): Texture;
61
+ /**
62
+ * Gets the current color tint applied to the image.
63
+ * @returns The color value as a number (e.g., 0xFFFFFF for white)
64
+ */
65
+ get color(): number;
66
+ /**
67
+ * Gets the current opacity level of the image.
68
+ * @returns The opacity value between 0.0 (transparent) and 1.0 (opaque)
69
+ */
70
+ get opacity(): number;
71
+ /**
72
+ * Gets whether transparency is enabled for the image.
73
+ * @returns True if transparency is enabled, false otherwise
74
+ */
75
+ get transparency(): boolean;
76
+ /**
77
+ * Sets the left border size for nine-slice scaling.
78
+ * @param value - The left border size in texture UV coordinates
79
+ */
80
+ set sliceBorderLeft(value: number);
81
+ /**
82
+ * Sets the right border size for nine-slice scaling.
83
+ * @param value - The right border size in texture UV coordinates
84
+ */
85
+ set sliceBorderRight(value: number);
86
+ /**
87
+ * Sets the top border size for nine-slice scaling.
88
+ * @param value - The top border size in texture UV coordinates
89
+ */
90
+ set sliceBorderTop(value: number);
91
+ /**
92
+ * Sets the bottom border size for nine-slice scaling.
93
+ * @param value - The bottom border size in texture UV coordinates
94
+ */
95
+ set sliceBorderBottom(value: number);
96
+ /**
97
+ * Sets a new texture for the image.
98
+ *
99
+ * When setting a new texture, the image will automatically resize to match
100
+ * the new texture's dimensions.
101
+ *
102
+ * @param value - The new Three.js texture to display
103
+ * @throws Will throw an error if the texture dimensions are not valid positive numbers
104
+ * @see {@link assertValidPositiveNumber}
105
+ */
106
+ set texture(value: Texture);
107
+ /**
108
+ * Sets the color tint applied to the image.
109
+ * @param value - The color value as a number (e.g., 0xFFFFFF for white)
110
+ */
111
+ set color(value: number);
112
+ /**
113
+ * Sets the opacity level of the image.
114
+ * @param value - The opacity value between 0.0 (transparent) and 1.0 (opaque)
115
+ */
116
+ set opacity(value: number);
117
+ /**
118
+ * Sets whether transparency is enabled for the image.
119
+ * @param value - True to enable transparency, false to disable
120
+ */
121
+ set transparency(value: boolean);
122
+ /**
123
+ * Sets all four border sizes for nine-slice scaling at once.
124
+ *
125
+ * @param left - The left border size in texture UV coordinates
126
+ * @param right - The right border size in texture UV coordinates
127
+ * @param top - The top border size in texture UV coordinates
128
+ * @param bottom - The bottom border size in texture UV coordinates
129
+ */
130
+ setSliceBorders(left: number, right: number, top: number, bottom: number): void;
131
+ /**
132
+ * Destroys the nine-slice element and cleans up resources.
133
+ *
134
+ * This method removes event listeners, disposes of the material,
135
+ * and calls the parent destroy method.
136
+ */
9
137
  destroy(): void;
10
- protected ["onBeforeRenderInternal"](renderer: WebGLRenderer, deltaTime: number): void;
138
+ /**
139
+ * Internal render callback that updates the material's quad size.
140
+ * This ensures the nine-slice scaling works correctly with micro transformations.
141
+ */
142
+ private readonly onWillRenderInternal;
11
143
  }
@@ -2,38 +2,160 @@ import type { Texture } from "three";
2
2
  import { Mesh } from "three";
3
3
  import type { UILayer } from "../layers/UILayer";
4
4
  import { UIElement } from "./UIElement";
5
+ /**
6
+ * Configuration options for creating a UIProgress element.
7
+ */
5
8
  export interface UIProgressOptions {
9
+ /** X position of the element */
6
10
  x: number;
11
+ /** Y position of the element */
7
12
  y: number;
13
+ /** Optional background texture (if not provided, only foreground is shown) */
8
14
  textureBackground: Texture;
15
+ /** Progress value between 0.0 (empty) and 1.0 (full) */
9
16
  progress: number;
10
- isForegroundDirection: boolean;
17
+ /** Direction of progress fill (true = forward, false = reverse) */
18
+ isForwardDirection: boolean;
19
+ /** Angle of progress fill in degrees (0 = horizontal, 90 = vertical) */
11
20
  angle: number;
21
+ /** Background color tint as hex number (e.g., 0xFFFFFF) */
12
22
  backgroundColor: number;
23
+ /** Foreground color tint as hex number (e.g., 0xFFFFFF) */
13
24
  foregroundColor: number;
25
+ /** Background opacity between 0.0 (transparent) and 1.0 (opaque) */
14
26
  backgroundOpacity: number;
27
+ /** Foreground opacity between 0.0 (transparent) and 1.0 (opaque) */
15
28
  foregroundOpacity: number;
16
29
  }
30
+ /**
31
+ * Progress bar UI element with customizable fill direction and appearance.
32
+ *
33
+ * UIProgress displays a progress bar that can be filled in various directions
34
+ * (horizontal, vertical, or at custom angles). It supports separate background
35
+ * and foreground textures with independent color tinting and opacity control.
36
+ *
37
+ * The progress value ranges from 0.0 (empty) to 1.0 (completely filled).
38
+ * The fill direction can be controlled both by angle and forward/reverse direction.
39
+ */
17
40
  export declare class UIProgress extends UIElement<Mesh> {
18
41
  private readonly material;
42
+ /**
43
+ * Creates a new progress bar UI element.
44
+ *
45
+ * @param layer - The UI layer to add this element to
46
+ * @param textureForeground - The texture used for the progress fill
47
+ * @param options - Configuration options for the progress bar
48
+ */
19
49
  constructor(layer: UILayer, textureForeground: Texture, options?: Partial<UIProgressOptions>);
50
+ /**
51
+ * Gets the current progress value.
52
+ * @returns Progress value between 0.0 (empty) and 1.0 (full)
53
+ */
20
54
  get progress(): number;
55
+ /**
56
+ * Gets the background texture.
57
+ * @returns The background texture, or undefined if none is set
58
+ */
21
59
  get backgroundTexture(): Texture | undefined;
60
+ /**
61
+ * Gets the foreground (fill) texture.
62
+ * @returns The foreground texture
63
+ */
22
64
  get foregroundTexture(): Texture;
65
+ /**
66
+ * Gets the background color tint.
67
+ * @returns The background color as a hex number (e.g., 0xFFFFFF)
68
+ */
23
69
  get backgroundColor(): number;
70
+ /**
71
+ * Gets the foreground color tint.
72
+ * @returns The foreground color as a hex number (e.g., 0xFFFFFF)
73
+ */
24
74
  get foregroundColor(): number;
75
+ /**
76
+ * Gets the background opacity.
77
+ * @returns Opacity value between 0.0 (transparent) and 1.0 (opaque)
78
+ */
25
79
  get backgroundOpacity(): number;
80
+ /**
81
+ * Gets the foreground opacity.
82
+ * @returns Opacity value between 0.0 (transparent) and 1.0 (opaque)
83
+ */
26
84
  get foregroundOpacity(): number;
85
+ /**
86
+ * Gets whether transparency is enabled for the image.
87
+ * @returns True if transparency is enabled, false otherwise
88
+ */
89
+ get transparency(): boolean;
90
+ /**
91
+ * Gets the progress fill angle in degrees.
92
+ * @returns Angle in degrees (0 = horizontal, 90 = vertical)
93
+ */
27
94
  get angle(): number;
95
+ /**
96
+ * Gets whether the progress fills in forward direction.
97
+ * @returns True if filling forward, false if filling in reverse
98
+ */
28
99
  get isForwardDirection(): boolean;
100
+ /**
101
+ * Sets the progress value.
102
+ * @param value - Progress value between 0.0 (empty) and 1.0 (full)
103
+ */
29
104
  set progress(value: number);
105
+ /**
106
+ * Sets the background texture.
107
+ * @param value - The background texture, or undefined to remove background
108
+ */
30
109
  set backgroundTexture(value: Texture | undefined);
110
+ /**
111
+ * Sets the foreground (fill) texture.
112
+ *
113
+ * When setting a new texture, the progress bar will automatically resize
114
+ * to match the new texture's dimensions.
115
+ *
116
+ * @param value - The new foreground texture
117
+ * @throws Will throw an error if the texture dimensions are not valid positive numbers
118
+ */
31
119
  set foregroundTexture(value: Texture);
120
+ /**
121
+ * Sets the background color tint.
122
+ * @param value - The background color as a hex number (e.g., 0xFFFFFF)
123
+ */
32
124
  set backgroundColor(value: number);
125
+ /**
126
+ * Sets the foreground color tint.
127
+ * @param value - The foreground color as a hex number (e.g., 0xFFFFFF)
128
+ */
33
129
  set foregroundColor(value: number);
130
+ /**
131
+ * Sets the background opacity.
132
+ * @param value - Opacity value between 0.0 (transparent) and 1.0 (opaque)
133
+ */
34
134
  set backgroundOpacity(value: number);
135
+ /**
136
+ * Sets the foreground opacity.
137
+ * @param value - Opacity value between 0.0 (transparent) and 1.0 (opaque)
138
+ */
35
139
  set foregroundOpacity(value: number);
140
+ /**
141
+ * Sets whether transparency is enabled for the image.
142
+ * @param value - True to enable transparency, false to disable
143
+ */
144
+ set transparency(value: boolean);
145
+ /**
146
+ * Sets the progress fill angle.
147
+ * @param value - Angle in degrees (0 = horizontal, 90 = vertical)
148
+ */
36
149
  set angle(value: number);
150
+ /**
151
+ * Sets the progress fill direction.
152
+ * @param value - True for forward direction, false for reverse
153
+ */
37
154
  set isForwardDirection(value: boolean);
155
+ /**
156
+ * Destroys the progress bar element and cleans up resources.
157
+ *
158
+ * This method disposes of the material and calls the parent destroy method.
159
+ */
38
160
  destroy(): void;
39
161
  }
@@ -1,6 +1,6 @@
1
- import type { Camera, WebGLRenderer } from "three";
1
+ import type { Camera } from "three";
2
2
  import { Mesh, Scene } from "three";
3
- import type { UILayer } from "../layers/UILayer";
3
+ import { type UILayer } from "../layers/UILayer";
4
4
  import { UIElement } from "./UIElement";
5
5
  /**
6
6
  * Update modes for controlling when the 3D scene should be re-rendered.
@@ -196,14 +196,5 @@ export declare class UIScene extends UIElement<Mesh> {
196
196
  * want to trigger a scene re-render without changing any properties.
197
197
  */
198
198
  requestRender(): void;
199
- /**
200
- * Internal method called before rendering each frame.
201
- *
202
- * This method handles the conditional rendering of the 3D scene based on
203
- * the current update mode. It manages frame counting, property change detection,
204
- * and manual render requests to optimize performance.
205
- *
206
- * @param renderer - The WebGL renderer instance
207
- */
208
- protected ["onBeforeRenderInternal"](renderer: WebGLRenderer): void;
199
+ private readonly onWillRenderInternal;
209
200
  }
@@ -1,6 +1,5 @@
1
- import type { WebGLRenderer } from "three";
2
1
  import { Mesh } from "three";
3
- import type { UILayer } from "../layers/UILayer";
2
+ import { type UILayer } from "../layers/UILayer";
4
3
  import type { UITextContent } from "../miscellaneous/textInterfaces";
5
4
  import { type UITextPadding } from "../miscellaneous/UITextPadding";
6
5
  import { type UITextStyle } from "../miscellaneous/UITextStyle";
@@ -15,6 +14,10 @@ export interface UITextOptions {
15
14
  padding: Partial<UITextPadding>;
16
15
  /** Common style properties applied to all text content. */
17
16
  commonStyle: Partial<UITextStyle>;
17
+ /** X-coordinate of the text element. */
18
+ x: number;
19
+ /** Y-coordinate of the text element. */
20
+ y: number;
18
21
  }
19
22
  /**
20
23
  * UI element for rendering dynamic text with canvas-based rendering.
@@ -65,7 +68,7 @@ export declare class UIText extends UIElement<Mesh> {
65
68
  * @param y - Initial y-coordinate position (defaults to 0)
66
69
  * @throws Will throw an error if canvas context creation fails
67
70
  */
68
- constructor(layer: UILayer, content: UITextContent, options?: Partial<UITextOptions>, x?: number, y?: number);
71
+ constructor(layer: UILayer, content: UITextContent, options?: Partial<UITextOptions>);
69
72
  /**
70
73
  * Gets the current color tint applied to the text.
71
74
  * @returns The color value as a number (e.g., 0xFFFFFF for white)
@@ -145,17 +148,7 @@ export declare class UIText extends UIElement<Mesh> {
145
148
  * the text element should not be used anymore.
146
149
  */
147
150
  destroy(): void;
148
- /**
149
- * Internal method called before rendering each frame.
150
- *
151
- * Updates the element's height to maintain the correct aspect ratio
152
- * based on the text content dimensions. This ensures the text is
153
- * displayed without distortion.
154
- *
155
- * @param renderer - The WebGL renderer instance
156
- * @param deltaTime - Time elapsed since the last frame in seconds
157
- */
158
- protected ["onBeforeRenderInternal"](renderer: WebGLRenderer, deltaTime: number): void;
151
+ private readonly onWillRenderInternal;
159
152
  /**
160
153
  * Rebuilds the text canvas and texture based on current content and settings.
161
154
  *