@evitcastudio/kit 3.8.0 → 3.9.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.
@@ -243,9 +243,9 @@ declare global {
243
243
  */
244
244
  autoZoomMulti?: number;
245
245
  /**
246
- * When true, prevents the map view from automatically scaling with the window.
246
+ * When true, prevents the map view from automatically scaling with the window. Can also be set to `'fit'` to fit the viewport.
247
247
  */
248
- preventAutoScale?: boolean;
248
+ preventAutoScale?: boolean | 'fit';
249
249
  /**
250
250
  * When true, prevents automatic resize recalculations on window resize.
251
251
  */
@@ -1011,6 +1011,135 @@ declare global {
1011
1011
  */
1012
1012
  sendDiob(pD: Diob, pVar?: string | string[]): void
1013
1013
 
1014
+ /**
1015
+ * If true, requires connected players to have a valid Vylocity account rather than guest accounts.
1016
+ *
1017
+ * @env Client | Server
1018
+ */
1019
+ requireAccount?: boolean
1020
+
1021
+ /**
1022
+ * If true, prevents the server from automatically initiating/hosting the server socket on startup.
1023
+ *
1024
+ * @env Server
1025
+ */
1026
+ preventAutoHost?: boolean
1027
+
1028
+ /**
1029
+ * If true, enables server-side position and property transitions to be processed and synced.
1030
+ *
1031
+ * @env Server
1032
+ */
1033
+ allowServerTransitions?: boolean
1034
+
1035
+ /**
1036
+ * Manually starts hosting the server on the specified port. Overrides `World.mainPort` if provided.
1037
+ *
1038
+ * @env Server
1039
+ * @param {number} [pPort] - Port number to listen on.
1040
+ */
1041
+ hostServer(pPort?: number): void
1042
+
1043
+ /**
1044
+ * Initializes the Steamworks API wrapper if running in the desktop executable environment. Returns true on success.
1045
+ *
1046
+ * @env Client
1047
+ * @returns {boolean} Whether Steam API initialization succeeded.
1048
+ */
1049
+ openSteamAPI(): boolean
1050
+
1051
+ /**
1052
+ * Returns the address of the connected server or 'localhost'.
1053
+ *
1054
+ * @env Client | Server
1055
+ * @returns {string} Server address string.
1056
+ */
1057
+ getServerAddress(): string
1058
+
1059
+ /**
1060
+ * Sends an asynchronous HTTP fetch request using the fetch API and returns the response Promise.
1061
+ *
1062
+ * @env Client | Server
1063
+ * @param {string} pURL - Request destination URL.
1064
+ * @param {any} [pData] - Request options/payload object.
1065
+ * @returns {Promise<any>} Response promise.
1066
+ */
1067
+ sendWebRequest(pURL: string, pData?: any): Promise<any>
1068
+
1069
+ /**
1070
+ * Maximum allowable payload size in bytes for POST requests to the `/api?post` endpoint. Defaults to `5000000` (5MB).
1071
+ *
1072
+ * @env Client | Server
1073
+ */
1074
+ maxPostSize: number
1075
+
1076
+ /**
1077
+ * Maximum allowable file upload size in bytes for requests to the `/api?upload` endpoint. Defaults to `5000000` (5MB).
1078
+ *
1079
+ * @env Client | Server
1080
+ */
1081
+ maxUploadFilesize: number
1082
+
1083
+ /**
1084
+ * Event invoked when a POST request is received at `/api?post`.
1085
+ *
1086
+ * @env Server
1087
+ * @param {Buffer | any} pPost - Received body data chunk buffer.
1088
+ * @param {string} pFrom - Client IP address string.
1089
+ * @param {Record<string, string>} pHeaders - HTTP request headers.
1090
+ * @param {(pResult?: any) => void} [pCallback] - Optional callback to send response.
1091
+ * @returns {any} Optional return value sent directly as response if not using callback.
1092
+ */
1093
+ onPost?(pPost: Buffer | any, pFrom: string, pHeaders: Record<string, string>, pCallback?: (pResult?: any) => void): any
1094
+
1095
+ /**
1096
+ * Returns the Icon object corresponding to the specified atlas, icon name, state, and frame.
1097
+ *
1098
+ * @env Client | Server
1099
+ * @param {string} pAtlas - Icon atlas name.
1100
+ * @param {string} [pIcon] - Icon name.
1101
+ * @param {string} [pState] - Icon state name.
1102
+ * @param {number} [pFrame] - Optional frame index.
1103
+ * @returns {Icon | any} The matching icon instance.
1104
+ */
1105
+ getIcon(pAtlas: string, pIcon?: string, pState?: string, pFrame?: number): Icon | any
1106
+
1107
+ /**
1108
+ * Returns or creates the IconAtlas instance for the specified atlas name.
1109
+ *
1110
+ * @env Client | Server
1111
+ * @param {string} pAtlas - Icon atlas name.
1112
+ * @returns {IconAtlas} Icon atlas instance.
1113
+ */
1114
+ getIconAtlas(pAtlas: string): IconAtlas
1115
+
1116
+ /**
1117
+ * Creates a new Icon instance in the specified atlas.
1118
+ *
1119
+ * @env Client | Server
1120
+ * @param {string} pAtlas - Target atlas name.
1121
+ * @param {string} pIcon - Icon name.
1122
+ * @param {string} [pState] - Initial state name.
1123
+ * @param {number} [pW] - Width in pixels.
1124
+ * @param {number} [pH] - Height in pixels.
1125
+ * @param {number} [pDelay] - Frame delay in milliseconds.
1126
+ * @param {any} [pData] - Texture or image data.
1127
+ * @returns {Icon | any} Newly created Icon.
1128
+ */
1129
+ newIcon(pAtlas: string, pIcon: string, pState?: string, pW?: number, pH?: number, pDelay?: number, pData?: any): Icon | any
1130
+
1131
+ /**
1132
+ * Creates a new Icon loaded directly from an image URL.
1133
+ *
1134
+ * @env Client | Server
1135
+ * @param {string} pData - Image URL or data URL.
1136
+ * @param {number} [pW] - Width in pixels.
1137
+ * @param {number} [pH] - Height in pixels.
1138
+ * @param {number} [pDelay] - Frame delay in milliseconds.
1139
+ * @returns {Icon | any} Newly created Icon.
1140
+ */
1141
+ newIconFromURL(pData: string, pW?: number, pH?: number, pDelay?: number): Icon | any
1142
+
1014
1143
  }
1015
1144
 
1016
1145
 
@@ -1025,6 +1154,41 @@ declare global {
1025
1154
  */
1026
1155
  inTicker: object
1027
1156
 
1157
+ /**
1158
+ * The ticker object instance attached to this object (`_vy_tickerOb`).
1159
+ *
1160
+ * @env Client | Server
1161
+ */
1162
+ tickerOb: any;
1163
+
1164
+ /**
1165
+ * The root base type string in this object's type hierarchy (e.g. `'Diob'`, `'Mob'`, `'Tile'`, `'Client'`).
1166
+ *
1167
+ * @env Client | Server
1168
+ */
1169
+ readonly baseType: string;
1170
+
1171
+ /**
1172
+ * The immediate parent type string this object type inherits from.
1173
+ *
1174
+ * @env Client | Server
1175
+ */
1176
+ readonly parentType: string;
1177
+
1178
+ /**
1179
+ * The leaf type string of this object (the most derived type).
1180
+ *
1181
+ * @env Client | Server
1182
+ */
1183
+ readonly ownType: string;
1184
+
1185
+ /**
1186
+ * Reference to the internal ObjectType descriptor structure representing this object's type (`_vy_parentT`).
1187
+ *
1188
+ * @env Client | Server
1189
+ */
1190
+ readonly typeOb: ObjectType;
1191
+
1028
1192
  /**
1029
1193
  * Sets the `pVal` value of the `pVar` static variable belonging to the type `pType`. Static variables are variables that belong to all Objects of this type collectively and are different than normal variables, usually static variables can only be set once, but VyScript static variables may be changed if that is what the developer wants.
1030
1194
  *
@@ -1047,6 +1211,142 @@ declare global {
1047
1211
 
1048
1212
 
1049
1213
 
1214
+ /**
1215
+ * Represents the runtime type metadata and prototype descriptor for an Object type in the Vylocity type system.
1216
+ */
1217
+ interface ObjectType {
1218
+
1219
+ /**
1220
+ * Read-only boolean flag indicating this is an ObjectType descriptor.
1221
+ *
1222
+ * @env Client | Server
1223
+ */
1224
+ readonly isObjectType?: boolean;
1225
+
1226
+ /**
1227
+ * The leaf type string of this ObjectType (the short type name without parent paths).
1228
+ *
1229
+ * @env Client | Server
1230
+ */
1231
+ readonly ownType: string;
1232
+
1233
+ /**
1234
+ * Array of type strings that this ObjectType inherits from.
1235
+ *
1236
+ * @env Client | Server
1237
+ */
1238
+ readonly inherits: string[];
1239
+
1240
+ /**
1241
+ * Record of static variables defined on this ObjectType.
1242
+ *
1243
+ * @env Client | Server
1244
+ */
1245
+ readonly staticVars: Record<string, any>;
1246
+
1247
+ /**
1248
+ * Destroys this ObjectType and unregisters it from the engine's type registry.
1249
+ *
1250
+ * @env Client | Server
1251
+ */
1252
+ destroy(): void;
1253
+
1254
+ /**
1255
+ * Adds a type path `pType` to this ObjectType's inheritance list.
1256
+ *
1257
+ * @env Client | Server
1258
+ * @param {string} pType - Type path to inherit.
1259
+ * @returns {ObjectType} The inherited ObjectType descriptor.
1260
+ */
1261
+ addInherit(pType: string): ObjectType;
1262
+
1263
+ /**
1264
+ * Removes an inherited type path `pInherit` from this ObjectType.
1265
+ *
1266
+ * @env Client | Server
1267
+ * @param {string} pInherit - Type path to remove.
1268
+ */
1269
+ removeInherit(pInherit: string): void;
1270
+
1271
+ /**
1272
+ * Sets multiple variables on this ObjectType definition simultaneously.
1273
+ *
1274
+ * @env Client | Server
1275
+ * @param {Record<string, any>} pVars - Object containing key-value pairs to set.
1276
+ */
1277
+ setVars(pVars: Record<string, any>): void;
1278
+
1279
+ /**
1280
+ * Sets a variable `pVar` on this ObjectType definition to `pVal`.
1281
+ *
1282
+ * @env Client | Server
1283
+ * @param {string} pVar - Variable name to define.
1284
+ * @param {any} pVal - Value to assign.
1285
+ */
1286
+ setVar(pVar: string, pVal: any): void;
1287
+
1288
+ /**
1289
+ * Retrieves the value of a variable `pVar` defined on this ObjectType.
1290
+ *
1291
+ * @env Client | Server
1292
+ * @param {string} pVar - Variable name to look up.
1293
+ * @param {boolean} [pOwn] - If `true`, only inspect variables defined directly on this type, ignoring parents.
1294
+ * @returns {any} The variable value.
1295
+ */
1296
+ getVar(pVar: string, pOwn?: boolean): any;
1297
+
1298
+ /**
1299
+ * Deletes a variable `pVar` from this ObjectType and propagates the deletion to child types.
1300
+ *
1301
+ * @env Client | Server
1302
+ * @param {string} pVar - Variable name to remove.
1303
+ */
1304
+ delVar(pVar: string): void;
1305
+
1306
+ /**
1307
+ * Sets or overrides a member function `pName` on this ObjectType.
1308
+ *
1309
+ * @env Client | Server
1310
+ * @param {string} pName - Function name.
1311
+ * @param {Function} pFunc - Function implementation.
1312
+ * @param {boolean} [pOverride] - Whether this function completely overrides parent implementations.
1313
+ */
1314
+ setFunc(pName: string, pFunc: Function, pOverride?: boolean): void;
1315
+
1316
+ /**
1317
+ * Retrieves the member function `pName` defined on this ObjectType.
1318
+ *
1319
+ * @env Client | Server
1320
+ * @param {string} pName - Function name.
1321
+ * @param {boolean} [pOwn] - If `true`, only returns function if directly defined on this type.
1322
+ * @returns {Function} The function.
1323
+ */
1324
+ getFunc(pName: string, pOwn?: boolean): Function;
1325
+
1326
+ /**
1327
+ * Sets a static variable `pVar` belonging to this ObjectType to `pVal`.
1328
+ *
1329
+ * @env Client | Server
1330
+ * @param {string} pVar - Static variable name.
1331
+ * @param {any} pVal - Static value.
1332
+ */
1333
+ setStaticVar(pVar: string, pVal: any): void;
1334
+
1335
+ /**
1336
+ * Retrieves the static variable `pVar` belonging to this ObjectType.
1337
+ *
1338
+ * @env Client | Server
1339
+ * @param {string} pVar - Static variable name.
1340
+ * @returns {any} The static value.
1341
+ */
1342
+ getStaticVar(pVar: string): any;
1343
+
1344
+ [key: string]: any;
1345
+
1346
+ }
1347
+
1348
+
1349
+
1050
1350
  /** The diob object. */
1051
1351
  interface Diob {
1052
1352
 
@@ -2239,60 +2539,307 @@ declare global {
2239
2539
  * ```
2240
2540
  */
2241
2541
  mouseOpacity: MouseOpacity | 0 | 1 | 2;
2242
- [key: string]: any
2243
2542
 
2244
- }
2543
+ /**
2544
+ * Read-only boolean flag indicating this object is a Diob.
2545
+ *
2546
+ * @env Client | Server
2547
+ */
2548
+ readonly isDiob: boolean;
2245
2549
 
2550
+ /**
2551
+ * Indicates whether this diob is functioning as an overlay.
2552
+ * Returns the parent Diob if an overlay of another Diob, or a boolean/null.
2553
+ *
2554
+ * @env Client | Server
2555
+ */
2556
+ isOverlay: boolean | Diob | null;
2246
2557
 
2558
+ /**
2559
+ * CLIENT-ONLY. Accesses the underlying PixiJS Sprite instance used to render this diob's icon (`_vy_pixS`).
2560
+ *
2561
+ * @env Client
2562
+ */
2563
+ sprite: any;
2247
2564
 
2248
- /** The movable object. */
2249
- type Movable = {
2565
+ /**
2566
+ * CLIENT-ONLY. Accesses the underlying PixiJS Text instance used to render this diob's text label (`_vy_pixT`).
2567
+ *
2568
+ * @env Client
2569
+ */
2570
+ textSprite: any;
2250
2571
 
2251
2572
  /**
2252
- * Moves movable in the direction of `pDir` using movable's stepSize until told to stop. Takes density into consideration. You can stop movement by calling a different movement function or calling this function with no or `null` arguments.
2573
+ * Color tint applied to this diob's visual sprite (e.g. `0xFFFFFF` for untinted, or a hexadecimal color number).
2253
2574
  *
2254
2575
  * @env Client | Server
2255
- * @param {Direction | string} [pDir] - Direction to move movable in.
2576
+ *
2577
+ * @example
2578
+ * ```ts
2579
+ * diob.tint = 0xff0000; // Red tint
2580
+ * ```
2256
2581
  */
2257
- moveDir(pDir?: Direction | string): void
2582
+ tint: number;
2258
2583
 
2259
- /**
2260
- * Moves the movable by `pX` x pixels and `pY` y pixels until told to stop. Takes obstacles into consideration. You can stop movement by calling a different movement function or calling this function with no or `null` arguments.
2261
- *
2262
- * @env Client | Server
2263
- * @param {number} pX - X value to step by.
2264
- * @param {number} pY - Y value to step by.
2265
- */
2266
- movePos(pX: number, pY: number): void
2584
+ /**
2585
+ * CLIENT-ONLY. Controls whether this diob is subject to screen frustum culling.
2586
+ * When `true` (default), the diob is removed from the active screen display list when outside the viewport.
2587
+ *
2588
+ * @env Client
2589
+ */
2590
+ isCullable: boolean;
2267
2591
 
2268
- /**
2269
- * True if moving using the built-in movement.
2270
- *
2271
- * @env Client | Server
2272
- */
2273
- isMoving: boolean
2592
+ /**
2593
+ * Controls whether this diob is exempt from spatial interest grid tracking and culling on the server.
2594
+ *
2595
+ * @env Server
2596
+ */
2597
+ preventInterest?: boolean;
2274
2598
 
2275
- /**
2276
- * Steps the movable by `pX` x pixels and `pY` y pixels. Takes obstacles into consideration. Returns `true` or `false` depending on if the step was successful.
2277
- *
2278
- * @env Client | Server
2279
- * @param {number} pX - X value to step by.
2280
- * @param {number} pY - Y value to step by.
2281
- * @param {boolean} pGlide - If set, movement will not stop unless move directions are blocked.
2282
- * @param {boolean} pSlide - If set, the step will occur without changing the movable's direction.
2283
- * @returns {void} Returns `true` or `false` depending on if the step was successful.
2284
- */
2285
- stepPos(pX: number, pY: number, pGlide: boolean, pSlide: boolean): void
2599
+ /**
2600
+ * Calculates the screen viewport position of this diob in pixels.
2601
+ *
2602
+ * @env Client
2603
+ * @param {Partial<Point2D>} [pO] - Optional point object to populate with `x` and `y`.
2604
+ * @returns {Point2D} The screen coordinates `{ x, y }` in viewport pixels.
2605
+ *
2606
+ * @example
2607
+ * ```ts
2608
+ * const screenPos = diob.getScreenPos();
2609
+ * console.log(`Diob screen position: (${screenPos.x}, ${screenPos.y})`);
2610
+ * ```
2611
+ */
2612
+ getScreenPos(pO?: Partial<Point2D>): Point2D;
2286
2613
 
2287
- /**
2288
- * Movement settings configuration controlling step size, gliding, sliding, cardinal locking, and step frequency.
2289
- *
2290
- * @env Client | Server
2291
- *
2292
- * @example
2293
- * ```ts
2294
- * movable.moveSettings = {
2295
- * stepSize: 4,
2614
+ /**
2615
+ * Called when a touch point is placed over this diob.
2616
+ *
2617
+ * @env Client | Server
2618
+ * @event
2619
+ * @param {Client} pClient - The client initiating the touch.
2620
+ * @param {number} pX - Horizontal coordinate of the touch relative to the diob.
2621
+ * @param {number} pY - Vertical coordinate of the touch relative to the diob.
2622
+ * @param {TouchEvent} [pEvent] - (Optional) The native browser TouchEvent.
2623
+ */
2624
+ onTouchStart?(pClient: Client, pX: number, pY: number, pEvent?: TouchEvent): void;
2625
+
2626
+ /**
2627
+ * Called when a touch point is removed from over this diob.
2628
+ *
2629
+ * @env Client | Server
2630
+ * @event
2631
+ * @param {Client} pClient - The client whose touch was lifted.
2632
+ * @param {number} pX - Horizontal coordinate of the touch relative to the diob.
2633
+ * @param {number} pY - Vertical coordinate of the touch relative to the diob.
2634
+ * @param {boolean} [pCancel] - (Optional) Whether the touch was cancelled.
2635
+ * @param {TouchEvent} [pEvent] - (Optional) The native browser TouchEvent.
2636
+ */
2637
+ onTouchEnd?(pClient: Client, pX: number, pY: number, pCancel?: boolean, pEvent?: TouchEvent): void;
2638
+
2639
+ /**
2640
+ * Called when a touch point moves over this diob.
2641
+ *
2642
+ * @env Client | Server
2643
+ * @event
2644
+ * @param {Client} pClient - The client whose touch moved.
2645
+ * @param {number} pX - Horizontal coordinate of the touch relative to the diob.
2646
+ * @param {number} pY - Vertical coordinate of the touch relative to the diob.
2647
+ * @param {TouchEvent} [pEvent] - (Optional) The native browser TouchEvent.
2648
+ */
2649
+ onTouchMove?(pClient: Client, pX: number, pY: number, pEvent?: TouchEvent): void;
2650
+
2651
+ /**
2652
+ * Called when this diob is attached as an overlay to another diob or client.
2653
+ *
2654
+ * @env Client | Server
2655
+ * @event
2656
+ * @param {Diob} pParent - The parent diob or client that this diob was attached to.
2657
+ */
2658
+ onOverlayed?(pParent: Diob): void;
2659
+
2660
+ /**
2661
+ * Called when this diob is removed as an overlay from its parent.
2662
+ *
2663
+ * @env Client | Server
2664
+ * @event
2665
+ * @param {Diob} pParent - The parent diob or client that this diob was removed from.
2666
+ */
2667
+ onUnoverlayed?(pParent: Diob): void;
2668
+
2669
+ /**
2670
+ * CLIENT-ONLY. Called when this diob's state is synchronized from the server to the client.
2671
+ *
2672
+ * @env Client
2673
+ * @event
2674
+ * @param {Client} pClient - The local client instance.
2675
+ */
2676
+ onClientSync?(pClient: Client): void;
2677
+
2678
+ [key: string]: any
2679
+
2680
+ }
2681
+
2682
+
2683
+
2684
+ /**
2685
+ * MapObject represents a spatial display object situated directly on a map grid, extending Diob.
2686
+ */
2687
+ interface MapObject extends Diob {
2688
+
2689
+ /**
2690
+ * Read-only boolean flag indicating this is a MapObject.
2691
+ *
2692
+ * @env Client | Server
2693
+ */
2694
+ readonly isMapObject: boolean;
2695
+
2696
+ /**
2697
+ * When `true`, prevents the MapObject from automatically being added to the screen display list.
2698
+ *
2699
+ * @env Client | Server
2700
+ */
2701
+ preventAutoDisplay: boolean;
2702
+
2703
+ /**
2704
+ * Calculates Euclidean distance in pixels between the top-left position of this object and `pD`.
2705
+ *
2706
+ * @env Client | Server
2707
+ * @param {MapObject} pD - The target MapObject.
2708
+ * @returns {number} The distance in pixels.
2709
+ */
2710
+ getDistFrom(pD: MapObject): number;
2711
+
2712
+ /**
2713
+ * Calculates Euclidean distance in pixels between the bounding box centers of this object and `pD`.
2714
+ *
2715
+ * @env Client | Server
2716
+ * @param {MapObject} pD - The target MapObject.
2717
+ * @returns {number} The center-to-center distance in pixels.
2718
+ */
2719
+ getDistCenterFrom(pD: MapObject): number;
2720
+
2721
+ /**
2722
+ * Calculates Euclidean distance in pixels between the closest bounding edges of this object and `pD`.
2723
+ *
2724
+ * @env Client | Server
2725
+ * @param {MapObject} pD - The target MapObject.
2726
+ * @returns {number} The edge-to-edge distance in pixels.
2727
+ */
2728
+ getDistEdgeFrom(pD: MapObject): number;
2729
+
2730
+ /**
2731
+ * Calculates the compass direction string from this object's top-left position towards `pD`.
2732
+ *
2733
+ * @env Client | Server
2734
+ * @param {MapObject} pD - Target MapObject.
2735
+ * @param {boolean} [pCard] - If `true`, constrains return to standard cardinal directions.
2736
+ * @returns {Direction | string} Direction string.
2737
+ */
2738
+ getDirFrom(pD: MapObject, pCard?: boolean): Direction | string;
2739
+
2740
+ /**
2741
+ * Calculates the compass direction string from this object's bounding center towards `pD`.
2742
+ *
2743
+ * @env Client | Server
2744
+ * @param {MapObject} pD - Target MapObject.
2745
+ * @param {boolean} [pCard] - If `true`, constrains return to standard cardinal directions.
2746
+ * @returns {Direction | string} Direction string.
2747
+ */
2748
+ getDirCenterFrom(pD: MapObject, pCard?: boolean): Direction | string;
2749
+
2750
+ /**
2751
+ * Calculates the angle in radians from this object's top-left position towards `pD`.
2752
+ *
2753
+ * @env Client | Server
2754
+ * @param {MapObject} pD - Target MapObject.
2755
+ * @returns {number} Angle in radians.
2756
+ */
2757
+ getAngleFrom(pD: MapObject): number;
2758
+
2759
+ /**
2760
+ * Calculates the angle in radians from this object's bounding center towards `pD`.
2761
+ *
2762
+ * @env Client | Server
2763
+ * @param {MapObject} pD - Target MapObject.
2764
+ * @returns {number} Angle in radians.
2765
+ */
2766
+ getAngleCenterFrom(pD: MapObject): number;
2767
+
2768
+ /**
2769
+ * Checks whether this MapObject's bounding box intersects with `pO`.
2770
+ *
2771
+ * @env Client | Server
2772
+ * @param {MapObject} pO - Object to test intersection with.
2773
+ * @returns {boolean} `true` if bounding boxes overlap; otherwise `false`.
2774
+ */
2775
+ checkIntersectWith(pO: MapObject): boolean;
2776
+
2777
+ /**
2778
+ * Checks whether this MapObject would collide with dense tiles or dense objects at the specified rectangle.
2779
+ *
2780
+ * @env Client | Server
2781
+ * @param {number} [pX] - Test horizontal position in map pixels (defaults to current x).
2782
+ * @param {number} [pY] - Test vertical position in map pixels (defaults to current y).
2783
+ * @param {number} [pW] - Test width (defaults to current width).
2784
+ * @param {number} [pH] - Test height (defaults to current height).
2785
+ * @returns {Tile | Diob | null} The obstacle encountered, or `null` if clear.
2786
+ */
2787
+ checkCollideAt(pX?: number, pY?: number, pW?: number, pH?: number): Tile | Diob | null;
2788
+
2789
+ [key: string]: any;
2790
+
2791
+ }
2792
+
2793
+
2794
+
2795
+ /** The movable object. */
2796
+ type Movable = {
2797
+
2798
+ /**
2799
+ * Moves movable in the direction of `pDir` using movable's stepSize until told to stop. Takes density into consideration. You can stop movement by calling a different movement function or calling this function with no or `null` arguments.
2800
+ *
2801
+ * @env Client | Server
2802
+ * @param {Direction | string} [pDir] - Direction to move movable in.
2803
+ */
2804
+ moveDir(pDir?: Direction | string): void
2805
+
2806
+ /**
2807
+ * Moves the movable by `pX` x pixels and `pY` y pixels until told to stop. Takes obstacles into consideration. You can stop movement by calling a different movement function or calling this function with no or `null` arguments.
2808
+ *
2809
+ * @env Client | Server
2810
+ * @param {number} pX - X value to step by.
2811
+ * @param {number} pY - Y value to step by.
2812
+ */
2813
+ movePos(pX: number, pY: number): void
2814
+
2815
+ /**
2816
+ * True if moving using the built-in movement.
2817
+ *
2818
+ * @env Client | Server
2819
+ */
2820
+ isMoving: boolean
2821
+
2822
+ /**
2823
+ * Steps the movable by `pX` x pixels and `pY` y pixels. Takes obstacles into consideration. Returns `true` or `false` depending on if the step was successful.
2824
+ *
2825
+ * @env Client | Server
2826
+ * @param {number} pX - X value to step by.
2827
+ * @param {number} pY - Y value to step by.
2828
+ * @param {boolean} pGlide - If set, movement will not stop unless move directions are blocked.
2829
+ * @param {boolean} pSlide - If set, the step will occur without changing the movable's direction.
2830
+ * @returns {void} Returns `true` or `false` depending on if the step was successful.
2831
+ */
2832
+ stepPos(pX: number, pY: number, pGlide: boolean, pSlide: boolean): void
2833
+
2834
+ /**
2835
+ * Movement settings configuration controlling step size, gliding, sliding, cardinal locking, and step frequency.
2836
+ *
2837
+ * @env Client | Server
2838
+ *
2839
+ * @example
2840
+ * ```ts
2841
+ * movable.moveSettings = {
2842
+ * stepSize: 4,
2296
2843
  * stepGlide: true,
2297
2844
  * stepTick: 16.6667
2298
2845
  * };
@@ -2326,7 +2873,21 @@ declare global {
2326
2873
  */
2327
2874
  move(): void
2328
2875
 
2329
- /**
2876
+ /**
2877
+ * Read-only boolean flag indicating this object is a Movable.
2878
+ *
2879
+ * @env Client | Server
2880
+ */
2881
+ readonly isMovable: boolean;
2882
+
2883
+ /**
2884
+ * The default step distance in pixels moved per step when moving in a direction.
2885
+ *
2886
+ * @env Client | Server
2887
+ */
2888
+ stepSize: number;
2889
+
2890
+ /**
2330
2891
  * Current facing or movement direction of the movable (`'north'`, `'south'`, `'east'`, `'west'`, `'northwest'`, `'northeast'`, `'southwest'`, `'southeast'`).
2331
2892
  *
2332
2893
  * @env Client | Server
@@ -2354,6 +2915,13 @@ declare global {
2354
2915
  * @env Client
2355
2916
  */
2356
2917
  preventScreenRelayer: boolean
2918
+
2919
+ /**
2920
+ * Read-only boolean flag indicating this object is a Particle.
2921
+ *
2922
+ * @env Client | Server
2923
+ */
2924
+ readonly isParticle: boolean;
2357
2925
  [key: string]: any
2358
2926
 
2359
2927
  }
@@ -2411,6 +2979,28 @@ declare global {
2411
2979
  * @env Client | Server
2412
2980
  */
2413
2981
  mouseOpacity?: MouseOpacity | 0 | 1 | 2;
2982
+
2983
+ /**
2984
+ * Read-only boolean flag indicating this object is a Tile.
2985
+ *
2986
+ * @env Client | Server
2987
+ */
2988
+ readonly isTile: boolean;
2989
+
2990
+ /**
2991
+ * Returns the neighbor Tile located in the compass direction `pDir` from this tile on the same map.
2992
+ *
2993
+ * @env Client | Server
2994
+ * @param {Direction | string} pDir - Compass direction (e.g. `'north'`, `'east'`, `'southwest'`).
2995
+ * @returns {Tile | null} The adjacent tile in that direction, or the engine void tile / null if out of bounds.
2996
+ *
2997
+ * @example
2998
+ * ```ts
2999
+ * const northTile = tile.getTileByDir('north');
3000
+ * ```
3001
+ */
3002
+ getTileByDir(pDir: Direction | string): Tile | null;
3003
+
2414
3004
  [key: string]: any
2415
3005
 
2416
3006
  }
@@ -2420,6 +3010,13 @@ declare global {
2420
3010
  /** The region object. */
2421
3011
  type Region = {
2422
3012
 
3013
+ /**
3014
+ * Read-only boolean flag indicating this object is a Region.
3015
+ *
3016
+ * @env Client | Server
3017
+ */
3018
+ readonly isRegion: boolean;
3019
+
2423
3020
  /**
2424
3021
  * When an object exits the contents of another object.
2425
3022
  *
@@ -2446,6 +3043,13 @@ declare global {
2446
3043
  /** The mob object. */
2447
3044
  interface Mob {
2448
3045
 
3046
+ /**
3047
+ * Read-only boolean flag indicating this object is a Mob.
3048
+ *
3049
+ * @env Client | Server
3050
+ */
3051
+ readonly isMob: boolean;
3052
+
2449
3053
  /**
2450
3054
  * A reference to the client of this mob.
2451
3055
  *
@@ -2477,6 +3081,13 @@ declare global {
2477
3081
  /** The overlay object. */
2478
3082
  type Overlay = {
2479
3083
 
3084
+ /**
3085
+ * Reference to the parent Diob that this overlay is attached to (`_vy_parent`).
3086
+ *
3087
+ * @env Client | Server
3088
+ */
3089
+ parent: Diob;
3090
+
2480
3091
  /**
2481
3092
  * If `true`, this overlay will appear directly above the parent and use the same appearance properties as the parent, such as angle and alpha. The overlay will basically be an extension of the parent's icon. Instead of `true` this can be an object containing information on the appearMask, `shareIcon` to have the overlay share the same iconName as the parent, `isUnder` to make the overlay appear under the parent instead of above, and `ownMod` to let the overlay use its own alpha, angle, scale, transform, and composite variables, `ownState` to have this overlay not sync up with the parent's iconState. Example: `{'shareIcon': `true`, 'isUnder': `true`}`.
2482
3093
  *
@@ -2636,6 +3247,54 @@ declare global {
2636
3247
  */
2637
3248
  loop: boolean
2638
3249
 
3250
+ /**
3251
+ * Read-only flag confirming this object is a Sound instance.
3252
+ *
3253
+ * @env Client | Server
3254
+ */
3255
+ readonly isSound?: boolean
3256
+
3257
+ /**
3258
+ * Playback rate factor for the sound (e.g. `1.0` for normal speed, `0.5` for half-speed, `2.0` for double speed).
3259
+ *
3260
+ * @env Client | Server
3261
+ */
3262
+ playbackRate?: number
3263
+
3264
+ /**
3265
+ * Sets the playback speed rate of this sound.
3266
+ *
3267
+ * @env Client | Server
3268
+ * @param {number} pVal - Playback rate multiplier (e.g. `1` is default speed).
3269
+ */
3270
+ setPlaybackRate(pVal: number): void
3271
+
3272
+ /**
3273
+ * Returns the native Web Audio API `AudioBufferSourceNode` source for this sound.
3274
+ *
3275
+ * @env Client | Server
3276
+ * @returns {AudioBufferSourceNode | any} The active audio source node.
3277
+ */
3278
+ getSource(): AudioBufferSourceNode | any
3279
+
3280
+ /**
3281
+ * Returns the spatial audio `PannerNode` for this sound, creating one if it doesn't already exist.
3282
+ *
3283
+ * @env Client | Server
3284
+ * @returns {PannerNode | any} The audio panner node.
3285
+ */
3286
+ getPanner(): PannerNode | any
3287
+
3288
+ /**
3289
+ * Registers a new sound buffer into the engine resources.
3290
+ *
3291
+ * @env Client | Server
3292
+ * @param {string} pName - Sound identifier name.
3293
+ * @param {string | ArrayBuffer} pData - Sound data or base64 data URL.
3294
+ * @param {string} [pDataType] - Optional data type (e.g. `'url'`).
3295
+ */
3296
+ newSound?(pName: string, pData: string | ArrayBuffer, pDataType?: string): void
3297
+
2639
3298
  }
2640
3299
 
2641
3300
 
@@ -2771,6 +3430,36 @@ declare global {
2771
3430
  */
2772
3431
  xPos: number
2773
3432
 
3433
+ /**
3434
+ * Read-only boolean flag indicating this is an Interface element.
3435
+ *
3436
+ * @env Client | Server
3437
+ */
3438
+ readonly isInterface: boolean;
3439
+
3440
+ /**
3441
+ * Reference to the Client instance that owns this interface element.
3442
+ *
3443
+ * @env Client | Server
3444
+ */
3445
+ client: Client;
3446
+
3447
+ /**
3448
+ * The InterfacePane instance that contains this interface element.
3449
+ *
3450
+ * @env Client | Server
3451
+ */
3452
+ pane: InterfacePane;
3453
+
3454
+ /**
3455
+ * Called when this interface element is moved or reassigned to a different interface pane.
3456
+ *
3457
+ * @env Client | Server
3458
+ * @event
3459
+ * @param {InterfacePane} pOldPane - The previous interface pane.
3460
+ */
3461
+ onPaneChange?(pOldPane: InterfacePane): void;
3462
+
2774
3463
  /**
2775
3464
  * Determines if the cursor executes mouse events on this interface element.
2776
3465
  *
@@ -2787,8 +3476,590 @@ declare global {
2787
3476
 
2788
3477
 
2789
3478
 
2790
- /** The client object. */
2791
- interface Client {
3479
+ /**
3480
+ * Represents a named container of interface elements belonging to a client.
3481
+ */
3482
+ interface InterfacePane {
3483
+
3484
+ /**
3485
+ * Read-only boolean flag indicating this is an InterfacePane.
3486
+ *
3487
+ * @env Client | Server
3488
+ */
3489
+ readonly isInterfacePane: boolean;
3490
+
3491
+ /**
3492
+ * The identifier name of this interface pane.
3493
+ *
3494
+ * @env Client | Server
3495
+ */
3496
+ name: string;
3497
+
3498
+ /**
3499
+ * The client that owns this interface pane.
3500
+ *
3501
+ * @env Client | Server
3502
+ */
3503
+ readonly client: Client;
3504
+
3505
+ /**
3506
+ * Transparency alpha level of all elements in this pane (0.0 to 1.0).
3507
+ *
3508
+ * @env Client | Server
3509
+ */
3510
+ alpha: number;
3511
+
3512
+ /**
3513
+ * Whether this interface pane is currently shown/visible.
3514
+ * Setting to `true` shows the pane; setting to `false` hides it.
3515
+ *
3516
+ * @env Client | Server
3517
+ */
3518
+ isShown: boolean;
3519
+
3520
+ /**
3521
+ * Shows the interface pane and its contained elements, or a specific child element `pEl`.
3522
+ *
3523
+ * @env Client | Server
3524
+ * @param {string | Diob} [pEl] - Optional specific child element name or instance to show.
3525
+ * @param {boolean} [pForce] - If `true`, forces hidden elements to be shown.
3526
+ */
3527
+ show(pEl?: string | Diob, pForce?: boolean): void;
3528
+
3529
+ /**
3530
+ * Hides the interface pane or a specific child element `pEl`.
3531
+ *
3532
+ * @env Client | Server
3533
+ * @param {string | Diob} [pEl] - Optional specific child element name or instance to hide.
3534
+ */
3535
+ hide(pEl?: string | Diob): void;
3536
+
3537
+ /**
3538
+ * Adds an interface child element `pEl` to this pane.
3539
+ *
3540
+ * @env Client | Server
3541
+ * @param {any} pEl - Element instance to add.
3542
+ * @returns {any} The added element.
3543
+ */
3544
+ addChild(pEl: any): any;
3545
+
3546
+ /**
3547
+ * Removes a child element `pEl` from this pane.
3548
+ *
3549
+ * @env Client | Server
3550
+ * @param {any} pEl - Child element to remove.
3551
+ * @param {boolean} [pSave] - If `true`, avoids deleting the element from the engine.
3552
+ */
3553
+ removeChild(pEl: any, pSave?: boolean): void;
3554
+
3555
+ /**
3556
+ * Retrieves the child element with the specified name `pName`.
3557
+ *
3558
+ * @env Client | Server
3559
+ * @param {string} pName - Name of the child element.
3560
+ * @returns {any} The child element.
3561
+ */
3562
+ getChild(pName: string): any;
3563
+
3564
+ /**
3565
+ * Returns an array of child elements within this pane matching the specified criteria.
3566
+ *
3567
+ * @env Client | Server
3568
+ * @param {string} [pType] - Optional type filter.
3569
+ * @param {boolean} [pChild] - If `true`, includes child types.
3570
+ * @returns {any[]} Array of child elements.
3571
+ */
3572
+ getChildren(pType?: string, pChild?: boolean): any[];
3573
+
3574
+ /**
3575
+ * Called when this interface pane is shown to a client.
3576
+ *
3577
+ * @env Client | Server
3578
+ * @event
3579
+ * @param {Client} pClient - The client shown to.
3580
+ */
3581
+ onShow?(pClient: Client): void;
3582
+
3583
+ /**
3584
+ * Called when this interface pane is hidden from a client.
3585
+ *
3586
+ * @env Client | Server
3587
+ * @event
3588
+ * @param {Client} pClient - The client hidden from.
3589
+ */
3590
+ onHide?(pClient: Client): void;
3591
+
3592
+ /**
3593
+ * Called when a child element is added to this pane.
3594
+ *
3595
+ * @env Client | Server
3596
+ * @event
3597
+ * @param {any} pChild - The child element added.
3598
+ */
3599
+ onAddChild?(pChild: any): void;
3600
+
3601
+ /**
3602
+ * Called when a child element is removed from this pane.
3603
+ *
3604
+ * @env Client | Server
3605
+ * @event
3606
+ * @param {any} pChild - The child element removed.
3607
+ */
3608
+ onRemoveChild?(pChild: any): void;
3609
+
3610
+ [key: string]: any;
3611
+
3612
+ }
3613
+
3614
+ /** WebBox padding style descriptor. */
3615
+ interface WebBoxPaddingStyle {
3616
+ top?: string | number;
3617
+ right?: string | number;
3618
+ bottom?: string | number;
3619
+ left?: string | number;
3620
+ [key: string]: any;
3621
+ }
3622
+
3623
+ /** WebBox margin style descriptor. */
3624
+ interface WebBoxMarginStyle {
3625
+ top?: string | number;
3626
+ right?: string | number;
3627
+ bottom?: string | number;
3628
+ left?: string | number;
3629
+ [key: string]: any;
3630
+ }
3631
+
3632
+ /** WebBox overflow style descriptor. */
3633
+ interface WebBoxOverflowStyle {
3634
+ x?: string;
3635
+ y?: string;
3636
+ [key: string]: any;
3637
+ }
3638
+
3639
+ /** WebBox background style descriptor. */
3640
+ interface WebBoxBackgroundStyle {
3641
+ color?: string;
3642
+ image?: string;
3643
+ repeat?: string;
3644
+ position?: string;
3645
+ size?: string;
3646
+ attachment?: string;
3647
+ clip?: string;
3648
+ origin?: string;
3649
+ [key: string]: any;
3650
+ }
3651
+
3652
+ /** WebBox border style descriptor. */
3653
+ interface WebBoxBorderStyle {
3654
+ width?: string | number;
3655
+ style?: string;
3656
+ color?: string;
3657
+ radius?: string | number;
3658
+ top?: string | number;
3659
+ right?: string | number;
3660
+ bottom?: string | number;
3661
+ left?: string | number;
3662
+ topColor?: string;
3663
+ rightColor?: string;
3664
+ bottomColor?: string;
3665
+ leftColor?: string;
3666
+ topStyle?: string;
3667
+ rightStyle?: string;
3668
+ bottomStyle?: string;
3669
+ leftStyle?: string;
3670
+ topWidth?: string | number;
3671
+ rightWidth?: string | number;
3672
+ bottomWidth?: string | number;
3673
+ leftWidth?: string | number;
3674
+ topLeftRadius?: string | number;
3675
+ topRightRadius?: string | number;
3676
+ bottomLeftRadius?: string | number;
3677
+ bottomRightRadius?: string | number;
3678
+ collapse?: string;
3679
+ spacing?: string | number;
3680
+ [key: string]: any;
3681
+ }
3682
+
3683
+ /** WebBox outline style descriptor. */
3684
+ interface WebBoxOutlineStyle {
3685
+ color?: string;
3686
+ offset?: string | number;
3687
+ style?: string;
3688
+ width?: string | number;
3689
+ [key: string]: any;
3690
+ }
3691
+
3692
+ /** WebBox text style descriptor. */
3693
+ interface WebBoxTextStyle {
3694
+ color?: string;
3695
+ fontFamily?: string;
3696
+ fontSize?: string | number;
3697
+ fontStyle?: string;
3698
+ fontWeight?: string | number;
3699
+ letterSpacing?: string | number;
3700
+ lineHeight?: string | number;
3701
+ textAlign?: string;
3702
+ textDecoration?: string;
3703
+ textIndent?: string | number;
3704
+ textOverflow?: string;
3705
+ textShadow?: string;
3706
+ textTransform?: string;
3707
+ whiteSpace?: string;
3708
+ wordBreak?: string;
3709
+ wordSpacing?: string | number;
3710
+ wordWrap?: string;
3711
+ [key: string]: any;
3712
+ }
3713
+
3714
+ /**
3715
+ * Represents an HTML DOM-backed interface element, extending Interface.
3716
+ */
3717
+ interface WebBox extends Interface {
3718
+
3719
+ /**
3720
+ * Read-only boolean flag indicating this is a WebBox.
3721
+ *
3722
+ * @env Client | Server
3723
+ */
3724
+ readonly isWebBox: boolean;
3725
+
3726
+ /**
3727
+ * The underlying HTML DOM element (`_vy_dom`).
3728
+ *
3729
+ * @env Client
3730
+ */
3731
+ readonly dom: HTMLElement;
3732
+
3733
+ /**
3734
+ * The DOM element's `id` attribute.
3735
+ *
3736
+ * @env Client | Server
3737
+ */
3738
+ domID: string;
3739
+
3740
+ /**
3741
+ * CSSStyleDeclaration of the underlying DOM element.
3742
+ *
3743
+ * @env Client
3744
+ */
3745
+ style: CSSStyleDeclaration | Record<string, any>;
3746
+
3747
+ /**
3748
+ * CSS `display` style property.
3749
+ *
3750
+ * @env Client | Server
3751
+ */
3752
+ display: string;
3753
+
3754
+ /**
3755
+ * CSS `box-shadow` style property.
3756
+ *
3757
+ * @env Client | Server
3758
+ */
3759
+ boxShadow: string;
3760
+
3761
+ /**
3762
+ * CSS `box-sizing` style property.
3763
+ *
3764
+ * @env Client | Server
3765
+ */
3766
+ boxSizing: string;
3767
+
3768
+ /**
3769
+ * CSS `clip-path` style property.
3770
+ *
3771
+ * @env Client | Server
3772
+ */
3773
+ clip: string;
3774
+
3775
+ /**
3776
+ * CSS `cursor` style property.
3777
+ *
3778
+ * @env Client | Server
3779
+ */
3780
+ cursor: string;
3781
+
3782
+ /**
3783
+ * CSS `pointer-events` style property.
3784
+ *
3785
+ * @env Client | Server
3786
+ */
3787
+ pointerEvents: string;
3788
+
3789
+ /**
3790
+ * Maximum height constraint.
3791
+ *
3792
+ * @env Client | Server
3793
+ */
3794
+ maxHeight: string | number;
3795
+
3796
+ /**
3797
+ * Minimum height constraint.
3798
+ *
3799
+ * @env Client | Server
3800
+ */
3801
+ minHeight: string | number;
3802
+
3803
+ /**
3804
+ * Maximum width constraint.
3805
+ *
3806
+ * @env Client | Server
3807
+ */
3808
+ maxWidth: string | number;
3809
+
3810
+ /**
3811
+ * Minimum width constraint.
3812
+ *
3813
+ * @env Client | Server
3814
+ */
3815
+ minWidth: string | number;
3816
+
3817
+ /**
3818
+ * Padding style helper or CSS string.
3819
+ *
3820
+ * @env Client | Server
3821
+ */
3822
+ padding: WebBoxPaddingStyle | string;
3823
+
3824
+ /**
3825
+ * Margin style helper or CSS string.
3826
+ *
3827
+ * @env Client | Server
3828
+ */
3829
+ margin: WebBoxMarginStyle | string;
3830
+
3831
+ /**
3832
+ * Overflow style helper or CSS string.
3833
+ *
3834
+ * @env Client | Server
3835
+ */
3836
+ overflow: WebBoxOverflowStyle | string;
3837
+
3838
+ /**
3839
+ * CSS `float` style property.
3840
+ *
3841
+ * @env Client | Server
3842
+ */
3843
+ float: string;
3844
+
3845
+ /**
3846
+ * CSS `transform` style property.
3847
+ *
3848
+ * @env Client | Server
3849
+ */
3850
+ transform: string;
3851
+
3852
+ /**
3853
+ * CSS `composite` style property.
3854
+ *
3855
+ * @env Client | Server
3856
+ */
3857
+ composite: any;
3858
+
3859
+ /**
3860
+ * Background style helper or CSS color string.
3861
+ *
3862
+ * @env Client | Server
3863
+ */
3864
+ background: WebBoxBackgroundStyle | string;
3865
+
3866
+ /**
3867
+ * Border style helper or CSS border string.
3868
+ *
3869
+ * @env Client | Server
3870
+ */
3871
+ border: WebBoxBorderStyle | string;
3872
+
3873
+ /**
3874
+ * Outline style helper or CSS outline string.
3875
+ *
3876
+ * @env Client | Server
3877
+ */
3878
+ outline: WebBoxOutlineStyle | string;
3879
+
3880
+ /**
3881
+ * CSS `accent-color` style property.
3882
+ *
3883
+ * @env Client | Server
3884
+ */
3885
+ accentColor: string;
3886
+
3887
+ /**
3888
+ * Typography and text styling options.
3889
+ *
3890
+ * @env Client | Server
3891
+ */
3892
+ textStyle: WebBoxTextStyle | any;
3893
+
3894
+ /**
3895
+ * CSS class name or array of class names applied to this element.
3896
+ *
3897
+ * @env Client | Server
3898
+ */
3899
+ styleClass: string | string[];
3900
+
3901
+ /**
3902
+ * Adds a CSS class name to this element.
3903
+ *
3904
+ * @env Client | Server
3905
+ * @param {string} pClass - CSS class name.
3906
+ */
3907
+ addStyleClass(pClass: string): void;
3908
+
3909
+ /**
3910
+ * Removes a CSS class name from this element.
3911
+ *
3912
+ * @env Client | Server
3913
+ * @param {string} pClass - CSS class name.
3914
+ */
3915
+ removeStyleClass(pClass: string): void;
3916
+
3917
+ /**
3918
+ * Parent WebBox containing this element, if nested.
3919
+ *
3920
+ * @env Client | Server
3921
+ */
3922
+ parent: WebBox | null;
3923
+
3924
+ /**
3925
+ * Top-most ancestor WebBox in the hierarchy.
3926
+ *
3927
+ * @env Client | Server
3928
+ */
3929
+ readonly highestParent: WebBox | null;
3930
+
3931
+ /**
3932
+ * Array of child WebBox elements contained within this element.
3933
+ *
3934
+ * @env Client | Server
3935
+ */
3936
+ readonly children: WebBox[];
3937
+
3938
+ /**
3939
+ * Adds a child WebBox element to this element.
3940
+ *
3941
+ * @env Client | Server
3942
+ * @param {WebBox} pEl - WebBox to add.
3943
+ * @returns {WebBox} The added WebBox.
3944
+ */
3945
+ addChild(pEl: WebBox): WebBox;
3946
+
3947
+ /**
3948
+ * Removes a child WebBox from this element.
3949
+ *
3950
+ * @env Client | Server
3951
+ * @param {WebBox} pEl - WebBox to remove.
3952
+ */
3953
+ removeChild(pEl: WebBox): void;
3954
+
3955
+ /**
3956
+ * Removes child WebBox elements across an index range.
3957
+ *
3958
+ * @env Client | Server
3959
+ * @param {number} pStart - Start index.
3960
+ * @param {number} [pEnd] - End index.
3961
+ */
3962
+ removeChildAt(pStart: number, pEnd?: number): void;
3963
+
3964
+ /**
3965
+ * Returns child WebBox elements matching the specified type.
3966
+ *
3967
+ * @env Client | Server
3968
+ * @param {string} [pType] - Type filter.
3969
+ * @param {boolean} [pChild] - Include child types.
3970
+ * @returns {WebBox[]} Child elements.
3971
+ */
3972
+ getChildren(pType?: string, pChild?: boolean): WebBox[];
3973
+
3974
+ /**
3975
+ * Configures whether this WebBox can be interactively resized by the user.
3976
+ *
3977
+ * @env Client
3978
+ */
3979
+ isResizable: boolean | 'both' | 'horizontal' | 'vertical';
3980
+
3981
+ /**
3982
+ * Configures whether this WebBox can be dragged across the screen.
3983
+ *
3984
+ * @env Client
3985
+ */
3986
+ isDraggable: boolean;
3987
+
3988
+ [key: string]: any;
3989
+
3990
+ }
3991
+
3992
+ /**
3993
+ * Represents an interactive text input interface element (single-line or multiline), extending WebBox.
3994
+ */
3995
+ interface TextInput extends WebBox {
3996
+
3997
+ /**
3998
+ * Read-only boolean flag indicating this is a TextInput.
3999
+ *
4000
+ * @env Client | Server
4001
+ */
4002
+ readonly isTextInput: boolean;
4003
+
4004
+ /**
4005
+ * When `true`, uses a multiline `<textarea>` element rather than a single-line input.
4006
+ *
4007
+ * @env Client | Server
4008
+ */
4009
+ isMultiline: boolean;
4010
+
4011
+ /**
4012
+ * When `true`, masks characters entered for password privacy (`type="password"`).
4013
+ *
4014
+ * @env Client | Server
4015
+ */
4016
+ isPasswordInput: boolean;
4017
+
4018
+ /**
4019
+ * When `true`, configures the input as a command-line input.
4020
+ *
4021
+ * @env Client | Server
4022
+ */
4023
+ isCommandInput: boolean;
4024
+
4025
+ /**
4026
+ * Maximum character length allowed in the input field.
4027
+ *
4028
+ * @env Client | Server
4029
+ */
4030
+ maxLength: number;
4031
+
4032
+ /**
4033
+ * Placeholder text displayed when the input field is empty.
4034
+ *
4035
+ * @env Client | Server
4036
+ */
4037
+ placeholder: string;
4038
+
4039
+ /**
4040
+ * HTML `tabIndex` attribute controlling keyboard focus navigation order.
4041
+ *
4042
+ * @env Client | Server
4043
+ */
4044
+ tabIndex: number;
4045
+
4046
+ /**
4047
+ * Called when the input text is modified by the user.
4048
+ *
4049
+ * @env Client | Server
4050
+ * @event
4051
+ * @param {Client} pClient - The client that typed into the input.
4052
+ */
4053
+ onInput?(pClient: Client): void;
4054
+
4055
+ [key: string]: any;
4056
+
4057
+ }
4058
+
4059
+
4060
+
4061
+ /** The client object. */
4062
+ interface Client {
2792
4063
 
2793
4064
  /**
2794
4065
  * Stores `pData` as a string locally on the client's computer and can be referenced using `pKey`. Leaving `pKey` and `pData` blank will clear all local storage; 3000 characters are allowed to be saved per game (keys and values combined).
@@ -2799,6 +4070,23 @@ declare global {
2799
4070
  */
2800
4071
  setLocalStorage(pKey?: string, pData?: string): void
2801
4072
 
4073
+ /**
4074
+ * Checks whether `window.localStorage` is supported, enabled, and functioning on the client's browser.
4075
+ *
4076
+ * Tests accessibility by attempting to write and remove a temporary test key.
4077
+ *
4078
+ * @env Client
4079
+ * @returns {boolean} `true` if local storage is available and functional; otherwise `false`.
4080
+ *
4081
+ * @example
4082
+ * ```ts
4083
+ * if (VYLO.Client.checkLocalStorage()) {
4084
+ * VYLO.Client.setLocalStorage('savedLevel', '5');
4085
+ * }
4086
+ * ```
4087
+ */
4088
+ checkLocalStorage(): boolean;
4089
+
2802
4090
  /**
2803
4091
  * Returns an object `{'x': x, 'y': y}` containing the x and y position on the map that currently matches the `pX` and `pY` position on the screen.
2804
4092
  *
@@ -2820,6 +4108,40 @@ declare global {
2820
4108
  */
2821
4109
  getInterfaceElement(pInterface: string, pElement: Diob): Diob
2822
4110
 
4111
+ /**
4112
+ * Returns the interface pane instance with the specified name `pPane`.
4113
+ *
4114
+ * @env Client
4115
+ * @param {string} pPane - The identifier name of the interface pane to retrieve.
4116
+ * @returns {InterfacePane} The interface pane instance, or `undefined` if not found.
4117
+ *
4118
+ * @example
4119
+ * ```ts
4120
+ * const chatPane = VYLO.Client.getInterfacePane('chat');
4121
+ * chatPane?.show();
4122
+ * ```
4123
+ */
4124
+ getInterfacePane(pPane: string): InterfacePane;
4125
+
4126
+ /**
4127
+ * Retrieves an interface pane or an element within an interface pane.
4128
+ *
4129
+ * - If `pEl` is omitted or `undefined`: returns the interface pane corresponding to `pPane`.
4130
+ * - If `pEl` is specified: returns the child element within that interface pane named `pEl`.
4131
+ *
4132
+ * @env Client
4133
+ * @param {string | InterfacePane} [pPane=''] - Name of the interface pane or the pane instance itself.
4134
+ * @param {string} [pEl] - Optional name of the element within the interface pane.
4135
+ * @returns {InterfacePane | Diob | any} The interface pane or the requested interface element.
4136
+ *
4137
+ * @example
4138
+ * ```ts
4139
+ * const hud = VYLO.Client.getInterface('hud');
4140
+ * const healthBar = VYLO.Client.getInterface('hud', 'healthBar');
4141
+ * ```
4142
+ */
4143
+ getInterface(pPane?: string | InterfacePane, pEl?: string): InterfacePane | Diob | any;
4144
+
2823
4145
  /**
2824
4146
  * Removes the specified filter.
2825
4147
  *
@@ -2853,6 +4175,109 @@ declare global {
2853
4175
  */
2854
4176
  xEdgeLimit: number
2855
4177
 
4178
+ /**
4179
+ * CLIENT-ONLY. Toggles whether to hide the on-screen frames-per-second (FPS) DOM label element (`#fps_label`).
4180
+ *
4181
+ * When `true`, the default FPS counter overlay is hidden from the client view.
4182
+ * When `false`, the FPS label element is displayed in the corner of the game screen and updated every second.
4183
+ *
4184
+ * @env Client
4185
+ *
4186
+ * @example
4187
+ * ```ts
4188
+ * // Hide the built-in FPS counter display
4189
+ * VYLO.Client.hideFPS = true;
4190
+ * ```
4191
+ */
4192
+ hideFPS: boolean
4193
+
4194
+ /**
4195
+ * CLIENT-ONLY. Controls whether off-screen display objects (Diobs) and map tiles are culled from rendering.
4196
+ *
4197
+ * By default (`false`), the Vylocity engine performs screen frustum culling, automatically removing
4198
+ * non-visible map tiles and cullable Diobs from the screen display list to maximize rendering performance.
4199
+ *
4200
+ * When set to `true`, screen culling is prevented, forcing all map tiles and objects within the map view
4201
+ * to remain added to the display list regardless of whether they are outside the current camera viewport.
4202
+ *
4203
+ * @env Client
4204
+ *
4205
+ * @example
4206
+ * ```ts
4207
+ * // Prevent culling so all diobs and tiles stay on screen
4208
+ * VYLO.Client.preventScreenCulling = true;
4209
+ * ```
4210
+ */
4211
+ preventScreenCulling: boolean
4212
+
4213
+ /**
4214
+ * Name of the default map file to load when the client connects or initializes.
4215
+ *
4216
+ * When the client's controlled mob is created and does not already have an assigned map,
4217
+ * it is automatically placed onto this map at coordinates `(0, 0)`.
4218
+ *
4219
+ * @env Client | Server
4220
+ *
4221
+ * @example
4222
+ * ```ts
4223
+ * VYLO.Client.mainMap = 'world-map';
4224
+ * ```
4225
+ */
4226
+ mainMap: string
4227
+
4228
+ /**
4229
+ * CLIENT-ONLY. Master volume level for sound playback on the client (default `100`).
4230
+ *
4231
+ * @env Client
4232
+ *
4233
+ * @example
4234
+ * ```ts
4235
+ * // Set client master volume to 50%
4236
+ * VYLO.Client.volume = 50;
4237
+ * ```
4238
+ */
4239
+ volume: number;
4240
+
4241
+ /**
4242
+ * Checks whether the client is logged in with a guest account (e.g. `Guest`, `Guest-xxx`, or `Guest1234`).
4243
+ *
4244
+ * @env Client | Server
4245
+ * @returns {boolean} `true` if the connected account is a guest account; otherwise `false`.
4246
+ *
4247
+ * @example
4248
+ * ```ts
4249
+ * if (client.isGuest()) {
4250
+ * client.prompt('Register', 'Please create an account to save your progress!', (name) => { ... });
4251
+ * }
4252
+ * ```
4253
+ */
4254
+ isGuest(): boolean;
4255
+
4256
+ /**
4257
+ * The name of the macro atlas currently active for this client.
4258
+ *
4259
+ * @env Client | Server
4260
+ *
4261
+ * @example
4262
+ * ```ts
4263
+ * client.macroAtlas = 'default_controls';
4264
+ * ```
4265
+ */
4266
+ macroAtlas: string;
4267
+
4268
+ /**
4269
+ * CLIENT-ONLY. Flags the client interface layout to refresh and redraw on the next animation frame.
4270
+ *
4271
+ * @env Client
4272
+ * @param {number} [pPlane] - Optional interface plane index to refresh.
4273
+ *
4274
+ * @example
4275
+ * ```ts
4276
+ * VYLO.Client.refreshInterface();
4277
+ * ```
4278
+ */
4279
+ refreshInterface(pPlane?: number): void;
4280
+
2856
4281
  /**
2857
4282
  * Executes 2D canvas drawing commands onto the top screen surface named `pName`.
2858
4283
  *
@@ -3762,10 +5187,11 @@ declare global {
3762
5187
  * Removes an interface element from the interface.
3763
5188
  *
3764
5189
  * @env Client | Server
3765
- * @param {string} pInterface - Name of the interface to remove an interface element from.
3766
- * @param {string | number} pName - Name of the interface element to remove.
5190
+ * @param {string | InterfacePane} pInterface - Name of the interface (or InterfacePane instance) to remove an interface element from.
5191
+ * @param {string | number | Diob} [pName] - Optional name of the interface element or Diob element instance to remove.
5192
+ * @param {boolean} [pSave] - Optional flag indicating whether to keep the element instance from being deleted.
3767
5193
  */
3768
- removeInterfaceElement(pInterface: string, pName: string | number): void
5194
+ removeInterfaceElement(pInterface: string | InterfacePane, pName?: string | number | Diob, pSave?: boolean): void
3769
5195
 
3770
5196
  /**
3771
5197
  * Returns the dimensions `{ width, height }` of the client's render screen canvas in pixels.
@@ -3966,54 +5392,338 @@ declare global {
3966
5392
  * @param {number} pY - Vertical viewport coordinate of the cursor.
3967
5393
  */
3968
5394
  onMouseWheelScrollDown?(pDiob: Diob | 0, pX: number, pY: number): void
5395
+
5396
+ /**
5397
+ * CLIENT-ONLY. The current horizontal scroll position of the client's screen viewport in map pixels. Read-only.
5398
+ *
5399
+ * @env Client
5400
+ *
5401
+ * @example
5402
+ * ```ts
5403
+ * console.log('Current horizontal screen scroll:', VYLO.Client.xView);
5404
+ * ```
5405
+ */
5406
+ readonly xView: number;
5407
+
5408
+ /**
5409
+ * CLIENT-ONLY. The current vertical scroll position of the client's screen viewport in map pixels. Read-only.
5410
+ *
5411
+ * @env Client
5412
+ *
5413
+ * @example
5414
+ * ```ts
5415
+ * console.log('Current vertical screen scroll:', VYLO.Client.yView);
5416
+ * ```
5417
+ */
5418
+ readonly yView: number;
5419
+
5420
+ /**
5421
+ * CLIENT-ONLY. The underlying PixiJS Application instance managing the game canvas renderer (`ScreenManager.pixiApp`).
5422
+ *
5423
+ * @env Client
5424
+ */
5425
+ readonly renderApp: any;
5426
+
5427
+ /**
5428
+ * CLIENT-ONLY. Prompts the user to select one or more local files for upload, optionally posting them as multipart form data to `pURL`.
5429
+ *
5430
+ * @env Client
5431
+ * @param {string} [pURL] - Optional target endpoint URL to upload files to via POST.
5432
+ * @param {Record<string, string>} [pOptions] - Optional HTML attributes to set on the hidden `<input type="file">` element (such as `accept`, `multiple`).
5433
+ * @returns {Promise<string | void>} Resolves with the server's text response if uploaded to `pURL`, or resolves with void.
5434
+ *
5435
+ * @example
5436
+ * ```ts
5437
+ * await VYLO.Client.uploadFile('https://example.com/api/upload', { accept: 'image/*' });
5438
+ * ```
5439
+ */
5440
+ uploadFile(pURL?: string, pOptions?: Record<string, string>): Promise<string | void>;
5441
+
5442
+ /**
5443
+ * CLIENT-ONLY. Called when files are selected for upload via `uploadFile`.
5444
+ * Return `false` (or a Promise resolving to `false`) to cancel the upload.
5445
+ *
5446
+ * @env Client
5447
+ * @event
5448
+ * @param {FileList} pFiles - The native FileList containing the selected files.
5449
+ * @returns {boolean | Promise<boolean>} Return `false` to abort the upload; otherwise return `true`.
5450
+ */
5451
+ onFileUpload?(pFiles: FileList): boolean | Promise<boolean>;
5452
+
5453
+ /**
5454
+ * Called when a touch point is placed on the touch surface.
5455
+ *
5456
+ * @env Client | Server
5457
+ * @event
5458
+ * @param {Diob | 0} pDiob - The diob instance underneath the touch point, or `0` if empty map/screen.
5459
+ * @param {number} pX - Horizontal coordinate of the touch point on the screen.
5460
+ * @param {number} pY - Vertical coordinate of the touch point on the screen.
5461
+ * @param {TouchEvent} [pEvent] - (Optional) The native browser TouchEvent.
5462
+ *
5463
+ * @example
5464
+ * ```ts
5465
+ * client.onTouchStart = (pDiob, pX, pY, pEvent) => {
5466
+ * console.log(`Touch started at (${pX}, ${pY}) on`, pDiob);
5467
+ * };
5468
+ * ```
5469
+ */
5470
+ onTouchStart?(pDiob: Diob | 0, pX: number, pY: number, pEvent?: TouchEvent): void;
5471
+
5472
+ /**
5473
+ * Called when a touch point is removed from the touch surface.
5474
+ *
5475
+ * @env Client | Server
5476
+ * @event
5477
+ * @param {Diob | 0} pDiob - The diob instance underneath the touch point, or `0` if empty map/screen.
5478
+ * @param {number} pX - Horizontal coordinate of the touch point on the screen.
5479
+ * @param {number} pY - Vertical coordinate of the touch point on the screen.
5480
+ * @param {boolean} [pCancel] - (Optional) Whether the touch was cancelled (e.g. touchcancel event).
5481
+ * @param {TouchEvent} [pEvent] - (Optional) The native browser TouchEvent.
5482
+ */
5483
+ onTouchEnd?(pDiob: Diob | 0, pX: number, pY: number, pCancel?: boolean, pEvent?: TouchEvent): void;
5484
+
5485
+ /**
5486
+ * Called when a touch point is moved along the touch surface.
5487
+ *
5488
+ * @env Client | Server
5489
+ * @event
5490
+ * @param {Diob | 0} pDiob - The diob instance underneath the touch point, or `0` if empty map/screen.
5491
+ * @param {number} pX - Horizontal coordinate of the touch point on the screen.
5492
+ * @param {number} pY - Vertical coordinate of the touch point on the screen.
5493
+ * @param {TouchEvent} [pEvent] - (Optional) The native browser TouchEvent.
5494
+ */
5495
+ onTouchMove?(pDiob: Diob | 0, pX: number, pY: number, pEvent?: TouchEvent): void;
5496
+
3969
5497
  [key: string]: any
3970
5498
 
3971
5499
  }
3972
5500
 
3973
5501
 
3974
5502
 
3975
- /** The resource object. */
3976
- type Resource = {
5503
+ /** The resource object. */
5504
+ type Resource = {
5505
+
5506
+ /**
5507
+ * Sets a game resource to use the resource file located at `pPath`.
5508
+ *
5509
+ * @env Client | Server
5510
+ * @param {string} pType - Type of file to set.
5511
+ * @param {string | number} pName - Name of file to set. This will be referenced in the project. Example: if `pName` was set to `my_atlas` ( atlasName = `my_atlas` ).
5512
+ * @param {string} pPath - Path to the file. If not a remote file this will be the name of the file (or path if any sub directories were added) inside resources/files/ for the game, otherwise it will be a web URL path to the file.
5513
+ * @param {boolean} [pRemote] - (Optional) If set the `pPath` file will be treated like a web URL.
5514
+ * @param {boolean} [pShare] - (Optional) Server-only. If set, sends the resource declaration to all connected clients.
5515
+ */
5516
+ setResource(pType: string, pName: string | number, pPath: string, pRemote?: boolean, pShare?: boolean): void
5517
+
5518
+ /**
5519
+ * Returns an array of resource names registered for the given type, or all resources if no type is specified.
5520
+ *
5521
+ * @env Client | Server
5522
+ * @param {string} [pType] - (Optional) Resource type filter prefix (e.g. 'map', 'icon', 'interface', 'sound').
5523
+ * @returns {string[]} Array of resource names.
5524
+ */
5525
+ getResources(pType?: string): string[]
5526
+
5527
+ /**
5528
+ * Returns the direct path to the resource.
5529
+ *
5530
+ * @env Client | Server
5531
+ * @param {string} pType - Type of file to get.
5532
+ * @param {string | number} pName - Name of file to get.
5533
+ * @param {boolean} [pLocal] - (Optional) Client-only. If true, returns a path relative to the local server rather than the remote resource server.
5534
+ * @returns {string} Returns the direct path to the resource.
5535
+ */
5536
+ getResourcePath(pType: string, pName: string | number, pLocal?: boolean): string
5537
+
5538
+ /**
5539
+ * Loads the resource of type `pType` with the name `pName` and then calls the function `pFunc`.
5540
+ *
5541
+ * @env Client | Server
5542
+ * @param {string} pType - Type of file to load.
5543
+ * @param {string | number} pName - Name of file to load.
5544
+ * @param {Function} pFunc - Function to call after the resource has finished loading or failed to load.
5545
+ */
5546
+ loadResource(pType: string, pName: string | number, pFunc: Function): void
5547
+
5548
+ /**
5549
+ * Returns a string containing the text inside of a loaded non-VS text file. The file must already be loaded to get the text.
5550
+ *
5551
+ * @env Client | Server
5552
+ * @param {string | number} pName - Name of loaded file to get text of.
5553
+ * @returns {string} Returns a string containing the text inside of a loaded non-VS text file. The file must already be loaded to get the text.
5554
+ */
5555
+ getFileText(pName: string | number): string
5556
+
5557
+ }
5558
+
5559
+
5560
+
5561
+ /**
5562
+ * Extended mathematical utility functions provided by the Vylocity engine.
5563
+ * Accessible globally via `Math` or via `VYLO.Math`.
5564
+ */
5565
+ interface Math {
5566
+
5567
+ /**
5568
+ * Creates a two-dimensional matrix array populated with the supplied values.
5569
+ *
5570
+ * @env Client | Server
5571
+ * @param {number} pXLen - Number of rows (outer array length).
5572
+ * @param {number} pYLen - Number of columns (inner array length).
5573
+ * @param {...(number | string)[]} pValues - Optional sequence of numeric values or numeric strings to populate each matrix entry `[x][y]`.
5574
+ * @returns {any[][]} A 2D array representation.
5575
+ *
5576
+ * @example
5577
+ * ```ts
5578
+ * const matrix = Math.getMatrix(2, 2, 1, 2, 3, 4);
5579
+ * // returns [[1, 2], [3, 4]]
5580
+ * ```
5581
+ */
5582
+ getMatrix(pXLen: number, pYLen: number, ...pValues: (number | string)[]): any[][];
5583
+
5584
+ /**
5585
+ * Generates a pseudo-random integer between `pNum1` and `pNum2` (inclusive), or a random float between `0` and `1` if no arguments are passed.
5586
+ *
5587
+ * - If no arguments: returns `Math.random()` (float `[0, 1)`).
5588
+ * - If one argument `pNum1`: returns random integer between `0` and `pNum1` (inclusive).
5589
+ * - If two arguments `pNum1` and `pNum2`: returns random integer between `pNum1` and `pNum2` (inclusive).
5590
+ *
5591
+ * @env Client | Server
5592
+ * @param {number} [pNum1] - Lower bound (or upper bound if `pNum2` is omitted).
5593
+ * @param {number} [pNum2] - Upper bound.
5594
+ * @returns {number} The generated random number.
5595
+ *
5596
+ * @example
5597
+ * ```ts
5598
+ * const roll = Math.rand(1, 6); // Random integer 1 through 6
5599
+ * const val = Math.rand(10); // Random integer 0 through 10
5600
+ * ```
5601
+ */
5602
+ rand(pNum1?: number, pNum2?: number): number;
5603
+
5604
+ /**
5605
+ * Generates a pseudo-random floating point number between `pNum1` and `pNum2`.
5606
+ *
5607
+ * - If no arguments: returns `Math.random()`.
5608
+ * - If one argument `pNum1`: returns float between `0` and `pNum1 + 1`.
5609
+ * - If two arguments `pNum1` and `pNum2`: returns float between `pNum1` and `pNum2`.
5610
+ *
5611
+ * @env Client | Server
5612
+ * @param {number} [pNum1] - Lower bound (or upper bound if `pNum2` is omitted).
5613
+ * @param {number} [pNum2] - Upper bound.
5614
+ * @returns {number} The generated random float.
5615
+ *
5616
+ * @example
5617
+ * ```ts
5618
+ * const speed = Math.randFloat(1.5, 3.5);
5619
+ * ```
5620
+ */
5621
+ randFloat(pNum1?: number, pNum2?: number): number;
5622
+
5623
+ /**
5624
+ * Rounds a floating-point number to a specified number of decimal places.
5625
+ *
5626
+ * @env Client | Server
5627
+ * @param {number} pNum - Number to round.
5628
+ * @param {number} [pDecimal=0] - Number of decimal places to preserve (default `0`).
5629
+ * @returns {number} The rounded floating-point number.
5630
+ *
5631
+ * @example
5632
+ * ```ts
5633
+ * Math.roundFloat(3.14159, 2); // 3.14
5634
+ * ```
5635
+ */
5636
+ roundFloat(pNum: number, pDecimal?: number): number;
5637
+
5638
+ /**
5639
+ * Performs a percentage-based probability check.
5640
+ *
5641
+ * Returns `true` if a random check between 0 and 100 succeeds given percentage `pProb` (0-100), otherwise `false`.
5642
+ *
5643
+ * @env Client | Server
5644
+ * @param {number} pProb - Probability percentage between 0 and 100 (e.g. 50 for a 50% chance).
5645
+ * @returns {boolean} `true` if the roll succeeds; otherwise `false`.
5646
+ *
5647
+ * @example
5648
+ * ```ts
5649
+ * if (Math.prob(25)) {
5650
+ * // 25% chance of critical hit
5651
+ * }
5652
+ * ```
5653
+ */
5654
+ prob(pProb: number): boolean;
3977
5655
 
3978
5656
  /**
3979
- * Sets a game resource to use the resource file located at `pPath`.
5657
+ * Clamps a numeric value between a minimum and maximum boundary.
3980
5658
  *
3981
5659
  * @env Client | Server
3982
- * @param {string} pType - Type of file to set.
3983
- * @param {string | number} pName - Name of file to set. This will be referenced in the project. Example: if `pName` was set to `my_atlas` ( atlasName = `my_atlas` ).
3984
- * @param {string} pPath - Path to the file. If not a remote file this will be the name of the file (or path if any sub directories were added) inside resources/files/ for the game, otherwise it will be a web URL path to the file.
3985
- * @param {boolean} [pRemote] - (Optional) If set the `pPath` file will be treated like a web URL.
5660
+ * @param {number} pVal - The numeric value to clamp.
5661
+ * @param {number} pMin - The lower boundary.
5662
+ * @param {number} pMax - The upper boundary.
5663
+ * @returns {number} Clamped value within `[pMin, pMax]`.
5664
+ *
5665
+ * @example
5666
+ * ```ts
5667
+ * const health = Math.clamp(currentHealth - damage, 0, maxHealth);
5668
+ * ```
3986
5669
  */
3987
- setResource(pType: string, pName: string | number, pPath: string, pRemote?: boolean): void
5670
+ clamp(pVal: number, pMin: number, pMax: number): number;
3988
5671
 
3989
- /**
3990
- * Returns the direct path to the resource.
3991
- *
3992
- * @env Client | Server
3993
- * @param {string} pType - Type of file to get.
3994
- * @param {string | number} pName - Name of file to get.
3995
- * @returns {string} Returns the direct path to the resource.
3996
- */
3997
- getResourcePath(pType: string, pName: string | number): string
5672
+ /**
5673
+ * Linearly interpolates between two numbers `pA` and `pB` by factor `pT`.
5674
+ *
5675
+ * Formula: `pA * (1 - pT) + pB * pT`.
5676
+ *
5677
+ * @env Client | Server
5678
+ * @param {number} pA - Starting value.
5679
+ * @param {number} pB - Ending value.
5680
+ * @param {number} pT - Interpolation weight (typically between 0 and 1).
5681
+ * @returns {number} The interpolated value.
5682
+ *
5683
+ * @example
5684
+ * ```ts
5685
+ * const currentX = Math.lerp(startX, targetX, 0.1);
5686
+ * ```
5687
+ */
5688
+ lerp(pA: number, pB: number, pT: number): number;
3998
5689
 
3999
- /**
4000
- * Loads the resource of type `pType` with the name `pName` and then calls the function `pFunc`.
4001
- *
4002
- * @env Client | Server
4003
- * @param {string} pType - Type of file to load.
4004
- * @param {string | number} pName - Name of file to load.
4005
- * @param {Function} pFunc - Function to call after the resource has finished loading or failed to load.
4006
- */
4007
- loadResource(pType: string, pName: string | number, pFunc: Function): void
5690
+ /**
5691
+ * Normalizes a value `pVal` within range `[pMin, pMax]` to a `0` to `1` range.
5692
+ *
5693
+ * Formula: `(pVal - pMin) / (pMax - pMin)`.
5694
+ *
5695
+ * @env Client | Server
5696
+ * @param {number} pVal - Value to normalize.
5697
+ * @param {number} pMin - Minimum range value.
5698
+ * @param {number} pMax - Maximum range value.
5699
+ * @returns {number} Normalized value between 0 and 1.
5700
+ *
5701
+ * @example
5702
+ * ```ts
5703
+ * const ratio = Math.normalize(50, 0, 200); // 0.25
5704
+ * ```
5705
+ */
5706
+ normalize(pVal: number, pMin: number, pMax: number): number;
4008
5707
 
4009
- /**
4010
- * Returns a string containing the text inside of a loaded non-VS text file. The file must already be loaded to get the text.
4011
- *
4012
- * @env Client | Server
4013
- * @param {string | number} pName - Name of loaded file to get text of.
4014
- * @returns {string} Returns a string containing the text inside of a loaded non-VS text file. The file must already be loaded to get the text.
4015
- */
4016
- getFileText(pName: string | number): string
5708
+ /**
5709
+ * Remaps a number from one numeric range `[pLow1, pHigh1]` to another `[pLow2, pHigh2]`.
5710
+ *
5711
+ * Formula: `pLow2 + (pVal - pLow1) * (pHigh2 - pLow2) / (pHigh1 - pLow1)`.
5712
+ *
5713
+ * @env Client | Server
5714
+ * @param {number} pVal - Value to remap.
5715
+ * @param {number} pLow1 - Lower bound of the source range.
5716
+ * @param {number} pHigh1 - Upper bound of the source range.
5717
+ * @param {number} pLow2 - Lower bound of the target range.
5718
+ * @param {number} pHigh2 - Upper bound of the target range.
5719
+ * @returns {number} The remapped value.
5720
+ *
5721
+ * @example
5722
+ * ```ts
5723
+ * const mapped = Math.remap(5, 0, 10, 0, 100); // 50
5724
+ * ```
5725
+ */
5726
+ remap(pVal: number, pLow1: number, pHigh1: number, pLow2: number, pHigh2: number): number;
4017
5727
 
4018
5728
  }
4019
5729
 
@@ -4240,272 +5950,628 @@ declare global {
4240
5950
  * @param {unknown} pVal - Value to check for function.
4241
5951
  * @returns {boolean} Returns `true` if value is a function. Returns `false` if value is not a function.
4242
5952
  */
4243
- isFunction(pVal: unknown): pVal is (...args: any[]) => any
5953
+ isFunction(pVal: unknown): pVal is (...args: any[]) => any
5954
+
5955
+ /**
5956
+ * Returns an array containing the values all of key names (variable names) of `pO`.
5957
+ *
5958
+ * @env Client | Server
5959
+ * @param {object} pO - Object to get key names from.
5960
+ * @returns {string[]} Returns an array containing the values all of key names (variable names) of `pO`.
5961
+ */
5962
+ getObjectKeys(pO: object): string[]
5963
+
5964
+ /**
5965
+ * Converts an ArrayBuffer to a base64 string.
5966
+ *
5967
+ * @env Client | Server
5968
+ * @param {ArrayBuffer} pArrBuff - ArrayBuffer to convert to base64.
5969
+ * @returns {string} Base64 string.
5970
+ */
5971
+ arrayBufferToBase64(pArrBuff: ArrayBuffer): string
5972
+
5973
+ /**
5974
+ * Returns `pVal` converted to a string value.
5975
+ *
5976
+ * @env Client | Server
5977
+ * @param {any} pVal - Value to get string from.
5978
+ * @returns {string} Returns `pVal` converted to a string value.
5979
+ */
5980
+ toString(pVal: any): string
5981
+
5982
+ /**
5983
+ * Returns new text that has been decoded.
5984
+ *
5985
+ * @env Client | Server
5986
+ * @param {string} pText - Text to decode.
5987
+ * @returns {string} Returns new text that has been decoded.
5988
+ */
5989
+ decodeURIComponent(pText: string): string
5990
+
5991
+ /**
5992
+ * Gets all the variables that can be saved and returns a new object that contains those values which can then be saved (no internal engine variables, no functions, no references to Vylocity Objects).
5993
+ *
5994
+ * @env Client | Server
5995
+ * @param {object} pS - Object to get saveable values from.
5996
+ * @param {object} [pO] - (Optional) Alter this object and return it as the return object.
5997
+ * @returns {Record<string, any>} Returns a new object that contains those values which can then be saved (no internal engine variables, no functions, no references to Vylocity Objects).
5998
+ */
5999
+ getSaveObject<T extends object = Record<string, any>>(pS: object, pO?: object): T
6000
+
6001
+ /**
6002
+ * Returns the numeric compass index of the specified direction name in the engine's direction lookup table.
6003
+ *
6004
+ * @env Client | Server
6005
+ * @param {Direction | string} pDir - Direction name.
6006
+ * @returns {number} Numeric compass index of direction.
6007
+ */
6008
+ getDirNum(pDir: Direction | string): number
6009
+
6010
+ }
6011
+
6012
+
6013
+
6014
+ /** The event object. */
6015
+ type Event = {
6016
+
6017
+ /**
6018
+ * Remove `pO` to the ticker.
6019
+ *
6020
+ * @env Client | Server
6021
+ * @param {Diob} pO - Reference to the object.
6022
+ */
6023
+ removeTicker(pO: Diob | Object | object): void
6024
+
6025
+ /**
6026
+ * Add `pO` to the ticker.
6027
+ *
6028
+ * @env Client | Server
6029
+ * @param {Diob | Object | object} pO - Reference to the object.
6030
+ * @param {object} [pS] - (Optional) An object containing settings for this object's ticker.
6031
+ */
6032
+ addTicker(pO: Diob | Object | object, pS?: object): void
6033
+
6034
+ /**
6035
+ * Forces a thread to stop doing its executions.
6036
+ *
6037
+ * @env Client | Server
6038
+ * @param {boolean} pVal - Variable linking to the thread to be interrupted.
6039
+ */
6040
+ interruptThread(pVal: boolean): void
6041
+
6042
+ /**
6043
+ * Returns an array of all active objects with tickers running.
6044
+ *
6045
+ * @env Client | Server
6046
+ * @returns {Diob[] | Object[]} Returns an array of all active objects with tickers running.
6047
+ */
6048
+ getTickers(): Diob[] | Object[]
6049
+
6050
+ /**
6051
+ * Prevents a specific spawn from occuring.
6052
+ *
6053
+ * @env Client | Server
6054
+ * @param {boolean} pVal - Variable linking to the spawn to be interrupted.
6055
+ */
6056
+ interruptSpawn(pVal: boolean): void
6057
+
6058
+ /**
6059
+ * Pauses or resumes all tickers.
6060
+ *
6061
+ * @env Client | Server
6062
+ * @param {boolean} [pBool] - (Optional) True or `false`.
6063
+ */
6064
+ toggleTicker(pBool?: boolean): void
6065
+
6066
+ }
6067
+
6068
+
6069
+
6070
+ /** The file object. */
6071
+ type File = {
6072
+
6073
+ /**
6074
+ * Checks if `pFile` exists.
6075
+ *
6076
+ * @env Server
6077
+ * @param {string} pFile - Path to the file or directory to check.
6078
+ * @param {Function} pFunc - Function to call after `pPath` has been checked. First argument `pExists` determines if `pPath` exists or not.
6079
+ */
6080
+ exists(pFile: string, pFunc: Function): void
6081
+
6082
+ /**
6083
+ * Asynchronously retrieves filesystem metadata and statistics for the file or directory located at `pPath`.
6084
+ *
6085
+ * @env Server
6086
+ * @param {string} pPath - Path to the file or directory (relative to the game `files/` root).
6087
+ * @param {(pStats?: FileStats, pErr?: any) => void} pFunc - Callback invoked with the `FileStats` object and any error encountered.
6088
+ *
6089
+ * @example
6090
+ * ```ts
6091
+ * VYLO.File.getStats('saves/player1.json', (stats, err) => {
6092
+ * if (!err && stats) {
6093
+ * console.log('File size in bytes:', stats.size);
6094
+ * }
6095
+ * });
6096
+ * ```
6097
+ */
6098
+ getStats(pPath: string, pFunc: (pStats?: FileStats, pErr?: any) => void): void
6099
+
6100
+ /**
6101
+ * Reads the data and returns the data in `pFunc`.
6102
+ *
6103
+ * @env Server
6104
+ * @param {string} pFile - Path to the file.
6105
+ * @param {Function} pFunc - Function to call after reading is complete. First argument `pData` is set to the data read. Second arg `pErr` is set if an error has occured.
6106
+ * @returns {void} Returns the data in `pFunc`.
6107
+ */
6108
+ readText(pFile: string, pFunc: Function): void
6109
+
6110
+ /**
6111
+ * Creates `pFile` if it does not exist and then saves the `pSave` object to the file. Overwrites existing data.
6112
+ *
6113
+ * @env Server
6114
+ * @param {string} pFile - Path to the file.
6115
+ * @param {object} pSave - Object to save to the file for example ( `{'value1': 1, 'value2': 2}` ).
6116
+ * @param {Function} pFunc - Function to call after writing is complete. First argument `pErr` is set if an error has occured.
6117
+ */
6118
+ writeSave(pFile: string, pSave: object, pFunc: Function): void
6119
+
6120
+ /**
6121
+ * Creates `pFile` if needed and then add `pData` to the end of the file.
6122
+ *
6123
+ * @env Server
6124
+ * @param {string} pFile - Path to the file.
6125
+ * @param {string} pData - Text to add to the end of `pFile`.
6126
+ * @param {Function} pFunc - Function to call after appending is complete. First argument `pErr` is set if an error has occured.
6127
+ */
6128
+ appendText(pFile: string, pData: string, pFunc: Function): void
6129
+
6130
+ /**
6131
+ * Provides an array of files in `pPath` directory.
6132
+ *
6133
+ * @env Server
6134
+ * @param {string} pPath - Path to the directory.
6135
+ * @param {Function} pFunc - Function to call after the directory has been read. First argument `pFiles` is an array of the files in the directory, second argument `pErr` is an error if there is one.
6136
+ */
6137
+ readDir(pPath: string, pFunc: Function): void
4244
6138
 
4245
6139
  /**
4246
- * Returns an array containing the values all of key names (variable names) of `pO`.
6140
+ * Deletes the file or directory at `pPath`. All child files are also deleted.
4247
6141
  *
4248
- * @env Client | Server
4249
- * @param {object} pO - Object to get key names from.
4250
- * @returns {string[]} Returns an array containing the values all of key names (variable names) of `pO`.
6142
+ * @env Server
6143
+ * @param {string} pPath - Path to the file or directory to delete.
6144
+ * @param {Function} pFunc - Function to call after `pPath` has been removed.
4251
6145
  */
4252
- getObjectKeys(pO: object): string[]
6146
+ remove(pPath: string, pFunc: Function): void
4253
6147
 
4254
6148
  /**
4255
- * Converts an ArrayBuffer to a base64 string.
6149
+ * Inspects `pPath` and invokes `pFunc` with a `FileStats` object describing file attributes and directory status.
4256
6150
  *
4257
- * @env Client | Server
4258
- * @param {ArrayBuffer} pArrBuff - ArrayBuffer to convert to base64.
4259
- * @returns {string} Base64 string.
6151
+ * @env Server
6152
+ * @param {string} pPath - Path to the file or directory to inspect.
6153
+ * @param {(pStat?: FileStats, pErr?: any) => void} pFunc - Callback invoked with `FileStats` and error object.
6154
+ *
6155
+ * @example
6156
+ * ```ts
6157
+ * VYLO.File.stat('data', (stat, err) => {
6158
+ * if (stat?.isDirectory()) {
6159
+ * console.log('Path is a directory');
6160
+ * }
6161
+ * });
6162
+ * ```
4260
6163
  */
4261
- arrayBufferToBase64(pArrBuff: ArrayBuffer): string
6164
+ stat(pPath: string, pFunc: (pStat?: FileStats, pErr?: any) => void): void
4262
6165
 
4263
6166
  /**
4264
- * Returns `pVal` converted to a string value.
6167
+ * Creates a new directory at the location of `pPath`.
4265
6168
  *
4266
- * @env Client | Server
4267
- * @param {any} pVal - Value to get string from.
4268
- * @returns {string} Returns `pVal` converted to a string value.
6169
+ * @env Server
6170
+ * @param {string} pPath - Path to create the new directory.
6171
+ * @param {Function} pFunc - Function to call after the directory has been made.
4269
6172
  */
4270
- toString(pVal: any): string
6173
+ makeDir(pPath: string, pFunc: Function): void
4271
6174
 
4272
6175
  /**
4273
- * Returns new text that has been decoded.
6176
+ * Returns an array of file names inside the `pPath` dir and calls `pFunc` with the first argument being the array and the second being an error (if any).
4274
6177
  *
4275
- * @env Client | Server
4276
- * @param {string} pText - Text to decode.
4277
- * @returns {string} Returns new text that has been decoded.
6178
+ * @env Server
6179
+ * @param {string} pPath - Path to the directory to get contents of.
6180
+ * @param {Function} pFunc - Function to call after.
6181
+ * @returns {string[]} Returns an array of file names inside the `pPath` dir and calls `pFunc` with the first argument being the array and the second being an error (if any).
4278
6182
  */
4279
- decodeURIComponent(pText: string): string
6183
+ getDir(pPath: string, pFunc: Function): string[]
4280
6184
 
4281
6185
  /**
4282
- * Gets all the variables that can be saved and returns a new object that contains those values which can then be saved (no internal engine variables, no functions, no references to Vylocity Objects).
6186
+ * Reads `pFile` JSON save data and passes the parsed object to `pFunc`.
4283
6187
  *
4284
- * @env Client | Server
4285
- * @param {object} pS - Object to get saveable values from.
4286
- * @param {object} [pO] - (Optional) Alter this object and return it as the return object.
4287
- * @returns {Record<string, any>} Returns a new object that contains those values which can then be saved (no internal engine variables, no functions, no references to Vylocity Objects).
6188
+ * @env Server
6189
+ * @param {string} pFile - Path to the file.
6190
+ * @param {(pData?: Record<string, any>, pErr?: any) => void} pFunc - Callback receiving the parsed data object or error.
6191
+ *
6192
+ * @example
6193
+ * ```ts
6194
+ * VYLO.File.readSave('saves/profile.json', (data, err) => {
6195
+ * if (!err && data) {
6196
+ * console.log('Loaded save profile:', data);
6197
+ * }
6198
+ * });
6199
+ * ```
4288
6200
  */
4289
- getSaveObject<T extends object = Record<string, any>>(pS: object, pO?: object): T
6201
+ readSave(pFile: string, pFunc: (pData?: Record<string, any>, pErr?: any) => void): void
4290
6202
 
4291
6203
  /**
4292
- * Returns the numeric compass index of the specified direction name in the engine's direction lookup table.
6204
+ * Creates `pFile` if needed and then writes `pData` to the file. Overwrites existing data.
4293
6205
  *
4294
- * @env Client | Server
4295
- * @param {Direction | string} pDir - Direction name.
4296
- * @returns {number} Numeric compass index of direction.
6206
+ * @env Server
6207
+ * @param {string} pFile - Path to the file.
6208
+ * @param {string} pData - Text to put into the file.
6209
+ * @param {Function} pFunc - Function to call after writing is complete. First argument `pErr` is set if an error occurs.
4297
6210
  */
4298
- getDirNum(pDir: Direction | string): number
6211
+ writeText(pFile: string, pData: string, pFunc?: (pErr?: any) => void): void
6212
+
6213
+ /**
6214
+ * Asynchronously writes resource data directly into the game's `resources/` directory.
6215
+ *
6216
+ * @env Server
6217
+ * @param {string} pFile - Resource file path relative to the `resources/` folder.
6218
+ * @param {any} pData - Data content to write to the file.
6219
+ * @returns {Promise<void>}
6220
+ */
6221
+ writeResource(pFile: string, pData: any): Promise<void>
4299
6222
 
4300
6223
  }
4301
6224
 
4302
6225
 
4303
6226
 
4304
- /** The event object. */
4305
- type Event = {
6227
+ /**
6228
+ * Represents an icon atlas containing multiple icons and textures.
6229
+ */
6230
+ interface IconAtlas {
6231
+ /** Name of the icon atlas. */
6232
+ name: string;
6233
+ /** Underlying atlas texture. */
6234
+ texture: any;
6235
+ /**
6236
+ * Adds one or more icons to this atlas.
6237
+ *
6238
+ * @env Client
6239
+ * @param {...Icon[]} pIcons - Icon instances to add.
6240
+ */
6241
+ addIcon(...pIcons: Icon[]): void;
6242
+ /**
6243
+ * Inserts one or more icons at the specified index or before an icon.
6244
+ *
6245
+ * @env Client
6246
+ * @param {number | Icon} pIndex - Insertion index or target icon.
6247
+ * @param {...Icon[]} pIcons - Icons to insert.
6248
+ */
6249
+ insertIcon(pIndex: number | Icon, ...pIcons: Icon[]): void;
6250
+ /**
6251
+ * Creates and adds a new icon to this atlas.
6252
+ *
6253
+ * @env Client
6254
+ * @param {any} pData - Image data or URL.
6255
+ * @param {string} pName - Name of the icon.
6256
+ * @param {number} [pW] - Width in pixels.
6257
+ * @param {number} [pH] - Height in pixels.
6258
+ * @param {number} [pDelay] - Animation frame delay in milliseconds.
6259
+ * @returns {Icon} The newly created Icon instance.
6260
+ */
6261
+ newIcon(pData: any, pName: string, pW?: number, pH?: number, pDelay?: number): Icon;
6262
+ /**
6263
+ * Removes one or more icons from this atlas.
6264
+ *
6265
+ * @env Client
6266
+ * @param {...(Icon | string)[]} pIcons - Icons or icon names to remove.
6267
+ */
6268
+ removeIcon(...pIcons: (Icon | string)[]): void;
6269
+ /**
6270
+ * Removes icons within the specified index range.
6271
+ *
6272
+ * @env Client
6273
+ * @param {number} [pStart] - Start index.
6274
+ * @param {number} [pEnd] - End index.
6275
+ */
6276
+ removeIconAt(pStart?: number, pEnd?: number): void;
6277
+ /**
6278
+ * Destroys this icon atlas and frees resources.
6279
+ *
6280
+ * @env Client
6281
+ */
6282
+ destroy(): void;
6283
+ /**
6284
+ * Clones this icon atlas.
6285
+ *
6286
+ * @env Client
6287
+ * @returns {IconAtlas}
6288
+ */
6289
+ clone(): IconAtlas;
6290
+ /**
6291
+ * Returns an array of icon names in this atlas, optionally matching a regular expression.
6292
+ *
6293
+ * @env Client
6294
+ * @param {RegExp} [pRegex] - Optional regex filter.
6295
+ * @returns {string[]} Array of icon names.
6296
+ */
6297
+ getIconNames(pRegex?: RegExp): string[];
6298
+ [key: string]: any;
6299
+ }
6300
+
6301
+ /** The icon object. */
6302
+ type Icon = {
4306
6303
 
4307
6304
  /**
4308
- * Remove `pO` to the ticker.
6305
+ * Read-only flag indicating this is an Icon.
4309
6306
  *
4310
- * @env Client | Server
4311
- * @param {Diob} pO - Reference to the object.
6307
+ * @env Client
4312
6308
  */
4313
- removeTicker(pO: Diob | Object | object): void
6309
+ readonly isIcon?: boolean;
4314
6310
 
4315
- /**
4316
- * Add `pO` to the ticker.
4317
- *
4318
- * @env Client | Server
4319
- * @param {Diob | Object | object} pO - Reference to the object.
4320
- * @param {object} [pS] - (Optional) An object containing settings for this object's ticker.
4321
- */
4322
- addTicker(pO: Diob | Object | object, pS?: object): void
6311
+ /**
6312
+ * Parent state icon if this icon is an icon state.
6313
+ *
6314
+ * @env Client
6315
+ */
6316
+ readonly isState?: any;
4323
6317
 
4324
- /**
4325
- * Forces a thread to stop doing its executions.
4326
- *
4327
- * @env Client | Server
4328
- * @param {boolean} pVal - Variable linking to the thread to be interrupted.
4329
- */
4330
- interruptThread(pVal: boolean): void
6318
+ /**
6319
+ * True if this icon is an animation frame of another icon.
6320
+ *
6321
+ * @env Client
6322
+ */
6323
+ readonly isFrame?: boolean;
4331
6324
 
4332
- /**
4333
- * Returns an array of all active objects with tickers running.
4334
- *
4335
- * @env Client | Server
4336
- * @returns {Diob[] | Object[]} Returns an array of all active objects with tickers running.
4337
- */
4338
- getTickers(): Diob[] | Object[]
6325
+ /**
6326
+ * Underlying rendering texture (e.g. PIXI.Texture).
6327
+ *
6328
+ * @env Client
6329
+ */
6330
+ texture?: any;
4339
6331
 
4340
- /**
4341
- * Prevents a specific spawn from occuring.
4342
- *
4343
- * @env Client | Server
4344
- * @param {boolean} pVal - Variable linking to the spawn to be interrupted.
4345
- */
4346
- interruptSpawn(pVal: boolean): void
6332
+ /**
6333
+ * Base texture of the icon atlas.
6334
+ *
6335
+ * @env Client
6336
+ */
6337
+ readonly atlasTexture?: any;
4347
6338
 
4348
- /**
4349
- * Pauses or resumes all tickers.
4350
- *
4351
- * @env Client | Server
4352
- * @param {boolean} [pBool] - (Optional) True or `false`.
4353
- */
4354
- toggleTicker(pBool?: boolean): void
6339
+ /**
6340
+ * The IconAtlas instance this icon belongs to.
6341
+ *
6342
+ * @env Client
6343
+ */
6344
+ atlas?: any;
4355
6345
 
4356
- }
6346
+ /**
6347
+ * Name of the icon atlas this icon belongs to.
6348
+ *
6349
+ * @env Client
6350
+ */
6351
+ atlasName?: string;
4357
6352
 
6353
+ /**
6354
+ * Name of this icon.
6355
+ *
6356
+ * @env Client
6357
+ */
6358
+ iconName?: string;
4358
6359
 
6360
+ /**
6361
+ * State name of this icon (empty string for default state).
6362
+ *
6363
+ * @env Client
6364
+ */
6365
+ iconState?: string;
4359
6366
 
4360
- /** The file object. */
4361
- type File = {
6367
+ /**
6368
+ * Width of this icon in pixels.
6369
+ *
6370
+ * @env Client
6371
+ */
6372
+ width?: number;
6373
+
6374
+ /**
6375
+ * Height of this icon in pixels.
6376
+ *
6377
+ * @env Client
6378
+ */
6379
+ height?: number;
6380
+
6381
+ /**
6382
+ * Frame delay duration in milliseconds.
6383
+ *
6384
+ * @env Client
6385
+ */
6386
+ frameDelay?: number;
6387
+
6388
+ /**
6389
+ * Parent icon or state if nested.
6390
+ *
6391
+ * @env Client
6392
+ */
6393
+ parent?: any;
6394
+
6395
+ /**
6396
+ * Image data source or base64 data URL.
6397
+ *
6398
+ * @env Client
6399
+ */
6400
+ imageData?: any;
6401
+
6402
+ /**
6403
+ * Adds one or more state icons to this icon.
6404
+ *
6405
+ * @env Client
6406
+ * @param {...Icon[]} pIcons - Icon instances to add as states.
6407
+ */
6408
+ addState?(...pIcons: Icon[]): void;
6409
+
6410
+ /**
6411
+ * Inserts one or more state icons at the specified index.
6412
+ *
6413
+ * @env Client
6414
+ * @param {number | Icon} pIndex - Insertion index or target icon.
6415
+ * @param {...Icon[]} pIcons - Icon instances to insert.
6416
+ */
6417
+ insertState?(pIndex: number | Icon, ...pIcons: Icon[]): void;
6418
+
6419
+ /**
6420
+ * Removes one or more state icons from this icon.
6421
+ *
6422
+ * @env Client
6423
+ * @param {...(Icon | string)[]} pIcons - States or state names to remove.
6424
+ */
6425
+ removeState?(...pIcons: (Icon | string)[]): void;
6426
+
6427
+ /**
6428
+ * Removes state icons within the specified index range.
6429
+ *
6430
+ * @env Client
6431
+ * @param {number} [pStart] - Start index.
6432
+ * @param {number} [pEnd] - End index.
6433
+ */
6434
+ removeStateAt?(pStart?: number, pEnd?: number): void;
6435
+
6436
+ /**
6437
+ * Creates and adds a new state to this icon.
6438
+ *
6439
+ * @env Client
6440
+ * @param {any} pData - Image data or URL.
6441
+ * @param {string} pName - Name of the new state.
6442
+ * @param {number} [pDelay] - Animation frame delay in milliseconds.
6443
+ * @returns {Icon} The newly created state Icon.
6444
+ */
6445
+ newState?(pData: any, pName: string, pDelay?: number): Icon;
4362
6446
 
4363
6447
  /**
4364
- * Checks if `pFile` exists.
6448
+ * Adds one or more frame icons to this icon.
4365
6449
  *
4366
- * @env Server
4367
- * @param {string} pFile - Path to the file or directory to check.
4368
- * @param {Function} pFunc - Function to call after `pPath` has been checked. First argument `pExists` determines if `pPath` exists or not.
6450
+ * @env Client
6451
+ * @param {...Icon[]} pIcons - Icon instances to add as animation frames.
4369
6452
  */
4370
- exists(pFile: string, pFunc: Function): void
4371
-
4372
- /**
4373
- * Asynchronously retrieves filesystem metadata and statistics for the file or directory located at `pPath`.
4374
- *
4375
- * @env Server
4376
- * @param {string} pPath - Path to the file or directory (relative to the game `files/` root).
4377
- * @param {(pStats?: FileStats, pErr?: any) => void} pFunc - Callback invoked with the `FileStats` object and any error encountered.
4378
- *
4379
- * @example
4380
- * ```ts
4381
- * VYLO.File.getStats('saves/player1.json', (stats, err) => {
4382
- * if (!err && stats) {
4383
- * console.log('File size in bytes:', stats.size);
4384
- * }
4385
- * });
4386
- * ```
4387
- */
4388
- getStats(pPath: string, pFunc: (pStats?: FileStats, pErr?: any) => void): void
6453
+ addFrame?(...pIcons: Icon[]): void;
4389
6454
 
4390
- /**
4391
- * Reads the data and returns the data in `pFunc`.
4392
- *
4393
- * @env Server
4394
- * @param {string} pFile - Path to the file.
4395
- * @param {Function} pFunc - Function to call after reading is complete. First argument `pData` is set to the data read. Second arg `pErr` is set if an error has occured.
4396
- * @returns {void} Returns the data in `pFunc`.
4397
- */
4398
- readText(pFile: string, pFunc: Function): void
6455
+ /**
6456
+ * Inserts one or more frame icons at the specified index.
6457
+ *
6458
+ * @env Client
6459
+ * @param {number | Icon} pIndex - Insertion index or target frame.
6460
+ * @param {...Icon[]} pIcons - Frame instances to insert.
6461
+ */
6462
+ insertFrame?(pIndex: number | Icon, ...pIcons: Icon[]): void;
4399
6463
 
4400
- /**
4401
- * Creates `pFile` if it does not exist and then saves the `pSave` object to the file. Overwrites existing data.
4402
- *
4403
- * @env Server
4404
- * @param {string} pFile - Path to the file.
4405
- * @param {object} pSave - Object to save to the file for example ( `{'value1': 1, 'value2': 2}` ).
4406
- * @param {Function} pFunc - Function to call after writing is complete. First argument `pErr` is set if an error has occured.
4407
- */
4408
- writeSave(pFile: string, pSave: object, pFunc: Function): void
6464
+ /**
6465
+ * Removes one or more frame icons from this icon.
6466
+ *
6467
+ * @env Client
6468
+ * @param {...Icon[]} pIcons - Frame instances to remove.
6469
+ */
6470
+ removeFrame?(...pIcons: Icon[]): void;
4409
6471
 
4410
- /**
4411
- * Creates `pFile` if needed and then add `pData` to the end of the file.
4412
- *
4413
- * @env Server
4414
- * @param {string} pFile - Path to the file.
4415
- * @param {string} pData - Text to add to the end of `pFile`.
4416
- * @param {Function} pFunc - Function to call after appending is complete. First argument `pErr` is set if an error has occured.
4417
- */
4418
- appendText(pFile: string, pData: string, pFunc: Function): void
6472
+ /**
6473
+ * Removes animation frames within the specified index range.
6474
+ *
6475
+ * @env Client
6476
+ * @param {number} [pStart] - Start frame index.
6477
+ * @param {number} [pEnd] - End frame index.
6478
+ */
6479
+ removeFrameAt?(pStart?: number, pEnd?: number): void;
4419
6480
 
4420
- /**
4421
- * Provides an array of files in `pPath` directory.
4422
- *
4423
- * @env Server
4424
- * @param {string} pPath - Path to the directory.
4425
- * @param {Function} pFunc - Function to call after the directory has been read. First argument `pFiles` is an array of the files in the directory, second argument `pErr` is an error if there is one.
4426
- */
4427
- readDir(pPath: string, pFunc: Function): void
6481
+ /**
6482
+ * Creates and adds a new animation frame to this icon.
6483
+ *
6484
+ * @env Client
6485
+ * @param {any} pData - Image data or URL.
6486
+ * @param {number} [pDelay] - Frame delay duration in milliseconds.
6487
+ * @returns {Icon} The newly created frame Icon.
6488
+ */
6489
+ newFrame?(pData: any, pDelay?: number): Icon;
4428
6490
 
4429
- /**
4430
- * Deletes the file or directory at `pPath`. All child files are also deleted.
4431
- *
4432
- * @env Server
4433
- * @param {string} pPath - Path to the file or directory to delete.
4434
- * @param {Function} pFunc - Function to call after `pPath` has been removed.
4435
- */
4436
- remove(pPath: string, pFunc: Function): void
6491
+ /**
6492
+ * Removes this icon from its parent atlas, state, or frame container.
6493
+ *
6494
+ * @env Client
6495
+ */
6496
+ remove?(): void;
4437
6497
 
4438
- /**
4439
- * Inspects `pPath` and invokes `pFunc` with a `FileStats` object describing file attributes and directory status.
4440
- *
4441
- * @env Server
4442
- * @param {string} pPath - Path to the file or directory to inspect.
4443
- * @param {(pStat?: FileStats, pErr?: any) => void} pFunc - Callback invoked with `FileStats` and error object.
4444
- *
4445
- * @example
4446
- * ```ts
4447
- * VYLO.File.stat('data', (stat, err) => {
4448
- * if (stat?.isDirectory()) {
4449
- * console.log('Path is a directory');
4450
- * }
4451
- * });
4452
- * ```
4453
- */
4454
- stat(pPath: string, pFunc: (pStat?: FileStats, pErr?: any) => void): void
6498
+ /**
6499
+ * Destroys this icon and frees associated texture and memory.
6500
+ *
6501
+ * @env Client
6502
+ * @param {boolean} [pSkip] - Whether to skip removing from parent tracking.
6503
+ */
6504
+ destroy?(pSkip?: boolean): void;
4455
6505
 
4456
- /**
4457
- * Creates a new directory at the location of `pPath`.
4458
- *
4459
- * @env Server
4460
- * @param {string} pPath - Path to create the new directory.
4461
- * @param {Function} pFunc - Function to call after the directory has been made.
4462
- */
4463
- makeDir(pPath: string, pFunc: Function): void
6506
+ /**
6507
+ * Returns the raw base64 data URL string for this icon's image.
6508
+ *
6509
+ * @env Client
6510
+ * @returns {string} Data URL string.
6511
+ */
6512
+ getDataURL?(): string;
4464
6513
 
4465
- /**
4466
- * Returns an array of file names inside the `pPath` dir and calls `pFunc` with the first argument being the array and the second being an error (if any).
4467
- *
4468
- * @env Server
4469
- * @param {string} pPath - Path to the directory to get contents of.
4470
- * @param {Function} pFunc - Function to call after.
4471
- * @returns {string[]} Returns an array of file names inside the `pPath` dir and calls `pFunc` with the first argument being the array and the second being an error (if any).
4472
- */
4473
- getDir(pPath: string, pFunc: Function): string[]
6514
+ /**
6515
+ * Retrieves the raw pixel ImageData of this icon.
6516
+ *
6517
+ * @env Client
6518
+ * @returns {any} ImageData instance.
6519
+ */
6520
+ getRawData?(): any;
4474
6521
 
4475
- /**
4476
- * Reads `pFile` JSON save data and passes the parsed object to `pFunc`.
4477
- *
4478
- * @env Server
4479
- * @param {string} pFile - Path to the file.
4480
- * @param {(pData?: Record<string, any>, pErr?: any) => void} pFunc - Callback receiving the parsed data object or error.
4481
- *
4482
- * @example
4483
- * ```ts
4484
- * VYLO.File.readSave('saves/profile.json', (data, err) => {
4485
- * if (!err && data) {
4486
- * console.log('Loaded save profile:', data);
4487
- * }
4488
- * });
4489
- * ```
4490
- */
4491
- readSave(pFile: string, pFunc: (pData?: Record<string, any>, pErr?: any) => void): void
6522
+ /**
6523
+ * Updates this icon's pixels using the provided ImageData.
6524
+ *
6525
+ * @env Client
6526
+ * @param {any} pData - ImageData object.
6527
+ * @returns {Promise<void>}
6528
+ */
6529
+ setRawData?(pData: any): Promise<void>;
4492
6530
 
4493
- /**
4494
- * Creates `pFile` if needed and then writes `pData` to the file. Overwrites existing data.
4495
- *
4496
- * @env Server
4497
- * @param {string} pFile - Path to the file.
4498
- * @param {string} pData - Text to put into the file.
4499
- * @param {Function} pFunc - Function to call after writing is complete. First argument `pErr` is set if an error occurs.
4500
- */
4501
- writeText(pFile: string, pData: string, pFunc?: (pErr?: any) => void): void
6531
+ /**
6532
+ * Sets this icon's image content from an image URL.
6533
+ *
6534
+ * @env Client
6535
+ * @param {string} pData - Image URL or data URL.
6536
+ * @returns {Promise<void>}
6537
+ */
6538
+ setDataFromURL?(pData: string): Promise<void>;
4502
6539
 
4503
- }
6540
+ /**
6541
+ * Sets this icon's image content from a file path.
6542
+ *
6543
+ * @env Client
6544
+ * @param {string} pPath - File path to the image.
6545
+ * @returns {Promise<void>}
6546
+ */
6547
+ setDataFromFile?(pPath: string): Promise<void>;
4504
6548
 
6549
+ /**
6550
+ * Sets this icon's image content from a registered resource.
6551
+ *
6552
+ * @env Client
6553
+ * @param {string} pType - Resource type.
6554
+ * @param {string} pName - Resource name.
6555
+ * @returns {Promise<void>}
6556
+ */
6557
+ setDataFromResource?(pType: string, pName: string): Promise<void>;
4505
6558
 
6559
+ /**
6560
+ * Creates a clone of this icon.
6561
+ *
6562
+ * @env Client
6563
+ * @returns {Icon}
6564
+ */
6565
+ clone?(): Icon;
4506
6566
 
4507
- /** The icon object. */
4508
- type Icon = {
6567
+ /**
6568
+ * Returns an array of state names belonging to this icon.
6569
+ *
6570
+ * @env Client
6571
+ * @param {RegExp} [pRegex] - Optional regex filter.
6572
+ * @returns {string[]} Array of state names.
6573
+ */
6574
+ getStateNames?(pRegex?: RegExp): string[];
4509
6575
 
4510
6576
  /**
4511
6577
  * Creates a new blank icon named `pIcon` inside of the atlas `pAtlas`.
@@ -4739,6 +6805,27 @@ declare global {
4739
6805
  */
4740
6806
  applyFilter(pFilter: object, pAtlas: string, pIcon: string, pState?: string, pFrame?: number, pFunc?: Function): void
4741
6807
 
6808
+ /**
6809
+ * Creates and returns a new rendering sprite (e.g. `PIXI.Sprite`) using the texture from the specified icon, state, or frame.
6810
+ *
6811
+ * @env Client
6812
+ * @param {string} pAtlas - Name of the icon atlas.
6813
+ * @param {string} pIcon - Name of the icon.
6814
+ * @param {string} [pState] - Optional icon state name.
6815
+ * @param {number} [pFrame] - Optional 1-based frame index number.
6816
+ * @returns {any} A sprite display object referencing the icon texture.
6817
+ */
6818
+ createSprite(pAtlas: string, pIcon: string, pState?: string, pFrame?: number): any
6819
+
6820
+ /**
6821
+ * Creates and returns a new graphics display object (e.g. `PIXI.Graphics`).
6822
+ *
6823
+ * @env Client
6824
+ * @param {...any[]} pArgs - Optional constructor arguments passed to graphics initialization.
6825
+ * @returns {any} A graphics canvas display instance.
6826
+ */
6827
+ createGraphics(...pArgs: any[]): any
6828
+
4742
6829
  }
4743
6830
 
4744
6831
 
@@ -4746,6 +6833,65 @@ declare global {
4746
6833
  /** The map object. */
4747
6834
  type Map = {
4748
6835
 
6836
+ /**
6837
+ * Read-only boolean flag indicating this is a Map instance.
6838
+ *
6839
+ * @env Client | Server
6840
+ */
6841
+ readonly isMap?: boolean;
6842
+
6843
+ /**
6844
+ * Display name of this map.
6845
+ *
6846
+ * @env Client | Server
6847
+ */
6848
+ name?: string;
6849
+
6850
+ /**
6851
+ * System identifier name of this map.
6852
+ *
6853
+ * @env Client | Server
6854
+ */
6855
+ mapName?: string;
6856
+
6857
+ /**
6858
+ * Number of horizontal tile columns in this map.
6859
+ *
6860
+ * @env Client | Server
6861
+ */
6862
+ xMax?: number;
6863
+
6864
+ /**
6865
+ * Number of vertical tile rows in this map.
6866
+ *
6867
+ * @env Client | Server
6868
+ */
6869
+ yMax?: number;
6870
+
6871
+ /**
6872
+ * Total width of this map in pixels.
6873
+ *
6874
+ * @env Client | Server
6875
+ */
6876
+ width?: number;
6877
+
6878
+ /**
6879
+ * Total height of this map in pixels.
6880
+ *
6881
+ * @env Client | Server
6882
+ */
6883
+ height?: number;
6884
+
6885
+ /**
6886
+ * Resizes this map to the specified tile coordinates.
6887
+ *
6888
+ * @env Client | Server
6889
+ * @param {number} pX - Horizontal size in tiles.
6890
+ * @param {number} [pY] - Vertical size in tiles (defaults to pX).
6891
+ * @param {string} [pTile] - Default tile type for new tiles.
6892
+ */
6893
+ setSizeByCoords?(pX: number, pY?: number, pTile?: string): void;
6894
+
4749
6895
  /**
4750
6896
  * Returns number of tiles between `pA` and `pB`.
4751
6897
  *
@@ -4756,17 +6902,18 @@ declare global {
4756
6902
  */
4757
6903
  getTileDist(pA: Diob | Object, pB: Diob | Object): number
4758
6904
 
4759
- /**
4760
- * Returns an array of diobs on the map `pMap` depending on the provided arguments. If `pType` is not set, all diobs on the map will be returned. If `pType` is set but `pChild` is not, diobs on the map with the exact type of `pType` will be returned. If `pType` is set and `pChild` is set, all diobs with the type `pType` or a parent type of `pType` will be returned. For example, if `pType` is set to `Mob` with `pChild` `undefined`, all diobs with the exact type of `Mob` will be returned, but if `pChild` is set, then all mobs on the map will be returned.
4761
- *
4762
- * @env Client | Server
4763
- * @param {string} pMap - Name of the map to get diobs from.
4764
- * @param {string} [pType] - (Optional) String containing type path to return.
4765
- * @param {boolean} [pChild] - (Optional) Boolean that determines if child types are included.
4766
- * @param {Diob[]} [pAdd] - (Optional) If set, tiles and regions on the map will also be returned.
4767
- * @returns {Diob[]} Returns an array of diobs on the map `pMap` depending on the provided arguments. If `pType` is not set, all diobs on the map will be returned. If `pType` is set but `pChild` is not, diobs on the map with the exact type of `pType` will be returned. If `pType` is set and `pChild` is set, all diobs with the type `pType` or a parent type of `pType` will be returned. For example, if `pType` is set to `Mob` with `pChild` `undefined`, all diobs with the exact type of `Mob` will be returned, but if `pChild` is set, then all mobs on the map will be returned.
4768
- */
4769
- getDiobs(pMap: string, pType?: string, pChild?: boolean, pAdd?: Diob[]): Diob[]
6905
+ /**
6906
+ * Returns an array of diobs on this map or on map `pMap` depending on the provided arguments.
6907
+ * When called on a Map instance, `pType` can be passed as the first parameter.
6908
+ *
6909
+ * @env Client | Server
6910
+ * @param {string} [pMapOrType] - Name of the map or type path filter.
6911
+ * @param {string | boolean} [pTypeOrChild] - String containing type path or boolean for child types.
6912
+ * @param {boolean} [pChild] - (Optional) Boolean that determines if child types are included.
6913
+ * @param {Diob[]} [pAdd] - (Optional) If set, tiles and regions on the map will also be returned.
6914
+ * @returns {Diob[]} Array of diobs matching the query.
6915
+ */
6916
+ getDiobs(pMapOrType?: string, pTypeOrChild?: string | boolean, pChild?: boolean, pAdd?: Diob[]): Diob[];
4770
6917
 
4771
6918
  /**
4772
6919
  * Changes the sized of `pMap` to the width and height of `pW` and `pH`. Reducing the size will delete diobs that are no longer within the map size.
@@ -4800,25 +6947,25 @@ declare global {
4800
6947
  setLoc(pLoc: Diob | Object, pT: string): Diob
4801
6948
 
4802
6949
  /**
4803
- * Returns the tiles on `pMap` within the specified area. If no area is specified, all tiles will be returned.
6950
+ * Returns the tiles within the specified area. Can be called on a Map instance with `(pX, pY, pW, pH)` or statically with `(pMap, pX, pY, pW, pH)`.
4804
6951
  *
4805
6952
  * @env Client | Server
4806
- * @param {string} pMap - Name of the map to get tiles from.
4807
- * @param {number} [pX] - (Optional) Starting x coordinate.
4808
- * @param {number} [pY] - (Optional) Starting y coordinate.
4809
- * @param {number} [pW] - (Optional) Number of tiles to get from the right of `pX`. Negative numbers to get tiles from the left.
4810
- * @param {number} [pH] - (Optional) Number of tiles to get from below `pY`. Negative numbers to get tiles from above.
4811
- * @returns {Diob[]} Returns the tiles on `pMap` within the specified area. If no area is specified, all tiles will be returned.
6953
+ * @param {string | number} [pMapOrX] - Name of map or starting x coordinate.
6954
+ * @param {number} [pXOrY] - Starting x coordinate or starting y coordinate.
6955
+ * @param {number} [pYOrW] - Starting y coordinate or width.
6956
+ * @param {number} [pWOrH] - Width in tiles or height in tiles.
6957
+ * @param {number} [pH] - Height in tiles.
6958
+ * @returns {Diob[]} Returns the tiles on the map within the specified area.
4812
6959
  */
4813
- getTiles(pMap: string, pX?: number, pY?: number, pW?: number, pH?: number): Diob[]
6960
+ getTiles(pMapOrX?: string | number, pXOrY?: number, pYOrW?: number, pWOrH?: number, pH?: number): Diob[];
4814
6961
 
4815
6962
  /**
4816
- * Returns an array of diobs on the map `pMap` that have the tag `pTag`.
6963
+ * Returns an array of diobs on the map that have the tag `pTag`.
4817
6964
  *
4818
6965
  * @env Client | Server
4819
6966
  * @param {string} pTag - String containing tag to look for.
4820
- * @param {string} [pMap] - (Optional) Name of map to search.
4821
- * @returns {Diob[]} Returns an array of diobs on the map `pMap` that have the tag `pTag`.
6967
+ * @param {string} [pMap] - (Optional) Name of map to search if called statically.
6968
+ * @returns {Diob[]} Returns an array of diobs that have the tag `pTag`.
4822
6969
  */
4823
6970
  getDiobsByTag(pTag: string, pMap?: string): Diob[]
4824
6971
 
@@ -5125,6 +7272,16 @@ declare global {
5125
7272
  */
5126
7273
  createMap(pName: string | number, pX: number, pY: number, pTile: string): void
5127
7274
 
7275
+ /**
7276
+ * Creates a map by parsing raw map text file data and initializing all tiles, objects, and overlays.
7277
+ *
7278
+ * @env Client | Server
7279
+ * @param {string} pName - Name to assign to the newly created map.
7280
+ * @param {string} pText - Raw map file text data to parse.
7281
+ * @param {Function} [pFunc] - Optional callback function invoked once the map finishes parsing and loading.
7282
+ */
7283
+ createMapFromText(pName: string, pText: string, pFunc?: Function): void
7284
+
5128
7285
  /**
5129
7286
  * Sends the data for the `pD` diob to all clients on the `pMap` map, if `pVar` is set it will send only those variables, if it is not set it will only send built-in engine variables.
5130
7287
  *
@@ -5382,6 +7539,8 @@ declare global {
5382
7539
  Map: Map
5383
7540
  /** The type object. */
5384
7541
  Type: Type
7542
+ /** The math object. */
7543
+ Math: Math
5385
7544
 
5386
7545
  /**
5387
7546
  * The global object referencing all global variables in VyScript.
@@ -5438,4 +7597,4 @@ declare global {
5438
7597
  }
5439
7598
 
5440
7599
 
5441
- export { VyloType, World, Diob, Movable, Particle, Tile, Region, Mob, Overlay, Sound, Interface, Client, Resource, Util, Icon, Macro, Type, MouseButton, MouseOpacity, Direction, Directions, MoveSettingsConfig, AppearMask, AppearMaskConfig };
7600
+ export { VyloType, World, Diob, MapObject, Movable, Particle, Tile, Region, Mob, Overlay, Sound, Interface, InterfacePane, WebBox, TextInput, Client, Resource, Util, Icon, IconAtlas, Macro, Type, ObjectType, MouseButton, MouseOpacity, Direction, Directions, MoveSettingsConfig, AppearMask, AppearMaskConfig };