@momo2555/koppeliajs 0.0.161 → 0.0.163

package/dist/scripts/koppeliaWebsocket.js

@@ -10,9 +10,9 @@ export class KoppeliaWebsocket {
     openCallback;
     /* ------ PUBLIC ------ */
     /**
-     * Constructor of the Koppelia websocket class
-     * @param websocketUrl
-     * @param timeout
+     * Initializes the Koppelia WebSocket client.
+     * @param websocketUrl The URL of the WebSocket server to connect to.
+     * @param timeout The maximum time in milliseconds to wait for a response before timing out a request. Defaults to 20000ms.
      */
     constructor(websocketUrl, timeout = DEFAULT_WS_TIMEOUT) {
         if (!import.meta.env.SSR) {
@@ -28,51 +28,51 @@ export class KoppeliaWebsocket {
         this.websocketUrl = websocketUrl;
     }
     /**
-     * Send a new request: Add a request Id to the request and add it to the ongoing requests
-     * Add an interval to timeout when there is no response after a certain amount of time
-     * @param data
-     * @param callback
+     * Sends a new message request through the WebSocket.
+     * Automatically generates a request ID, registers the request as ongoing, and sets a timeout.
+     * @param data The message payload to send.
+     * @param callback Optional callback to be executed when a response to this specific request is received.
      */
     send(data, callback) {
         if (this.socket === undefined) {
-            logger.log("KoppeliaWebsocket::send(): Koppelia websocket client was not instancieated");
+            logger.log("KoppeliaWebsocket::send(): Koppelia websocket client was not instantiated");
             return;
         }
-        // Create a request id
         data.generateRequestId();
         this._addNewRequest(data.getRequestId(), callback);
-        // Send the request
         const serializedMessage = JSON.stringify(data.toObject());
         logger.log("sending message", serializedMessage);
         this.socket.send(serializedMessage);
-        // set a timeout
         window.setTimeout(() => this._deleteRequest(data.getRequestId()), this.timeout);
         ;
     }
     /**
-     * Add a receive callback
-     * @param callback
+     * Registers a global callback to be triggered whenever a message is received.
+     * @param callback The function to execute upon receiving a message.
      */
     onReceive(callback) {
         this.receiveCallbacks.push(callback);
     }
     /**
-     * Define a callback for the websocket open event
-     * @param callback
+     * Registers a callback to be triggered when the WebSocket connection successfully opens.
+     * @param callback The function to execute upon connection.
      */
     onOpen(callback) {
         this.openCallback = callback;
     }
     /* ------ PRIVATE ------ */
+    /**
+     * Establishes the WebSocket connection.
+     * @param websockerUrl The URL of the WebSocket server.
+     */
     _connectWebsocket(websockerUrl) {
         this.socket = new WebSocket(websockerUrl);
     }
     /**
-     * Handle a websocket response
-     * - Execute a callback of a reception if a request was send before (by checking ongoing request)
-     * - Execute a callbacj for a genral reception response
-     * @param data
-     * @returns
+     * Handles incoming WebSocket responses.
+     * Checks if the message corresponds to an ongoing request. If so, triggers its specific callback.
+     * Otherwise, broadcasts the message to all global receive callbacks.
+     * @param data The raw data payload received from the WebSocket.
      */
     _handleWebsocketResponse(data) {
         if (data === undefined) {
@@ -81,13 +81,10 @@ export class KoppeliaWebsocket {
         let message = new Message();
         message.parse(data);
         if (message.getRequestId() !== undefined) {
-            // There is a request id, check if it's a response
             let onGoing = this._getOnGoingRequest(message.getRequestId());
             if (onGoing) {
-                // check if the callback exists
                 if (onGoing.callback)
                     onGoing.callback(message);
-                // otherwise do not execute callback and delete the request from ongoing
                 this._deleteRequest(message.getRequestId());
                 return;
             }
@@ -97,53 +94,52 @@ export class KoppeliaWebsocket {
         }
     }
     /**
-     * Init all websocker events
+     * Initializes all WebSocket event listeners (open, message, close).
+     * Handles automatic reconnection on connection close or error.
      */
     _setupEvents() {
         if (this.socket === undefined) {
-            logger.log("KoppeliaWebsocket::_setupEvents(): Koppelia websocket client was not instancieated");
+            logger.log("KoppeliaWebsocket::_setupEvents(): Koppelia websocket client was not instantiated");
             return;
         }
-        // handle web socker opening
         this.socket.addEventListener('open', (e) => {
             if (this.openCallback)
                 this.openCallback();
         });
-        // handle web socket reception
         this.socket.addEventListener('message', (e) => {
             let data = JSON.parse(e.data);
             this._handleWebsocketResponse(data);
         });
-        // handle connection close (if an error occure)
         this.socket.onclose = (event) => {
-            logger.log(`Connection closed ${event.reason}, code=${event.code}, retry onnection ...`);
+            logger.log(`Connection closed ${event.reason}, code=${event.code}, retry connection ...`);
             setTimeout(() => { this._connectWebsocket(this.websocketUrl); this._setupEvents(); }, 1000);
         };
     }
     /**
-     * Timeout the request if there is no response
-     * To timout the response, the function simply delete the id from on going request list
-     * @param requestId Id of the request
+     * Retrieves the index of an ongoing request in the internal list.
+     * @param requestId The unique identifier of the request.
+     * @returns The array index of the request, or -1 if not found.
      */
     _getRequestIndex(requestId) {
         return this.onGoingRequests.findIndex((element) => {
             if (!element) {
-                return false; // Skip empty slots
+                return false;
             }
             return element.requestId === requestId;
         });
     }
     /**
-     * Delete the request from the list of onGoing Requests
-     * @param requestId
+     * Removes a request from the ongoing requests list.
+     * Used both when a request is successfully resolved or when it times out.
+     * @param requestId The unique identifier of the request to remove.
      */
     _deleteRequest(requestId) {
         this.onGoingRequests = this.onGoingRequests.filter((element) => element.requestId !== requestId);
     }
     /**
-     * get the Ongoing the request and get theh callback
-     * @param requestId
-     * @returns
+     * Retrieves an ongoing request object by its ID.
+     * @param requestId The unique identifier of the request.
+     * @returns The ongoing request object, or undefined if not found.
      */
     _getOnGoingRequest(requestId) {
         let requestIndex = this._getRequestIndex(requestId);
@@ -152,9 +148,9 @@ export class KoppeliaWebsocket {
         return this.onGoingRequests[requestIndex];
     }
     /**
-     * Add a new request to ongoing requests
-     * @param requestId
-     * @param callback
+     * Registers a new request in the ongoing requests list.
+     * @param requestId The unique identifier generated for the request.
+     * @param callback Optional callback to trigger when the response arrives.
      */
     _addNewRequest(requestId, callback) {
         this.onGoingRequests.push({ requestId: requestId, callback: callback });

package/dist/scripts/message.d.ts

@@ -25,7 +25,7 @@ export declare enum MessageType {
     ERROR = "error",
     CLOSE = "close"
 }
-type MessagetHeader = {
+type MessageHeader = {
     id: string;
     type: string;
     from: string;
@@ -45,76 +45,93 @@ type DirectRequest = {
     };
 };
 /**
- * The koppelia protocol
+ * Defines the core Koppelia protocol message structure used for all network communications.
  */
 export declare class Message {
-    header: MessagetHeader;
+    header: MessageHeader;
     data: MessageData;
     request: DirectRequest;
     event: MessageEvent;
     constructor();
     /**
-     * Parse a json request received from the network
-     * @param data
+     * Parses a raw JSON request received from the network into the Message object.
+     * @param data The raw data object to parse.
      */
     parse(data: AnyRequest): void;
     /**
-     * Convert the request to json, to be sent on the network
-     * @returns
+     * Serializes the Message object into a plain JavaScript object for network transmission.
+     * @returns The serialized message object.
      */
     toObject(): AnyRequest;
     /**
-     * Set the source device, type and address (if there is address)
-     * @param type
-     * @param address
+     * Sets the routing source information for the message.
+     * @param type The peer type initiating the message.
+     * @param address The specific address of the source (defaults to empty string).
      */
     setSource(type: PeerType, address?: string): void;
     /**
-     * Set the destination device, type and address
-     * @param type
-     * @param address
+     * Sets the routing destination information for the message.
+     * @param type The intended peer type receiver.
+     * @param address The specific address of the destination (defaults to empty string).
      */
     setDestination(type: PeerType, address?: string): void;
     /**
-     * Get event name of the request, if it is an event
-     * @returns
+     * Retrieves the event name of the message.
+     * @returns The event string.
      */
     getEvent(): MessageEvent;
     /**
-     * Set the type of the request
-     * @param type
+     * Sets the primary type of the message.
+     * @param type The MessageType to assign.
      */
     setType(type: MessageType): void;
     /**
-     * Set an event to the request
-     * @param event
+     * Configures the message as an event request.
+     * @param event The name of the event.
      */
     setEvent(event: MessageEvent): void;
     /**
-     * Add a param if the request is request type
-     * @param key
-     * @param value
+     * Adds a parameter to the request payload.
+     * @param key The parameter key.
+     * @param value The parameter value.
      */
     addParam(key: string, value: any): void;
     /**
-     * Add data to the request
-     * @param key
-     * @param value
+     * Adds a key-value pair to the message data payload.
+     * @param key The data key.
+     * @param value The data value.
      */
     addData(key: string, value: any): void;
     /**
-     *
-     * @param data
+     * Overwrites the entire data payload of the message.
+     * @param data The new MessageData object.
      */
     setData(data: MessageData): void;
     /**
-     * Set a new request with a request name
-     * @param execName name of
+     * Configures the message as a direct request and sets its execution target name.
+     * @param execName The name of the action/command to execute.
      */
     setRequest(execName: string): void;
+    /**
+     * Retrieves a specific parameter from the request payload.
+     * @param paramName The key of the parameter to fetch.
+     * @param def The default value to return if the parameter is not found (defaults to null).
+     * @returns The parameter value, or the default value.
+     */
     getParam(paramName: string, def?: any): any;
+    /**
+     * Configures the message as an identification broadcast.
+     * @param peerToIdentify The peer type identifying itself.
+     */
     setIdentification(peerToIdentify: PeerType): void;
+    /**
+     * Generates and assigns a unique UUID for the message header.
+     */
     generateRequestId(): void;
+    /**
+     * Retrieves the unique identifier of the message.
+     * @returns The generated UUID string.
+     */
     getRequestId(): string;
 }
 export {};

package/dist/scripts/message.js

@@ -1,4 +1,4 @@
-import { v4 as uuidv4 } from 'uuid';
+import { v4 as uuidv4 } from "uuid";
 export var PeerType;
 (function (PeerType) {
     PeerType["MAESTRO"] = "maestro";
@@ -11,7 +11,6 @@ export var PeerType;
     PeerType["NONE"] = "none";
     PeerType["BROADCAST"] = "broadcast";
 })(PeerType || (PeerType = {}));
-;
 export var MessageType;
 (function (MessageType) {
     MessageType["EMPTY"] = "empty";
@@ -27,7 +26,7 @@ export var MessageType;
     MessageType["CLOSE"] = "close";
 })(MessageType || (MessageType = {}));
 /**
- * The koppelia protocol
+ * Defines the core Koppelia protocol message structure used for all network communications.
  */
 export class Message {
     header;
@@ -47,13 +46,13 @@ export class Message {
         this.data = {};
         this.request = {
             exec: "",
-            params: {}
+            params: {},
         };
         this.event = "";
     }
     /**
-     * Parse a json request received from the network
-     * @param data
+     * Parses a raw JSON request received from the network into the Message object.
+     * @param data The raw data object to parse.
      */
     parse(data) {
         if (data.header !== undefined) {
@@ -79,88 +78,94 @@ export class Message {
         }
     }
     /**
-     * Convert the request to json, to be sent on the network
-     * @returns
+     * Serializes the Message object into a plain JavaScript object for network transmission.
+     * @returns The serialized message object.
      */
     toObject() {
         return {
             header: this.header,
             request: this.request,
             data: this.data,
-            event: this.event
+            event: this.event,
         };
     }
     /**
-     * Set the source device, type and address (if there is address)
-     * @param type
-     * @param address
+     * Sets the routing source information for the message.
+     * @param type The peer type initiating the message.
+     * @param address The specific address of the source (defaults to empty string).
      */
     setSource(type, address = "") {
         this.header.from = type;
         this.header.from_addr = address;
     }
     /**
-     * Set the destination device, type and address
-     * @param type
-     * @param address
+     * Sets the routing destination information for the message.
+     * @param type The intended peer type receiver.
+     * @param address The specific address of the destination (defaults to empty string).
      */
     setDestination(type, address = "") {
         this.header.to = type;
         this.header.to_addr = address;
     }
     /**
-     * Get event name of the request, if it is an event
-     * @returns
+     * Retrieves the event name of the message.
+     * @returns The event string.
      */
     getEvent() {
         return this.event;
     }
     /**
-     * Set the type of the request
-     * @param type
+     * Sets the primary type of the message.
+     * @param type The MessageType to assign.
      */
     setType(type) {
         this.header.type = type;
     }
     /**
-     * Set an event to the request
-     * @param event
+     * Configures the message as an event request.
+     * @param event The name of the event.
      */
     setEvent(event) {
         this.header.type = MessageType.REQUEST;
         this.event = event;
     }
     /**
-     * Add a param if the request is request type
-     * @param key
-     * @param value
+     * Adds a parameter to the request payload.
+     * @param key The parameter key.
+     * @param value The parameter value.
      */
     addParam(key, value) {
         this.request.params[key] = value;
     }
     /**
-     * Add data to the request
-     * @param key
-     * @param value
+     * Adds a key-value pair to the message data payload.
+     * @param key The data key.
+     * @param value The data value.
      */
     addData(key, value) {
         this.data[key] = value;
     }
     /**
-     *
-     * @param data
+     * Overwrites the entire data payload of the message.
+     * @param data The new MessageData object.
      */
     setData(data) {
         this.data = data;
     }
     /**
-     * Set a new request with a request name
-     * @param execName name of
+     * Configures the message as a direct request and sets its execution target name.
+     * @param execName The name of the action/command to execute.
      */
     setRequest(execName) {
         this.header.type = MessageType.REQUEST;
         this.request.exec = execName;
     }
+    /**
+     * Retrieves a specific parameter from the request payload.
+     * @param paramName The key of the parameter to fetch.
+     * @param def The default value to return if the parameter is not found (defaults to null).
+     * @returns The parameter value, or the default value.
+     */
     getParam(paramName, def = null) {
         if (paramName in this.request.params) {
             return this.request.params[paramName];
@@ -169,13 +174,24 @@ export class Message {
             return def;
         }
     }
+    /**
+     * Configures the message as an identification broadcast.
+     * @param peerToIdentify The peer type identifying itself.
+     */
     setIdentification(peerToIdentify) {
         this.header.type = MessageType.IDENTIFICATION;
         this.header.from = peerToIdentify;
     }
+    /**
+     * Generates and assigns a unique UUID for the message header.
+     */
     generateRequestId() {
         this.header.id = uuidv4();
     }
+    /**
+     * Retrieves the unique identifier of the message.
+     * @returns The generated UUID string.
+     */
     getRequestId() {
         return this.header.id;
     }

package/dist/scripts/option.d.ts

@@ -3,38 +3,53 @@ export type Options = {
     [key: string]: any;
 };
 export type OptionChangedCallback = (value: any) => void;
+/**
+ * Manages game configuration options, allowing retrieval from the server and local modifications.
+ */
 export declare class Option {
     private _options;
     private _console;
     private _callbacks;
+    /**
+     * Initializes the game options manager.
+     * @param console The Console instance used for network communication.
+     */
     constructor(console: Console);
+    /**
+     * Retrieves the current dictionary of options.
+     */
     get options(): Options;
     /**
-     * Update the game options from the server
+     * Fetches all current game options from the server and populates the local cache.
+     * @returns A promise that resolves when the options have been successfully received and processed.
      */
     updateFromServer(): Promise<void>;
     /**
-     * Set a new or edit a game option
-     * @param name Name fo the option
-     * @param value Value of the option
+     * Requests the master peer to create or update a game option.
+     * @param name The unique identifier of the option.
+     * @param value The value to assign to the option.
+     * @param type Optional type definition for the option (e.g., string, number).
+     * @param config Optional additional configuration metadata for the option.
      */
     setOption(name: string, value: any, type?: string | null, config?: {
         [key: string]: any;
     }): void;
     /**
-     * Set a callback when an option has changed
-     * @param name
-     * @param callback
+     * Registers a callback to be executed whenever a specific option is updated.
+     * @param name The name of the option to observe.
+     * @param callback The function to trigger upon modification.
      */
     onOptionChanged(name: string, callback: OptionChangedCallback): void;
     /**
-     * Init all events
-     * @param from
-     * @param any
+     * Initializes core events: fetching options on readiness and listening for option change notifications.
      */
     private _initEvents;
     /**
-     * callback when a new option is received
+     * Internal handler to process incoming options from the server and trigger associated callbacks.
+     * @param from The origin peer sending the option.
+     * @param receivedOption The name/key of the option received.
+     * @param valueOption The payload containing the option's new value.
+     * @param runCallbacks If true, executes any registered callbacks for this option.
      */
     private _onReceiveState;
 }

package/dist/scripts/option.js

@@ -1,21 +1,32 @@
 import { Console } from "./console.js";
 import { Message, PeerType } from "./message.js";
 import { get, writable } from "svelte/store";
+/**
+ * Manages game configuration options, allowing retrieval from the server and local modifications.
+ */
 export class Option {
     _options;
     _console;
     _callbacks;
+    /**
+     * Initializes the game options manager.
+     * @param console The Console instance used for network communication.
+     */
     constructor(console) {
         this._options = {};
         this._console = console;
         this._callbacks = {};
         this._initEvents();
     }
+    /**
+     * Retrieves the current dictionary of options.
+     */
     get options() {
         return this._options;
     }
     /**
-     * Update the game options from the server
+     * Fetches all current game options from the server and populates the local cache.
+     * @returns A promise that resolves when the options have been successfully received and processed.
      */
     async updateFromServer() {
         return new Promise((resolve, reject) => {
@@ -31,9 +42,11 @@ export class Option {
         });
     }
     /**
-     * Set a new or edit a game option
-     * @param name Name fo the option
-     * @param value Value of the option
+     * Requests the master peer to create or update a game option.
+     * @param name The unique identifier of the option.
+     * @param value The value to assign to the option.
+     * @param type Optional type definition for the option (e.g., string, number).
+     * @param config Optional additional configuration metadata for the option.
      */
     setOption(name, value, type = null, config = {}) {
         let setOptionRequest = new Message();
@@ -44,27 +57,22 @@ export class Option {
         setOptionRequest.addParam("type", type);
         setOptionRequest.addParam("config", config);
         this._console.sendMessage(setOptionRequest);
-        // this._options[name] = value;
     }
     /**
-     * Set a callback when an option has changed
-     * @param name
-     * @param callback
+     * Registers a callback to be executed whenever a specific option is updated.
+     * @param name The name of the option to observe.
+     * @param callback The function to trigger upon modification.
      */
     onOptionChanged(name, callback) {
         this._callbacks[name] = callback;
     }
     /**
-     * Init all events
-     * @param from
-     * @param any
+     * Initializes core events: fetching options on readiness and listening for option change notifications.
      */
     _initEvents() {
-        // Get the state when the console is ready
         this._console.onReady(() => {
             this.updateFromServer();
         });
-        // update the state when receive a change from console
         this._console.onRequest((request, params, from) => {
             if (request == "gameOptionNotification") {
                 let value = {};
@@ -80,7 +88,11 @@ export class Option {
         });
     }
     /**
-     * callback when a new option is received
+     * Internal handler to process incoming options from the server and trigger associated callbacks.
+     * @param from The origin peer sending the option.
+     * @param receivedOption The name/key of the option received.
+     * @param valueOption The payload containing the option's new value.
+     * @param runCallbacks If true, executes any registered callbacks for this option.
      */
     _onReceiveState(from, receivedOption, valueOption, runCallbacks = false) {
         this._options[receivedOption] = valueOption["value"];