@momo2555/koppeliajs 0.0.162 → 0.0.164

package/dist/scripts/play.d.ts

@@ -1,5 +1,9 @@
 import { Console } from "./console.js";
 import type { MediaResponseData } from "./console.js";
+/**
+ * Represents a "Play" (a specific game session or scenario instance).
+ * Manages the play's metadata, thumbnail, and the dynamic loading of its core content from the network.
+ */
 export declare class Play {
     private _playCreationDate;
     private _playCreatorId;
@@ -14,35 +18,73 @@ export declare class Play {
     private _refreshed;
     private _playContent;
     private _playContentLoaded;
+    /**
+     * Initializes a new Play instance.
+     * @param console The Console instance used for network and media requests.
+     * @param playId The unique identifier for this play.
+     * @param playRawObj A raw dictionary containing the play's basic metadata.
+     */
     constructor(console: Console, playId: string, playRawObj: {
         [key: string]: any;
     });
+    /**
+     * Constructs the relative path for a media file associated with this play.
+     * @param mediaName The name of the media file.
+     * @returns The relative media path string.
+     */
     getPlayMediaPath(mediaName: string): string;
+    /**
+     * Generates the fully qualified URL to access a specific play media file.
+     * @param mediaName The name of the media file.
+     * @returns The full URL string.
+     */
     getMediaLink(mediaName: string): string;
+    /**
+     * Asynchronously fetches the raw binary or parsed content of a specific media file.
+     * @param mediaName The name of the media file to fetch.
+     * @returns A promise resolving to the parsed media data (Blob, JSON, Text, etc.).
+     */
     getMediaContent(mediaName: string): Promise<MediaResponseData>;
+    /**
+     * Asynchronously fetches the core data payload of the play using its registered file name.
+     * @returns A promise resolving to the play's main data object.
+     */
     getMediaData(): Promise<{
         [key: string]: any;
     }>;
+    /**
+     * Downloads and caches the main content of the play into memory, marking it as loaded.
+     */
     updatePlayContent(): Promise<void>;
+    /**
+     * Gets the loaded content dictionary of the play.
+     */
     get playContent(): {
         [key: string]: any;
     };
+    /**
+     * Checks if the play's main content has been fully loaded into memory.
+     * @returns True if the content is loaded, false otherwise.
+     */
     isPlayContentLoaded(): boolean;
     /**
-     * Get the data of the play
+     * Retrieves the file name serving as the main data entry point for the play.
      */
     get data(): string;
     /**
-     * Get the id of the play
+     * Retrieves the unique identifier of the play.
      */
     get id(): string;
     /**
-     * Get the name of the play
+     * Retrieves the name of the play.
      */
     get name(): string;
     /**
-     * Get the image base64
+     * Retrieves the Base64 encoded thumbnail image of the play.
      */
     get image(): string;
+    /**
+     * Checks if the play data is currently in a refreshed state.
+     */
     get isRefreshed(): boolean;
 }

package/dist/scripts/play.js

@@ -1,5 +1,9 @@
 import { Console } from "./console.js";
 import { Message, PeerType } from "./message.js";
+/**
+ * Represents a "Play" (a specific game session or scenario instance).
+ * Manages the play's metadata, thumbnail, and the dynamic loading of its core content from the network.
+ */
 export class Play {
     _playCreationDate = "";
     _playCreatorId = "";
@@ -14,6 +18,12 @@ export class Play {
     _refreshed = true;
     _playContent = {};
     _playContentLoaded = false;
+    /**
+     * Initializes a new Play instance.
+     * @param console The Console instance used for network and media requests.
+     * @param playId The unique identifier for this play.
+     * @param playRawObj A raw dictionary containing the play's basic metadata.
+     */
     constructor(console, playId, playRawObj) {
         this._console = console;
         this._playId = playId;
@@ -31,54 +41,86 @@ export class Play {
         }
         this._playContentLoaded = false;
     }
+    /**
+     * Constructs the relative path for a media file associated with this play.
+     * @param mediaName The name of the media file.
+     * @returns The relative media path string.
+     */
     getPlayMediaPath(mediaName) {
         return `media/game/${this._playGameId}/play/${this._playId}/${mediaName}`;
     }
+    /**
+     * Generates the fully qualified URL to access a specific play media file.
+     * @param mediaName The name of the media file.
+     * @returns The full URL string.
+     */
     getMediaLink(mediaName) {
         let mediaPath = this.getPlayMediaPath(mediaName);
         return this._console.getMediaUrl(mediaPath);
     }
+    /**
+     * Asynchronously fetches the raw binary or parsed content of a specific media file.
+     * @param mediaName The name of the media file to fetch.
+     * @returns A promise resolving to the parsed media data (Blob, JSON, Text, etc.).
+     */
     async getMediaContent(mediaName) {
         let mediaPath = this.getPlayMediaPath(mediaName);
         return await this._console.getMedia(mediaPath);
     }
+    /**
+     * Asynchronously fetches the core data payload of the play using its registered file name.
+     * @returns A promise resolving to the play's main data object.
+     */
     async getMediaData() {
         return await this.getMediaContent(this._playFileName);
     }
+    /**
+     * Downloads and caches the main content of the play into memory, marking it as loaded.
+     */
     async updatePlayContent() {
         this._playContent = await this.getMediaData();
         this._playContentLoaded = true;
     }
+    /**
+     * Gets the loaded content dictionary of the play.
+     */
     get playContent() {
         return this._playContent;
     }
+    /**
+     * Checks if the play's main content has been fully loaded into memory.
+     * @returns True if the content is loaded, false otherwise.
+     */
     isPlayContentLoaded() {
         return this._playContentLoaded;
     }
     /**
-     * Get the data of the play
+     * Retrieves the file name serving as the main data entry point for the play.
      */
     get data() {
         return this._playFileName;
     }
     /**
-     * Get the id of the play
+     * Retrieves the unique identifier of the play.
      */
     get id() {
         return this._playId;
     }
     /**
-     * Get the name of the play
+     * Retrieves the name of the play.
      */
     get name() {
         return this._playName;
     }
     /**
-     * Get the image base64
+     * Retrieves the Base64 encoded thumbnail image of the play.
      */
     get image() {
         return this._playImagebase64;
     }
+    /**
+     * Checks if the play data is currently in a refreshed state.
+     */
     get isRefreshed() {
         return this._refreshed;
     }

package/dist/scripts/resident.d.ts

@@ -1,12 +1,31 @@
+/**
+ * Represents a Resident entity within the Koppelia ecosystem.
+ * Handles the resident's personal details and dynamic media URLs.
+ */
 export declare class Resident {
     private _name;
     private _id;
     private _image;
     private _residenceId;
     constructor();
+    /**
+     * Gets the unique identifier of the resident.
+     */
     get id(): string;
+    /**
+     * Gets the full name of the resident.
+     */
     get name(): string;
+    /**
+     * Constructs and retrieves the full URL to the resident's profile image.
+     * Uses the Koppelia singleton to resolve the correct media path.
+     * @returns The full URL string for the image.
+     */
     get imageUrl(): string;
+    /**
+     * Hydrates the Resident instance using properties from a provided raw object.
+     * @param object A dictionary containing the resident's properties.
+     */
     fromObject(object: {
         [key: string]: string;
     }): void;

package/dist/scripts/resident.js

@@ -1,4 +1,8 @@
 import { Koppelia } from "./koppelia.js";
+/**
+ * Represents a Resident entity within the Koppelia ecosystem.
+ * Handles the resident's personal details and dynamic media URLs.
+ */
 export class Resident {
     _name = "";
     _id = "";
@@ -6,17 +10,33 @@ export class Resident {
     _residenceId = "";
     constructor() {
     }
+    /**
+     * Gets the unique identifier of the resident.
+     */
     get id() {
         return this._id;
     }
+    /**
+     * Gets the full name of the resident.
+     */
     get name() {
         return this._name;
     }
+    /**
+     * Constructs and retrieves the full URL to the resident's profile image.
+     * Uses the Koppelia singleton to resolve the correct media path.
+     * @returns The full URL string for the image.
+     */
     get imageUrl() {
         let koppelia = Koppelia.instance;
-        let path = "/media/residence/" + this._residenceId + "/resident/" + this._id + "/" + this._image;
+        let path = "/media/residence/" + this._residenceId + "/resident/" +
+            this._id + "/" + this._image;
         return koppelia.getMediaLink(path);
     }
+    /**
+     * Hydrates the Resident instance using properties from a provided raw object.
+     * @param object A dictionary containing the resident's properties.
+     */
     fromObject(object) {
         this._name = object["name"];
         this._id = object["id"];

package/dist/scripts/song.d.ts

@@ -1,4 +1,8 @@
 import { Koppelia } from "./koppelia.js";
+/**
+ * Represents a Song entity, managing its metadata (artist, album, year)
+ * and providing access to its associated media files (audio tracks, cover, lyrics).
+ */
 export declare class Song {
     private _id;
     private _name;
@@ -23,14 +27,46 @@ export declare class Song {
     get style(): string;
     get year(): number;
     get length(): number;
+    /**
+     * Retrieves the base media folder path for this specific song.
+     * @returns The relative path to the song's media directory.
+     */
     getSongsFolderPath(): string;
+    /**
+     * Constructs the full URL for a specific media file within the song's folder.
+     * @param mediaName The file name of the media asset.
+     * @returns The fully qualified URL to access the media.
+     */
     getMediaUrl(mediaName: string): string;
+    /**
+     * Gets the URL for the main audio track.
+     */
     get songUrl(): string;
+    /**
+     * Gets the URL for the album cover image.
+     */
     get coverUrl(): string;
+    /**
+     * Gets the URL for the lyrics file.
+     */
     get lyricsUrl(): string;
+    /**
+     * Gets the URL for the backing track (instrumental).
+     */
     get songBackingUrl(): string;
+    /**
+     * Gets the URL for the vocal/lyrics audio track.
+     */
     get songLyricsUrl(): string;
+    /**
+     * Asynchronously fetches and reads the lyrics file content as plain text.
+     * @returns A promise resolving to the text content of the lyrics.
+     */
     getLyrics(): Promise<string>;
+    /**
+     * Hydrates the Song instance using properties from a provided raw JSON object.
+     * @param object A dictionary containing the song's metadata and file names.
+     */
     fromObject(object: {
         [key: string]: any;
     }): void;

package/dist/scripts/song.js

@@ -1,4 +1,8 @@
 import { Koppelia } from "./koppelia.js";
+/**
+ * Represents a Song entity, managing its metadata (artist, album, year)
+ * and providing access to its associated media files (audio tracks, cover, lyrics).
+ */
 export class Song {
     _id = "";
     _name = "";
@@ -40,32 +44,64 @@ export class Song {
     get length() {
         return this._length;
     }
+    /**
+     * Retrieves the base media folder path for this specific song.
+     * @returns The relative path to the song's media directory.
+     */
     getSongsFolderPath() {
         return "/media/song/" + this._id;
     }
+    /**
+     * Constructs the full URL for a specific media file within the song's folder.
+     * @param mediaName The file name of the media asset.
+     * @returns The fully qualified URL to access the media.
+     */
     getMediaUrl(mediaName) {
         let koppelia = Koppelia.instance;
         let path = this.getSongsFolderPath() + "/" + mediaName;
         return koppelia.getMediaLink(path);
     }
+    /**
+     * Gets the URL for the main audio track.
+     */
     get songUrl() {
         return this.getMediaUrl(this._songFile);
     }
+    /**
+     * Gets the URL for the album cover image.
+     */
     get coverUrl() {
         return this.getMediaUrl(this._coverImage);
     }
+    /**
+     * Gets the URL for the lyrics file.
+     */
     get lyricsUrl() {
         return this.getMediaUrl(this._lyricsFile);
     }
+    /**
+     * Gets the URL for the backing track (instrumental).
+     */
     get songBackingUrl() {
         return this.getMediaUrl(this._songBackingFile);
     }
+    /**
+     * Gets the URL for the vocal/lyrics audio track.
+     */
     get songLyricsUrl() {
         return this.getMediaUrl(this._songLyricsFile);
     }
+    /**
+     * Asynchronously fetches and reads the lyrics file content as plain text.
+     * @returns A promise resolving to the text content of the lyrics.
+     */
     async getLyrics() {
         return (await fetch(this.lyricsUrl)).text();
     }
+    /**
+     * Hydrates the Song instance using properties from a provided raw JSON object.
+     * @param object A dictionary containing the song's metadata and file names.
+     */
     fromObject(object) {
         this._name = object["name"];
         this._id = object["id"];

package/dist/scripts/stage.d.ts

@@ -1,12 +1,43 @@
 import { Console } from "./console.js";
+/**
+ * Manages application routing and views (stages) based on commands from the server.
+ * Ensures the local view is synchronized with the network's current stage.
+ */
 export declare class Stage {
     private _currentStage;
     private _stages;
     private _console;
+    /**
+     * Initializes the stage manager.
+     * @param console The Console instance used for network communication.
+     */
     constructor(console: Console);
+    /**
+     * Updates the local stage from the server.
+     * @todo Implementation pending.
+     */
     updateFromServer(): void;
+    /**
+     * Registers a list of available stages with the server.
+     * @param stages An array of stage names.
+     */
     initStages(stages: string[]): void;
+    /**
+     * Requests a stage transition via the server.
+     * @param stage The name of the target stage to navigate to.
+     */
     goto(stage: string): void;
+    /**
+     * Initializes listeners for incoming stage change commands from the console.
+     */
     private _initEvents;
+    /**
+     * Handles the reception of a stage change command.
+     * Clears all network events to prevent memory leaks, then triggers SvelteKit routing.
+     * @param from The origin peer that requested the stage change.
+     * @param receivedStage The name of the stage to load.
+     */
     private _onReceiveStage;
+    get currentStage(): string;
+    get stages(): string[];
 }

package/dist/scripts/stage.js

@@ -3,38 +3,72 @@ import { Message } from "./message.js";
 import { goto } from "$app/navigation";
 import { routeType } from "../stores/routeStore.js";
 import { get } from "svelte/store";
+/**
+ * Manages application routing and views (stages) based on commands from the server.
+ * Ensures the local view is synchronized with the network's current stage.
+ */
 export class Stage {
     _currentStage = "home";
     _stages = ["home"];
     _console;
+    /**
+     * Initializes the stage manager.
+     * @param console The Console instance used for network communication.
+     */
     constructor(console) {
         this._console = console;
         this._initEvents();
     }
+    /**
+     * Updates the local stage from the server.
+     * @todo Implementation pending.
+     */
     updateFromServer() {
     }
+    /**
+     * Registers a list of available stages with the server.
+     * @param stages An array of stage names.
+     */
     initStages(stages) {
         let req = new Message();
         req.setRequest("initStages");
         req.addParam("stages", stages);
         this._console.sendMessage(req);
+        this._stages = stages;
     }
+    /**
+     * Requests a stage transition via the server.
+     * @param stage The name of the target stage to navigate to.
+     */
     goto(stage) {
         let req = new Message();
         req.setRequest("changeStage");
         req.addParam("stage", stage);
         this._console.sendMessage(req);
     }
+    /**
+     * Initializes listeners for incoming stage change commands from the console.
+     */
     _initEvents() {
-        // update the state when receive a change from console
         this._console.onStageChange((from, stage) => {
             this._onReceiveStage(from, stage);
         });
     }
+    /**
+     * Handles the reception of a stage change command.
+     * Clears all network events to prevent memory leaks, then triggers SvelteKit routing.
+     * @param from The origin peer that requested the stage change.
+     * @param receivedStage The name of the stage to load.
+     */
     _onReceiveStage(from, receivedStage) {
-        // Destroy all events before changing stage
-        this._console.destroyEvents();
+        this._currentStage = receivedStage;
         let path = "/game/" + get(routeType) + "/" + receivedStage;
         goto(path);
     }
+    get currentStage() {
+        return this._currentStage;
+    }
+    get stages() {
+        return this._stages;
+    }
 }

package/dist/scripts/state.d.ts

@@ -3,36 +3,53 @@ import { type Writable } from "svelte/store";
 export type AnyState = {
     [key: string]: any;
 };
+/**
+ * Manages the synchronized global state of the application.
+ * Uses a Svelte writable store locally and syncs changes automatically with the server via the Console.
+ */
 export declare class State {
     private _globalState;
     private _console;
     private _access;
     private _previousStateValue;
     private _forceState;
+    /**
+     * Initializes the state manager.
+     * @param console The Console instance used for network communication.
+     * @param defaultState The initial state to populate the Svelte store with.
+     */
     constructor(console: Console, defaultState?: AnyState);
+    /**
+     * Retrieves the Svelte writable store containing the global state.
+     * @returns The Svelte writable store.
+     */
     get state(): Writable<AnyState>;
     /**
-     * Update the state from the server
+     * Requests the latest state from the server and updates the local store upon receiving the response.
      */
     updateFromServer(): void;
     /**
-     * Force change the state with a new one
-     * @param newState
+     * Completely overwrites the current state with a new state object.
+     * @param newState The new state object to apply.
+     * @param force If true, forces the entire state payload to be broadcasted instead of just the computed diffs.
      */
     setState(newState: AnyState, force?: boolean): void;
     /**
-     * Marge a new update to the last one
-     * @param stateUpdate
+     * Merges a partial update into the current global state.
+     * @param stateUpdate A dictionary containing only the keys/values to update.
      */
     updateState(stateUpdate: AnyState): void;
     /**
-     * Init all events
-     * @param from
-     * @param any
+     * Initializes core events: fetching state on readiness, listening for incoming state changes,
+     * and subscribing to the local Svelte store to broadcast outgoing changes.
      */
     private _initEvents;
     /**
-     * callback when a new state
+     * Internal handler executed when a new state is received from the network.
+     * Temporarily blocks local store subscriptions to prevent echo-broadcasting the received state.
+     * @param from The origin peer of the state.
+     * @param receivedState The state object payload.
+     * @param update Flag indicating if the payload is a partial update (true) or a full overwrite (false).
      */
     private _onReceiveState;
 }

package/dist/scripts/state.js

@@ -2,25 +2,38 @@ import { Console } from "./console.js";
 import { logger } from "./logger.js";
 import { Message } from "./message.js";
 import { get, writable } from "svelte/store";
+/**
+ * Manages the synchronized global state of the application.
+ * Uses a Svelte writable store locally and syncs changes automatically with the server via the Console.
+ */
 export class State {
     _globalState;
     _console;
     _access = true;
     _previousStateValue = {};
     _forceState;
+    /**
+     * Initializes the state manager.
+     * @param console The Console instance used for network communication.
+     * @param defaultState The initial state to populate the Svelte store with.
+     */
     constructor(console, defaultState = {}) {
         this._access = false;
         this._globalState = writable(defaultState);
         this._console = console;
-        this._forceState = false; // force the state without update
+        this._forceState = false;
         this._initEvents();
         this._access = true;
     }
+    /**
+     * Retrieves the Svelte writable store containing the global state.
+     * @returns The Svelte writable store.
+     */
     get state() {
         return this._globalState;
     }
     /**
-     * Update the state from the server
+     * Requests the latest state from the server and updates the local store upon receiving the response.
      */
     updateFromServer() {
         let req = new Message();
@@ -31,16 +44,17 @@ export class State {
         });
     }
     /**
-     * Force change the state with a new one
-     * @param newState
+     * Completely overwrites the current state with a new state object.
+     * @param newState The new state object to apply.
+     * @param force If true, forces the entire state payload to be broadcasted instead of just the computed diffs.
      */
     setState(newState, force = false) {
-        this._forceState = force; // if force to true -> force the state to be sent entirely instead of sending an update
+        this._forceState = force;
         this._globalState.set(newState);
     }
     /**
-     * Marge a new update to the last one
-     * @param stateUpdate
+     * Merges a partial update into the current global state.
+     * @param stateUpdate A dictionary containing only the keys/values to update.
      */
     updateState(stateUpdate) {
         let tempState = get(this._globalState);
@@ -50,20 +64,16 @@ export class State {
         this.setState(tempState);
     }
     /**
-     * Init all events
-     * @param from
-     * @param any
+     * Initializes core events: fetching state on readiness, listening for incoming state changes,
+     * and subscribing to the local Svelte store to broadcast outgoing changes.
      */
     _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.onStateChange((from, state, update) => {
             this._onReceiveState(from, state, update);
         });
-        // Send a change state request when detect a state change
         this._globalState.subscribe((newState) => {
             if (this._access) {
                 let update = {};
@@ -94,7 +104,11 @@ export class State {
         });
     }
     /**
-     * callback when a new state
+     * Internal handler executed when a new state is received from the network.
+     * Temporarily blocks local store subscriptions to prevent echo-broadcasting the received state.
+     * @param from The origin peer of the state.
+     * @param receivedState The state object payload.
+     * @param update Flag indicating if the payload is a partial update (true) or a full overwrite (false).
      */
     _onReceiveState(from, receivedState, update) {
         this._access = false;