@momo2555/koppeliajs 0.0.162 → 0.0.163

package/dist/scripts/console.d.ts

@@ -11,7 +11,8 @@ export type AnyRequestCallback = (request: string, params: {
 }, from: string, address: string) => void;
 export type MediaResponseData = string | Blob | ArrayBuffer | any;
 /**
- * This class defines the Koppelia console to send and receive requests.
+ * Handles the Koppelia console connection, facilitating the sending and receiving of requests
+ * and managing event subscriptions for state changes, device data, and custom logic.
  */
 export declare class Console {
     consoleHostname: string;
@@ -27,85 +28,110 @@ export declare class Console {
     private _mediaApiUrl;
     constructor();
     /**
-     * Generates a unique random ID for callback registration.
+     * Generates a unique random ID used for registering and tracking callbacks.
+     * @returns A randomly generated string ID.
      */
     private _generateId;
     /**
-     * Unsubscribes a previously registered callback using its ID.
-     * @param id The identifier returned by the "on..." functions.
-     * @returns true if the ID was found and deleted, false otherwise.
+     * Unsubscribes a previously registered callback using its unique ID.
+     * @param id The subscription identifier returned by any "on..." listener function.
+     * @returns True if the ID was found and successfully removed, false otherwise.
      */
     unsubscribeCallback(id: string): boolean;
     /**
-     * Sends a message to the console. Set header.to to dispatch the message.
-     * @param message The message to send.
-     * @param callback The callback triggered when the websocket receives a response.
+     * Dispatches a message through the console socket.
+     * The routing source is automatically appended based on the current application state.
+     * @param message The message payload to send.
+     * @param callback Optional callback triggered when the WebSocket receives a specific response.
      */
     sendMessage(message: Message, callback?: Callback): void;
     /**
-     * Identifies the page (controller or monitor) to the console.
+     * Identifies the current client application (controller or monitor) to the console.
      * @param peer The peer type to identify as.
      */
     identify(peer: PeerType): void;
+    /**
+     * Retrieves the list of connected devices.
+     * @todo Implementation pending.
+     */
     getConnectedDevices(): void;
     /**
-     * Sends data to a specific peer.
-     * @param receiver The peer type receiving the data.
-     * @param data The data payload.
+     * Transmits data payload directly to a specific peer type.
+     * @param receiver The target peer intended to receive the data.
+     * @param data The data payload to transmit.
      */
     sendDataTo(receiver: PeerType, data: MessageData): void;
     /**
-     * Adds a callback to be executed when a new state is received from the console.
-     * @param callback Function to execute on state change.
-     * @returns The subscription ID.
+     * Registers a callback to execute whenever a new state is received from the console.
+     * @param callback The function to execute on state change.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onStateChange(callback: ChangeStateCallback): string;
     /**
-     * Adds a callback to be executed when the current stage changes.
-     * @param callback Function to execute on stage change.
-     * @returns The subscription ID.
+     * Registers a callback to execute whenever the current application stage changes.
+     * @param callback The function to execute on stage change.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onStageChange(callback: ChangeStageCallback): string;
     /**
-     * Adds a callback to be executed when the console is ready.
-     * If the console is already ready, the function is called immediately.
-     * @param callback Function to execute.
-     * @returns The subscription ID.
+     * Registers a callback to execute when the console connection is fully established and ready.
+     * If the console is already ready at the time of calling, the callback is executed immediately.
+     * @param callback The function to execute upon readiness.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onReady(callback: () => void): string;
     /**
-     * Adds a callback to listen for device events.
-     * @param callback Function to execute on device event.
-     * @returns The subscription ID.
+     * Registers a callback to listen for specific device events.
+     * @param callback The function to execute when a device event occurs.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onDeviceEvent(callback: DeviceEventCallback): string;
     /**
-     * Adds a callback to listen for data exchanges.
-     * @param callback Function to execute on data exchange.
-     * @returns The subscription ID.
+     * Registers a callback to listen for raw data exchanges between peers.
+     * @param callback The function to execute upon receiving exchanged data.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onDataExchange(callback: DataExchangeCallback): string;
     /**
-     * Adds a callback to listen for generic requests.
-     * @param callback Function to execute on request.
-     * @returns The subscription ID.
+     * Registers a generic callback to intercept and handle custom or unrecognized requests.
+     * @param callback The function to execute for generic requests.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onRequest(callback: AnyRequestCallback): string;
     /**
-     * Gets the current readiness state of the console connection.
+     * Gets the current readiness state of the console WebSocket connection.
      */
     get ready(): boolean;
+    /**
+     * Constructs the full URL for a media asset based on the API port and hostname.
+     * @param path The relative path to the media asset.
+     * @returns The fully qualified URL string.
+     */
     getMediaUrl(path: string): string;
     /**
-     * Normalizes the media URL to ensure it works for both the controller and the monitor.
-     * Sometimes, a link retrieved from one client is saved as a game state, but fails
-     * when accessed by the other client. Wrapping all media URLs with this function is best practice.
-     * @param mediaUrl The original media URL.
-     * @returns The corrected URL string.
+     * Normalizes a media URL to ensure cross-client compatibility.
+     * Corrects edge cases where media links cached in game states by one client (e.g., controller)
+     * fail when accessed by another (e.g., monitor).
+     * @param mediaUrl The raw URL string to fix.
+     * @returns The corrected and standardized URL string.
      */
     fixMediaUrl(mediaUrl: string): string;
+    /**
+     * Fetches a media asset from the API and automatically parses it based on its Content-Type.
+     * @param path The relative path to the media asset.
+     * @returns A promise resolving to the parsed data (JSON, Text, Blob, or ArrayBuffer).
+     * @throws Will throw an error if the HTTP request fails.
+     */
     getMedia(path: string): Promise<MediaResponseData>;
+    /**
+     * Initializes core WebSocket event listeners and maps them to the internal handlers.
+     */
     private _initEvents;
+    /**
+     * Core router for incoming WebSocket data. Decodes the message type and
+     * dispatches it to the corresponding internal execution loops.
+     * @param request The parsed Message object received from the socket.
+     */
     private _processReceivedData;
     private _execDeviceDataHandlers;
     private _execDeviceEventHandlers;
@@ -114,7 +140,7 @@ export declare class Console {
     private _execDataExchangeHandlers;
     private _execAnyRequestHandlers;
     /**
-     * Clears all registered event handlers.
+     * Hard-resets the application by clearing all registered event handlers.
      */
     destroyEvents(): void;
 }

package/dist/scripts/console.js

@@ -7,12 +7,12 @@ import { logger } from "./logger.js";
 const PORT = 2225;
 const API_PORT = 8000;
 /**
- * This class defines the Koppelia console to send and receive requests.
+ * Handles the Koppelia console connection, facilitating the sending and receiving of requests
+ * and managing event subscriptions for state changes, device data, and custom logic.
  */
 export class Console {
     consoleHostname = "";
     consoleSocket;
-    // Event handlers stored as dictionaries (Record) for ID-based subscription management
     _changeStateHandlers;
     _changeStageHandlers;
     _deviceEventHandlers;
@@ -31,7 +31,6 @@ export class Console {
         this.consoleSocket = new KoppeliaWebsocket(consoleUrl);
         this._mediaApiUrl = "http://" + this.consoleHostname + ":" + API_PORT;
         this._ready = false;
-        // Initialize dictionaries
         this._changeStateHandlers = {};
         this._changeStageHandlers = {};
         this._deviceEventHandlers = {};
@@ -42,16 +41,17 @@ export class Console {
         this._initEvents();
     }
     /**
-     * Generates a unique random ID for callback registration.
+     * Generates a unique random ID used for registering and tracking callbacks.
+     * @returns A randomly generated string ID.
      */
     _generateId() {
         return Math.random().toString(36).substring(2, 15) +
             Math.random().toString(36).substring(2, 15);
     }
     /**
-     * Unsubscribes a previously registered callback using its ID.
-     * @param id The identifier returned by the "on..." functions.
-     * @returns true if the ID was found and deleted, false otherwise.
+     * Unsubscribes a previously registered callback using its unique ID.
+     * @param id The subscription identifier returned by any "on..." listener function.
+     * @returns True if the ID was found and successfully removed, false otherwise.
      */
     unsubscribeCallback(id) {
         let deleted = false;
@@ -86,9 +86,10 @@ export class Console {
         return deleted;
     }
     /**
-     * Sends a message to the console. Set header.to to dispatch the message.
-     * @param message The message to send.
-     * @param callback The callback triggered when the websocket receives a response.
+     * Dispatches a message through the console socket.
+     * The routing source is automatically appended based on the current application state.
+     * @param message The message payload to send.
+     * @param callback Optional callback triggered when the WebSocket receives a specific response.
      */
     sendMessage(message, callback) {
         let route = PeerType.NONE;
@@ -102,7 +103,7 @@ export class Console {
         this.consoleSocket.send(message, callback);
     }
     /**
-     * Identifies the page (controller or monitor) to the console.
+     * Identifies the current client application (controller or monitor) to the console.
      * @param peer The peer type to identify as.
      */
     identify(peer) {
@@ -110,12 +111,16 @@ export class Console {
         req.setIdentification(peer);
         this.consoleSocket.send(req);
     }
+    /**
+     * Retrieves the list of connected devices.
+     * @todo Implementation pending.
+     */
     getConnectedDevices() {
     }
     /**
-     * Sends data to a specific peer.
-     * @param receiver The peer type receiving the data.
-     * @param data The data payload.
+     * Transmits data payload directly to a specific peer type.
+     * @param receiver The target peer intended to receive the data.
+     * @param data The data payload to transmit.
      */
     sendDataTo(receiver, data) {
         let req = new Message();
@@ -123,9 +128,9 @@ export class Console {
         req.setDestination(receiver);
     }
     /**
-     * Adds a callback to be executed when a new state is received from the console.
-     * @param callback Function to execute on state change.
-     * @returns The subscription ID.
+     * Registers a callback to execute whenever a new state is received from the console.
+     * @param callback The function to execute on state change.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onStateChange(callback) {
         const id = this._generateId();
@@ -133,9 +138,9 @@ export class Console {
         return id;
     }
     /**
-     * Adds a callback to be executed when the current stage changes.
-     * @param callback Function to execute on stage change.
-     * @returns The subscription ID.
+     * Registers a callback to execute whenever the current application stage changes.
+     * @param callback The function to execute on stage change.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onStageChange(callback) {
         const id = this._generateId();
@@ -143,10 +148,10 @@ export class Console {
         return id;
     }
     /**
-     * Adds a callback to be executed when the console is ready.
-     * If the console is already ready, the function is called immediately.
-     * @param callback Function to execute.
-     * @returns The subscription ID.
+     * Registers a callback to execute when the console connection is fully established and ready.
+     * If the console is already ready at the time of calling, the callback is executed immediately.
+     * @param callback The function to execute upon readiness.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onReady(callback) {
         const id = this._generateId();
@@ -159,9 +164,9 @@ export class Console {
         return id;
     }
     /**
-     * Adds a callback to listen for device events.
-     * @param callback Function to execute on device event.
-     * @returns The subscription ID.
+     * Registers a callback to listen for specific device events.
+     * @param callback The function to execute when a device event occurs.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onDeviceEvent(callback) {
         const id = this._generateId();
@@ -169,9 +174,9 @@ export class Console {
         return id;
     }
     /**
-     * Adds a callback to listen for data exchanges.
-     * @param callback Function to execute on data exchange.
-     * @returns The subscription ID.
+     * Registers a callback to listen for raw data exchanges between peers.
+     * @param callback The function to execute upon receiving exchanged data.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onDataExchange(callback) {
         const id = this._generateId();
@@ -179,9 +184,9 @@ export class Console {
         return id;
     }
     /**
-     * Adds a callback to listen for generic requests.
-     * @param callback Function to execute on request.
-     * @returns The subscription ID.
+     * Registers a generic callback to intercept and handle custom or unrecognized requests.
+     * @param callback The function to execute for generic requests.
+     * @returns The unique subscription ID used for unsubscribing.
      */
     onRequest(callback) {
         const id = this._generateId();
@@ -189,22 +194,27 @@ export class Console {
         return id;
     }
     /**
-     * Gets the current readiness state of the console connection.
+     * Gets the current readiness state of the console WebSocket connection.
      */
     get ready() {
         return this._ready;
     }
+    /**
+     * Constructs the full URL for a media asset based on the API port and hostname.
+     * @param path The relative path to the media asset.
+     * @returns The fully qualified URL string.
+     */
     getMediaUrl(path) {
         if (!path.startsWith("/"))
             path = "/" + path;
         return this._mediaApiUrl + path;
     }
     /**
-     * Normalizes the media URL to ensure it works for both the controller and the monitor.
-     * Sometimes, a link retrieved from one client is saved as a game state, but fails
-     * when accessed by the other client. Wrapping all media URLs with this function is best practice.
-     * @param mediaUrl The original media URL.
-     * @returns The corrected URL string.
+     * Normalizes a media URL to ensure cross-client compatibility.
+     * Corrects edge cases where media links cached in game states by one client (e.g., controller)
+     * fail when accessed by another (e.g., monitor).
+     * @param mediaUrl The raw URL string to fix.
+     * @returns The corrected and standardized URL string.
      */
     fixMediaUrl(mediaUrl) {
         let url = new URL(mediaUrl);
@@ -213,6 +223,12 @@ export class Console {
         fixedurl.search = url.search;
         return fixedurl.toString();
     }
+    /**
+     * Fetches a media asset from the API and automatically parses it based on its Content-Type.
+     * @param path The relative path to the media asset.
+     * @returns A promise resolving to the parsed data (JSON, Text, Blob, or ArrayBuffer).
+     * @throws Will throw an error if the HTTP request fails.
+     */
     async getMedia(path) {
         const response = await fetch(this.getMediaUrl(path));
         if (!response.ok) {
@@ -220,19 +236,22 @@ export class Console {
         }
         const contentType = response.headers.get("Content-Type") || "";
         if (contentType.includes("application/json")) {
-            return await response.json(); // Returns an Object
+            return await response.json();
         }
         else if (contentType.startsWith("text/")) {
-            return await response.text(); // Returns a String
+            return await response.text();
         }
         else if (contentType.startsWith("image/") ||
             contentType.includes("application/octet-stream")) {
-            return await response.blob(); // Returns a Blob (images, downloads, etc.)
+            return await response.blob();
         }
         else {
-            return await response.arrayBuffer(); // Returns a Generic binary buffer
+            return await response.arrayBuffer();
         }
     }
+    /**
+     * Initializes core WebSocket event listeners and maps them to the internal handlers.
+     */
     _initEvents() {
         this.consoleSocket.onOpen(() => {
             this._ready = true;
@@ -244,13 +263,17 @@ export class Console {
             this._processReceivedData(request);
         });
     }
+    /**
+     * Core router for incoming WebSocket data. Decodes the message type and
+     * dispatches it to the corresponding internal execution loops.
+     * @param request The parsed Message object received from the socket.
+     */
     _processReceivedData(request) {
         logger.log("Received new data from console", request);
         if (request.header.type === undefined) {
             return;
         }
         let type = request.header.type;
-        /* Handle specific requests */
         if (type == MessageType.REQUEST) {
             switch (request.request.exec) {
                 case "changeState":
@@ -264,18 +287,18 @@ export class Console {
                     this._execAnyRequestHandlers(request.request.exec, request.request.params, request.header.from, request.header.from_addr);
                     break;
             }
-        } /* Handle data exchange */
+        }
         else if (type == MessageType.DATA_EXCHANGE) {
             this._execDataExchangeHandlers(request.header.from, request.data);
-        } /* Handle device event */
+        }
         else if (type == MessageType.DEVICE_EVENT) {
             this._execDeviceEventHandlers(request.header.device, request.header.from_addr, request.event);
-        } /* Handle device data */
+        }
         else if (type == MessageType.DEVICE_DATA) {
             this._execDeviceDataHandlers(request.header.from_addr, request.data);
         }
     }
-    // Handler execution methods iterating over dictionary values
+    // --- Dictionary execution methods below ---
     _execDeviceDataHandlers(from_addr, data) {
         for (let handler of Object.values(this._deviceDataHandlers)) {
             handler(from_addr, data);
@@ -307,10 +330,9 @@ export class Console {
         }
     }
     /**
-     * Clears all registered event handlers.
+     * Hard-resets the application by clearing all registered event handlers.
      */
     destroyEvents() {
-        // Reset dictionaries to empty objects
         this._deviceEventHandlers = {};
         this._deviceDataHandlers = {};
         this._anyRequestHandlers = {};

package/dist/scripts/customCallback.d.ts

@@ -1,13 +1,31 @@
 import type { Console } from "./console.js";
+/**
+ * Manages the registration and network-wide execution of custom callbacks.
+ * Allows different nodes in the system to broadcast and react to custom function calls.
+ */
 export declare class CustomCallbacks {
     private _console;
     private _customCallbacks;
     constructor(console: Console);
+    /**
+     * Broadcasts a request across the network to execute a registered custom callback.
+     * @param name The registered name of the custom callback to trigger.
+     * @param args A dictionary of arguments to pass to the callback function.
+     */
     runCustomCallback(name: string, args: {
         [key: string]: any;
     }): void;
+    /**
+     * Registers a local function to be executed when a specific custom callback request is received.
+     * @param name The identifier name for this callback.
+     * @param callback The function to execute when triggered by the network.
+     */
     registerCustomCallback(name: string, callback: (args: {
         [key: string]: any;
     }) => void): void;
+    /**
+     * Removes a previously registered custom callback from the local listener registry.
+     * @param name The identifier name of the callback to remove.
+     */
     unregisterCustomCallback(name: string): void;
 }

package/dist/scripts/customCallback.js

@@ -1,5 +1,9 @@
 import { logger } from "./logger.js";
 import { Message, MessageType, PeerType } from "./message.js";
+/**
+ * Manages the registration and network-wide execution of custom callbacks.
+ * Allows different nodes in the system to broadcast and react to custom function calls.
+ */
 export class CustomCallbacks {
     _console;
     _customCallbacks;
@@ -9,25 +13,39 @@ export class CustomCallbacks {
         });
         this._customCallbacks = {};
         this._console.onDataExchange((from, data) => {
-            if (data.custumCallbackName != undefined &&
+            if (data.customCallbackName != undefined &&
                 data.customCallbackArgs != undefined) {
-                if (Object.hasOwn(this._customCallbacks, data.custumCallbackName)) {
-                    this._customCallbacks[data.custumCallbackName](data.customCallbackArgs);
+                if (Object.hasOwn(this._customCallbacks, data.customCallbackName)) {
+                    this._customCallbacks[data.customCallbackName](data.customCallbackArgs);
                 }
             }
         });
     }
+    /**
+     * Broadcasts a request across the network to execute a registered custom callback.
+     * @param name The registered name of the custom callback to trigger.
+     * @param args A dictionary of arguments to pass to the callback function.
+     */
     runCustomCallback(name, args) {
         let customCallbackRequest = new Message();
         customCallbackRequest.setType(MessageType.DATA_EXCHANGE);
-        customCallbackRequest.addData("custumCallbackName", name);
+        customCallbackRequest.addData("customCallbackName", name);
         customCallbackRequest.addData("customCallbackArgs", args);
         customCallbackRequest.setDestination(PeerType.BROADCAST, "");
         this._console.sendMessage(customCallbackRequest);
     }
+    /**
+     * Registers a local function to be executed when a specific custom callback request is received.
+     * @param name The identifier name for this callback.
+     * @param callback The function to execute when triggered by the network.
+     */
     registerCustomCallback(name, callback) {
         this._customCallbacks[name] = callback;
     }
+    /**
+     * Removes a previously registered custom callback from the local listener registry.
+     * @param name The identifier name of the callback to remove.
+     */
     unregisterCustomCallback(name) {
         if (Object.hasOwn(this._customCallbacks, name)) {
             delete this._customCallbacks[name];

package/dist/scripts/device.d.ts

@@ -1,8 +1,5 @@
 import { Console } from "./console.js";
 import { Resident } from "./resident.js";
-/**
- * This class reprensts a device
- */
 type Color = {
     r: number;
     g: number;
@@ -10,6 +7,10 @@ type Color = {
     lon?: number;
     loff?: number;
 };
+/**
+ * Represents a physical or logical device connected to the console.
+ * Handles device-specific commands like LEDs, vibrations, and hardware module subscriptions.
+ */
 export declare class Device {
     private _address;
     private _color;
@@ -21,32 +22,66 @@ export declare class Device {
     constructor(console: Console, address?: string);
     get color(): Color;
     get name(): string;
+    /**
+     * Subscribes to a specific hardware event for this device.
+     * @param eventName The name of the event to listen to.
+     * @param callback Function to execute when the event is triggered.
+     */
     onEvent(eventName: string, callback: () => void): void;
+    /**
+     * Enables the cursor module and listens for coordinate updates.
+     * @param callback Function to execute with the incoming (x, y) coordinates.
+     */
     onCursor(callback: (x: number, y: number) => void): void;
+    /**
+     * Enables the biking module and listens for speed updates.
+     * @param callback Function to execute with the incoming speed data.
+     */
     onBiking(callback: (speed: number) => void): void;
+    /**
+     * Enables the vertical detector module and listens for orientation updates.
+     * @param callback Function to execute with the boolean vertical state.
+     */
     onVerticalDetector(callback: (vertical: boolean) => void): void;
+    /**
+     * Sends a request to the device to attach a specific event listener on the hardware side.
+     * @param event The event name to attach.
+     */
     private _attachEvent;
+    /**
+     * Sends a request to the device to enable a specific hardware module.
+     * @param moduleName The name of the module to enable (Note: retains original code spelling).
+     */
     private _enableModule;
+    /**
+     * Changes the current LED color of the device.
+     * @param color The RGB color configuration to apply.
+     */
     setColor(color: Color): void;
+    /**
+     * Sends a predefined sequence of colors to the device.
+     * @param sequence Array of color sequence identifiers or configurations.
+     * @param reset Whether to interrupt the current sequence before starting the new one.
+     */
     setColorSequence(sequence: string[], reset?: boolean): void;
     /**
-     * Vibrate the device (use the motor vibrator)
-     * @param time
-     * @param blink
-     * @param blinkOff
-     * @param blinkCount
+     * Triggers the device's vibration motor.
+     * @param time Total vibration time in milliseconds.
+     * @param blink Enables pulsating/intermittent vibration.
+     * @param blinkOff The duration of the pause between pulses in milliseconds.
+     * @param blinkCount The number of pulsing cycles to execute.
      */
     vibrate(time: number, blink?: boolean, blinkOff?: number, blinkCount?: number): void;
     /**
-     * Convert this device object to a json object
-     * @returns
+     * Serializes the Device object into a generic dictionary.
+     * @returns A plain object representing the device's current state.
      */
     toObject(): {
         [key: string]: any;
     };
     /**
-     * set the device object from a json object
-     * @param object
+     * Hydrates the Device instance using properties from a provided object.
+     * @param object The plain object containing device properties.
      */
     fromObject(object: {
         [key: string]: any;