@momo2555/koppeliajs 0.0.162 → 0.0.164

package/dist/scripts/koppelia.js

@@ -12,6 +12,11 @@ import { Option } from "./option.js";
 import { logger, setDebugMode } from "./logger.js";
 import { CustomCallbacks } from "./customCallback.js";
 import { Song } from "./song.js";
+/**
+ * The main Koppelia framework entry point.
+ * Implements a Singleton pattern to provide global access to the console, state, stages,
+ * devices, and game synchronization features across the Svelte application.
+ */
 export class Koppelia {
     _console;
     _state;
@@ -40,81 +45,111 @@ export class Koppelia {
         this._stage = new Stage(this._console);
         this._option = new Option(this._console);
     }
+    /**
+     * Retrieves the singleton instance of the Koppelia class.
+     * Instantiates it if it does not yet exist.
+     */
     static get instance() {
         if (!Koppelia._instance) {
             Koppelia._instance = new Koppelia();
         }
         return Koppelia._instance;
     }
+    /**
+     * Retrieves the global Svelte writable store representing the synchronized game state.
+     */
     get state() {
         return this._state.state;
     }
+    /**
+     * Merges a partial update into the current global state and broadcasts the change.
+     * @param stateUpdate A dictionary containing the keys/values to update.
+     */
     updateState(stateUpdate) {
         this._state.updateState(stateUpdate);
     }
+    /**
+     * Completely overwrites the global state with a new state object.
+     * @param newState The new state object to apply.
+     */
     setState(newState) {
         this._state.setState(newState);
     }
+    /**
+     * Checks if the underlying WebSocket console connection is fully established.
+     */
     get ready() {
         return this._console.ready;
     }
+    /**
+     * Enables or disables debug mode for extended console logging.
+     * @param enable True to enable debug logs, false to disable.
+     */
     setDebugMode(enable) {
         setDebugMode(enable);
     }
     /**
-     * Add a callback that will be called when the connection to the console is entirely ready
-     *
-     * @param callback
+     * Registers a callback to execute when the console connection is fully ready.
+     * @param callback The function to execute.
      */
     onReady(callback) {
         this._console.onReady(callback);
     }
     /**
-     * Init the default state of the game and the list of all stages
-     *
-     * @param defaultState Default state that be initialized
-     * @param stages List of all stages
+     * Initializes the default state and the routing stages of the game.
+     * Specifically executes for "monitor" peers to ensure the primary game view sets the rules.
+     * @param defaultState The initial state structure.
+     * @param stages An array of valid stage names for application routing.
      */
     init(defaultState, stages) {
         this._console.onReady(() => {
             let type = get(routeType);
             if (type == "monitor") {
-                this._state.setState(defaultState, true); // set the state
-                this._stage.initStages(stages); // init the list of stages
+                this._state.setState(defaultState, true);
+                this._stage.initStages(stages);
             }
         });
     }
     /**
-     * Go to a stage, the stage must be in the stage list
-     * Before changing the staging all callbacks will be destroyed
-     * If the stage list is empty the console will return an error
-     * @param stageName
+     * Requests a transition to a specific stage (view) across the network.
+     * Note: All active console event listeners will be destroyed before transition.
+     * @param stageName The target stage to navigate to.
      */
     goto(stageName) {
         this._stage.goto(stageName);
     }
+    getCurrentStage() {
+        return this._stage.currentStage;
+    }
+    /**
+     * Normalizes a media URL to ensure cross-client compatibility.
+     * @param mediaUrl The raw media URL.
+     * @returns The corrected URL.
+     */
     fixMediaUrl(mediaUrl) {
         return this._console.fixMediaUrl(mediaUrl);
     }
+    /**
+     * Constructs the full URL for a given relative media path.
+     * @param path The relative media path.
+     * @returns The full URL string.
+     */
     getMediaLink(path) {
         return this._console.getMediaUrl(path);
     }
     /**
-     * Get the list of devices in a callback
-     * @param callback
+     * Asynchronously fetches the list of available connected devices from the master peer.
+     * @returns A promise resolving to an array of instantiated Device objects.
      */
     async getDevices() {
         return new Promise((resolve, reject) => {
-            // create the message to request the devices
             let getDevicesRequest = new Message();
             getDevicesRequest.setRequest("getDevices");
             getDevicesRequest.setDestination(PeerType.MASTER, "");
-            // send the message to the console
             this._console.sendMessage(getDevicesRequest, (response) => {
-                // convert the response to al list of device objects
-                let devices_raw = response.getParam("devices", []);
+                let devicesRaw = response.getParam("devices", []);
                 let devices = [];
-                for (let device_raw of devices_raw) {
+                for (let device_raw of devicesRaw) {
                     let device = new Device(this._console);
                     device.fromObject(device_raw);
                     devices.push(device);
@@ -123,20 +158,40 @@ export class Koppelia {
             });
         });
     }
+    _onDeviceConnNotification(callback, notifName) {
+        return this._console.onRequest((request, params, from, address) => {
+            if (request == notifName) {
+                if (params.device !== undefined) {
+                    let device = new Device(this._console);
+                    device.fromObject(params.device);
+                    callback(device);
+                }
+            }
+        });
+    }
+    onDeviceConnectedNotification(callback) {
+        return this._onDeviceConnNotification(callback, "deviceConnectionNotification");
+    }
+    onDeviceDisconnectedNotification(callback) {
+        return this._onDeviceConnNotification(callback, "deviceDisconnectionNotification");
+    }
+    unsubDeviceConnectionNotification(callbackId) {
+        this._console.unsubscribeCallback(callbackId);
+    }
     /**
-     * Get the game ID of the current game
-     * @returns the game id as a string
+     * Retrieves the unique identifier of the currently loaded game.
+     * @returns The game ID string provided by public environment variables.
      */
     getGameId() {
         return PUBLIC_GAME_ID;
     }
     /**
-     * Get the list of plays, the plays returned by this function doesn't include the raw
-     * You have to call a function in from the play object to download all the raw files
-     * @param count limit of plays to get
-     * @param index index from which to start fetching the plays
-     * @param orderBy order by date or name
-     * @returns the List of plays an array of objects of type Play,
+     * Asynchronously fetches a paginated list of Play sessions.
+     * Note: This only fetches metadata. Specific Play content must be downloaded via Play methods.
+     * @param count Maximum number of plays to retrieve (default: 10).
+     * @param index The starting offset index (default: 0).
+     * @param orderBy Sorting criteria, e.g., "date" or "name" (default: "date").
+     * @returns A promise resolving to an array of Play instances.
      */
     async getPlays(count = 10, index = 0, orderBy = "date") {
         return new Promise((resolve, reject) => {
@@ -157,6 +212,10 @@ export class Koppelia {
             });
         });
     }
+    /**
+     * Asynchronously fetches the list of registered residents/players.
+     * @returns A promise resolving to an array of Resident instances.
+     */
     async getResidents() {
         return new Promise((resolve, reject) => {
             let getResidentsRequest = new Message();
@@ -175,6 +234,11 @@ export class Koppelia {
             });
         });
     }
+    /**
+     * Asynchronously fetches a specific song by its unique ID.
+     * @param songId The ID of the song to retrieve.
+     * @returns A promise resolving to the corresponding Song instance.
+     */
     async getSongById(songId) {
         return new Promise((resolve, reject) => {
             let getSongRequest = new Message();
@@ -190,6 +254,10 @@ export class Koppelia {
             });
         });
     }
+    /**
+     * Asynchronously fetches a dictionary of all songs associated with the currently active play.
+     * @returns A promise resolving to a map of song IDs to Song instances.
+     */
     getCurrentPlaySongs() {
         return new Promise((resolve, reject) => {
             let getSongRequest = new Message();
@@ -209,8 +277,8 @@ export class Koppelia {
         });
     }
     /**
-     * Get the current play that has been set
-     * @returns the current play
+     * Asynchronously retrieves the currently active Play instance set on the server.
+     * @returns A promise resolving to the active Play.
      */
     async getCurrentPlay() {
         return new Promise((resolve, reject) => {
@@ -226,24 +294,23 @@ export class Koppelia {
         });
     }
     /**
-     * This function enables the difficulty cursor, to change the difficulty live when playing from Koppeli'App
-     * @param callback : callback to call when difficulty changes
+     * Enables a live difficulty cursor, allowing difficulty changes during gameplay.
+     * @param callback Function to execute when the difficulty changes.
      */
     async enableDifficultyCursor(callback) {
     }
     /**
-     * @param id
-     * @param onGrowChange
+     * Registers a new growable element on the network and listens for state changes.
+     * @param id The unique identifier for the growable element.
+     * @param onGrowChange Callback triggered when the 'grown' state of the element changes.
      */
     async registerNewGrowableElement(id, onGrowChange) {
         return new Promise((resolve, reject) => {
-            // create the message to request the devices
             if (get(routeType) == "controller") {
                 let addGrowableElRequest = new Message();
                 addGrowableElRequest.setRequest("addGrowableElement");
                 addGrowableElRequest.addParam("id", id);
                 addGrowableElRequest.setDestination(PeerType.MASTER, "");
-                // send the message to the console (only the controller sends the )
                 this._console.sendMessage(addGrowableElRequest, (response) => {
                 });
             }
@@ -261,26 +328,26 @@ export class Koppelia {
         });
     }
     /**
-     * @param id
-     * @param grown
+     * Updates the 'grown' state of a registered growable element across the network.
+     * @param id The unique identifier of the element.
+     * @param grown True if the element is in a grown state, false otherwise.
      */
     async updateGrowableElement(id, grown) {
         return new Promise((resolve, reject) => {
-            // create the message to request the devices
             let addGrowableElRequest = new Message();
             addGrowableElRequest.setRequest("updateGrowableElement");
             addGrowableElRequest.addParam("id", id);
             addGrowableElRequest.addParam("grown", grown);
             addGrowableElRequest.setDestination(PeerType.MASTER, "");
-            // send the message to the console
             this._console.sendMessage(addGrowableElRequest, (response) => {
                 resolve();
             });
         });
     }
     /**
-     * Add a new resizable text element and define the callback that will be executed when receive and a resizable
-     * text update notification form koppelia application
+     * Registers a new resizable text element with a default font size (Monitor only).
+     * @param id The unique identifier for the text element.
+     * @param defaultSize The default font size.
      */
     async registerNewResizableText(id, defaultSize) {
         return new Promise((resolve, reject) => {
@@ -290,13 +357,18 @@ export class Koppelia {
                 addGrowableElRequest.addParam("id", id);
                 addGrowableElRequest.addParam("defaultSize", defaultSize);
                 addGrowableElRequest.setDestination(PeerType.MASTER, "");
-                // send the message to the console (only the controller sends the )
                 this._console.sendMessage(addGrowableElRequest, (response) => {
                 });
             }
             resolve();
         });
     }
+    /**
+     * Subscribes to size change notifications for a specific resizable text element.
+     * @param id The unique identifier of the text element.
+     * @param onTextResized Callback executed with the new font size.
+     * @returns The unique subscription ID used for unsubscribing.
+     */
     onResizableTextChanged(id, onTextResized) {
         return this._console.onRequest((req, params) => {
             if (req == "resizableTextNotification") {
@@ -308,21 +380,34 @@ export class Koppelia {
             }
         });
     }
+    /**
+     * Unsubscribes a previously registered resizable text listener.
+     * @param callbackId The subscription ID returned by onResizableTextChanged.
+     */
     unsubResizableText(callbackId) {
         this._console.unsubscribeCallback(callbackId);
     }
+    /**
+     * Retrieves the list of all registered resizable text elements from the master.
+     * @returns A promise resolving to an array of resizable element data objects.
+     */
     async getResizableTexts() {
         return new Promise((resolve, reject) => {
             let addGrowableElRequest = new Message();
             addGrowableElRequest.setRequest("getResizableTexts");
             addGrowableElRequest.setDestination(PeerType.MASTER, "");
-            // send the message to the console (only the controller sends the )
             this._console.sendMessage(addGrowableElRequest, (response) => {
                 let resizables = response.getParam("resizableTexts", []);
                 resolve(resizables);
             });
         });
     }
+    /**
+     * Writes configuration data to the master peer, optionally binding it to the current play.
+     * @param config_id The unique identifier for this configuration data.
+     * @param config_value The dictionary containing the configuration payload.
+     * @param current_play Whether to bind this configuration to the active play session (default: true).
+     */
     async writeGameConfig(config_id, config_value, current_play = true) {
         let setGameConfigRequest = new Message();
         setGameConfigRequest.setRequest("setGameData");
@@ -332,6 +417,12 @@ export class Koppelia {
         setGameConfigRequest.setDestination(PeerType.MASTER, "");
         this._console.sendMessage(setGameConfigRequest);
     }
+    /**
+     * Retrieves persistent configuration data from the master peer.
+     * @param config_id The unique identifier of the configuration data to fetch.
+     * @param current_play True to fetch data bound specifically to the active play, false otherwise.
+     * @returns A promise resolving to the configuration dictionary.
+     */
     async getGameConfig(config_id, current_play) {
         return new Promise((resolve, reject) => {
             let getGameConfigRequest = new Message();
@@ -346,25 +437,33 @@ export class Koppelia {
         });
     }
     /**
-     * @param sentence
+     * Broadcasts a Text-to-Speech synthesis request to the Maestro peer.
+     * @param sentence The text string to be spoken out loud.
      */
     say(sentence) {
-        // create the message to request the devices
         let sayRequest = new Message();
         sayRequest.setRequest("sayRequest");
         sayRequest.addParam("sentence", sentence);
         sayRequest.setDestination(PeerType.MAESTRO, "");
-        // send the message to the console
         this._console.sendMessage(sayRequest);
     }
     /**
-     * Set a new or edit a game option
-     * @param name Name fo the option
-     * @param value Value of the option
+     * Assigns a basic value to a registered game option via the option manager.
+     * @param name The unique name of the option.
+     * @param value The value to set.
      */
     setOption(name, value) {
         this._option.setOption(name, value, null, {});
     }
+    /**
+     * Creates or updates an interactive slider option.
+     * @param name The unique identifier for the slider.
+     * @param label The display label for the UI.
+     * @param value The current numeric value.
+     * @param min The minimum allowed value.
+     * @param max The maximum allowed value.
+     * @param step The increment step size.
+     */
     createSliderOtption(name, label, value, min, max, step) {
         this._option.setOption(name, value, "slider", {
             "min": min,
@@ -373,26 +472,58 @@ export class Koppelia {
             "label": label,
         });
     }
+    /**
+     * Creates or updates an interactive toggle switch option.
+     * @param name The unique identifier for the switch.
+     * @param label The display label for the UI.
+     * @param value The current boolean state.
+     */
     createSwitchOption(name, label, value) {
         this._option.setOption(name, value, "switch", {
             "label": label,
         });
     }
+    /**
+     * Creates or updates a multiple-choice selection option.
+     * @param name The unique identifier for the option.
+     * @param label The display label for the UI.
+     * @param value The currently selected choice.
+     * @param choices An array of available string choices.
+     */
     createChoicesOption(name, label, value, choices) {
         this._option.setOption(name, value, "choices", {
             "choices": choices,
             "label": label,
         });
     }
+    /**
+     * Registers a callback listener to trigger whenever a specific option's value changes.
+     * @param name The name of the option to observe.
+     * @param callback The function to execute on change.
+     */
     onOptionChanged(name, callback) {
         this._option.onOptionChanged(name, callback);
     }
+    /**
+     * Executes a broadcasted network request to trigger a registered custom callback.
+     * @param callbackName The unique registered name of the custom callback.
+     * @param args Dictionary of arguments to pass to the callback.
+     */
     run(callbackName, args) {
         this._callbacks.runCustomCallback(callbackName, args);
     }
+    /**
+     * Registers a local function to listen for network execution of a custom callback.
+     * @param callbackName The identifier for this callback.
+     * @param callback The local function to execute.
+     */
     on(callbackName, callback) {
         this._callbacks.registerCustomCallback(callbackName, callback);
     }
+    /**
+     * Unregisters a locally listening custom callback.
+     * @param callbackName The identifier of the callback to remove.
+     */
     unsub(callbackName) {
         this._callbacks.unregisterCustomCallback(callbackName);
     }

package/dist/scripts/koppeliaWebsocket.d.ts

@@ -12,62 +12,67 @@ export declare class KoppeliaWebsocket {
     websocketUrl: string;
     openCallback?: () => void;
     /**
-     * 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: string, timeout?: number);
     /**
-     * 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: Message, callback?: Callback): void;
     /**
-     * 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: Callback): void;
     /**
-     * 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: () => void): void;
+    /**
+     * Establishes the WebSocket connection.
+     * @param websockerUrl The URL of the WebSocket server.
+     */
     private _connectWebsocket;
     /**
-     * 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.
      */
     private _handleWebsocketResponse;
     /**
-     * Init all websocker events
+     * Initializes all WebSocket event listeners (open, message, close).
+     * Handles automatic reconnection on connection close or error.
      */
     private _setupEvents;
     /**
-     * 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.
      */
     private _getRequestIndex;
     /**
-     * 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.
      */
     private _deleteRequest;
     /**
-     * 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.
      */
     private _getOnGoingRequest;
     /**
-     * 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.
      */
     private _addNewRequest;
 }