@momo2555/koppeliajs 0.0.162 → 0.0.164

package/dist/scripts/device.js

@@ -1,6 +1,10 @@
 import { Console } from "./console.js";
 import { Message, MessageType, PeerType } from "./message.js";
 import { Resident } from "./resident.js";
+/**
+ * Represents a physical or logical device connected to the console.
+ * Handles device-specific commands like LEDs, vibrations, and hardware module subscriptions.
+ */
 export class Device {
     _address;
     _color;
@@ -8,6 +12,8 @@ export class Device {
     _console;
     _attachedEvents;
     _resident;
+    _callbackIds;
+    _eventsIds;
     isAttachedToResident;
     constructor(console, address = "") {
         this._address = address;
@@ -15,22 +21,21 @@ export class Device {
         this._name = "";
         this._console = console;
         this._attachedEvents = [];
+        this._callbackIds = [];
+        this._eventsIds = [];
         this.isAttachedToResident = false;
     }
-    // public set color(color: Color) {
-    //     this._color = color;
-    //     // TODO : send a request to change the color
-    // }
     get color() {
         return this._color;
     }
-    // public set name(name: string) {
-    //     this._name = name;
-    //     // TODO : send a request to change the name
-    // }
     get name() {
         return this._name;
     }
+    /**
+     * 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, callback) {
         this._attachEvent(eventName);
         let consoleEvent = (device, from_addr, event) => {
@@ -38,35 +43,57 @@ export class Device {
                 callback();
             }
         };
-        this._console.onDeviceEvent(consoleEvent);
+        return this._console.onDeviceEvent(consoleEvent);
     }
+    /**
+     * Enables the cursor module and listens for coordinate updates.
+     * @param callback Function to execute with the incoming (x, y) coordinates.
+     */
     onCursor(callback) {
         this._enableModule("cursor");
         this._attachEvent("cursor");
-        this._console.onRequest((request, params, form, address) => {
+        let callbackId = this._console.onRequest((request, params, form, address) => {
             if (request == "cursor" && address == this._address) {
                 callback(params.x, params.y);
             }
         });
+        this._callbackIds.push(callbackId);
+        return callbackId;
     }
+    /**
+     * Enables the biking module and listens for speed updates.
+     * @param callback Function to execute with the incoming speed data.
+     */
     onBiking(callback) {
         this._enableModule("biking");
         this._attachEvent("biking");
-        this._console.onRequest((request, params, form, address) => {
+        let callbackId = this._console.onRequest((request, params, form, address) => {
             if (request == "biking" && address == this._address) {
                 callback(params.speed);
             }
         });
+        this._callbackIds.push(callbackId);
+        return callbackId;
     }
+    /**
+     * Enables the vertical detector module and listens for orientation updates.
+     * @param callback Function to execute with the boolean vertical state.
+     */
     onVerticalDetector(callback) {
         this._enableModule("vDetct");
         this._attachEvent("verticalDetector");
-        this._console.onRequest((request, params, form, address) => {
+        let callbackId = this._console.onRequest((request, params, form, address) => {
             if (request == "verticalDetector" && address == this._address) {
                 callback(params.value);
             }
         });
+        this._callbackIds.push(callbackId);
+        return callbackId;
     }
+    /**
+     * Sends a request to the device to attach a specific event listener on the hardware side.
+     * @param event The event name to attach.
+     */
     _attachEvent(event) {
         if (!(event in this._attachedEvents)) {
             let request = new Message();
@@ -77,13 +104,21 @@ export class Device {
             this._attachedEvents.push(event);
         }
     }
-    _enableModule(moduleNmae) {
+    /**
+     * 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).
+     */
+    _enableModule(moduleName) {
         let request = new Message();
-        request.addParam("module", moduleNmae);
+        request.addParam("module", moduleName);
         request.setDestination(PeerType.DEVICE, this._address);
         request.setRequest("enableModule");
         this._console.sendMessage(request);
     }
+    /**
+     * Changes the current LED color of the device.
+     * @param color The RGB color configuration to apply.
+     */
     setColor(color) {
         this._color = color;
         let request = new Message();
@@ -92,6 +127,11 @@ export class Device {
         request.setRequest("setColor");
         this._console.sendMessage(request);
     }
+    /**
+     * 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, reset = false) {
         let request = new Message();
         request.setDestination(PeerType.DEVICE, this._address);
@@ -101,11 +141,11 @@ export class Device {
         this._console.sendMessage(request);
     }
     /**
-     * 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, blink = false, blinkOff = 0, blinkCount = 0) {
         let vibration = {
@@ -123,9 +163,29 @@ export class Device {
         request.setRequest("vibrate");
         this._console.sendMessage(request);
     }
+    clearCallback(callbackId) {
+        if (this._callbackIds.includes(callbackId)) {
+            this._console.unsubscribeCallback(callbackId);
+        }
+    }
+    clearAllCallbacks() {
+        for (let callbackId of this._callbackIds) {
+            this.clearCallback(callbackId);
+        }
+    }
+    clearEvent(eventId) {
+        if (this._eventsIds.includes(eventId)) {
+            this._console.unsubscribeCallback(eventId);
+        }
+    }
+    clearAllEvents() {
+        for (let eventId of this._eventsIds) {
+            this.clearCallback(eventId);
+        }
+    }
     /**
-     * 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() {
         return {
@@ -135,8 +195,8 @@ export class Device {
         };
     }
     /**
-     * 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) {
         if (object.address !== undefined) {

package/dist/scripts/koppelia.d.ts

@@ -5,6 +5,11 @@ import { Play } from "./play.js";
 import { Resident } from "./resident.js";
 import { type OptionChangedCallback } from "./option.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 declare class Koppelia {
     private _console;
     private _state;
@@ -12,114 +17,233 @@ export declare class Koppelia {
     private static _instance;
     private _option;
     private _callbacks;
-    constructor();
+    private constructor();
+    /**
+     * Retrieves the singleton instance of the Koppelia class.
+     * Instantiates it if it does not yet exist.
+     */
     static get instance(): Koppelia;
+    /**
+     * Retrieves the global Svelte writable store representing the synchronized game state.
+     */
     get state(): Writable<AnyState>;
+    /**
+     * 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: AnyState): void;
+    /**
+     * Completely overwrites the global state with a new state object.
+     * @param newState The new state object to apply.
+     */
     setState(newState: AnyState): void;
+    /**
+     * Checks if the underlying WebSocket console connection is fully established.
+     */
     get ready(): boolean;
+    /**
+     * Enables or disables debug mode for extended console logging.
+     * @param enable True to enable debug logs, false to disable.
+     */
     setDebugMode(enable: boolean): void;
     /**
-     * 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: () => void): void;
     /**
-     * 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: AnyState, stages: string[]): void;
     /**
-     * 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: string): void;
+    getCurrentStage(): string;
+    /**
+     * Normalizes a media URL to ensure cross-client compatibility.
+     * @param mediaUrl The raw media URL.
+     * @returns The corrected URL.
+     */
     fixMediaUrl(mediaUrl: string): string;
+    /**
+     * Constructs the full URL for a given relative media path.
+     * @param path The relative media path.
+     * @returns The full URL string.
+     */
     getMediaLink(path: string): string;
     /**
-     * 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.
      */
     getDevices(): Promise<Device[]>;
+    private _onDeviceConnNotification;
+    onDeviceConnectedNotification(callback: (device: Device) => void): string;
+    onDeviceDisconnectedNotification(callback: (device: Device) => void): string;
+    unsubDeviceConnectionNotification(callbackId: string): void;
     /**
-     * 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(): string;
     /**
-     * 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.
      */
     getPlays(count?: number, index?: number, orderBy?: string): Promise<Play[]>;
+    /**
+     * Asynchronously fetches the list of registered residents/players.
+     * @returns A promise resolving to an array of Resident instances.
+     */
     getResidents(): Promise<Resident[]>;
+    /**
+     * 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.
+     */
     getSongById(songId: string): Promise<Song>;
+    /**
+     * 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(): Promise<{
         [key: string]: Song;
     }>;
     /**
-     * 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.
      */
     getCurrentPlay(): Promise<Play>;
     /**
-     * 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.
      */
     enableDifficultyCursor(callback: (difficulty: number) => void): Promise<void>;
     /**
-     * @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.
      */
     registerNewGrowableElement(id: string, onGrowChange: (grown: boolean) => void): Promise<void>;
     /**
-     * @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.
      */
     updateGrowableElement(id: string, grown: boolean): Promise<void>;
     /**
-     * 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.
      */
     registerNewResizableText(id: string, defaultSize: number): Promise<void>;
+    /**
+     * 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: string, onTextResized: (newSize: number) => void): string;
+    /**
+     * Unsubscribes a previously registered resizable text listener.
+     * @param callbackId The subscription ID returned by onResizableTextChanged.
+     */
     unsubResizableText(callbackId: string): void;
+    /**
+     * Retrieves the list of all registered resizable text elements from the master.
+     * @returns A promise resolving to an array of resizable element data objects.
+     */
     getResizableTexts(): Promise<{
         [key: string]: any;
     }[]>;
+    /**
+     * 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).
+     */
     writeGameConfig(config_id: string, config_value: {
         [key: string]: any;
     }, current_play?: boolean): Promise<void>;
+    /**
+     * 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.
+     */
     getGameConfig(config_id: string, current_play: boolean): Promise<{
         [key: string]: any;
     }>;
     /**
-     * @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: string): void;
     /**
-     * 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: string, value: any): void;
+    /**
+     * 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: string, label: string, value: number, min: number, max: number, step: number): void;
+    /**
+     * 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: string, label: string, value: boolean): void;
+    /**
+     * 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: string, label: string, value: string, choices: string[]): void;
+    /**
+     * 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: string, callback: OptionChangedCallback): void;
+    /**
+     * 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: string, args: {
         [key: string]: any;
     }): void;
+    /**
+     * 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: string, callback: (args: {
         [key: string]: any;
     }) => void): void;
+    /**
+     * Unregisters a locally listening custom callback.
+     * @param callbackName The identifier of the callback to remove.
+     */
     unsub(callbackName: string): void;
 }