@momo2555/koppeliajs 0.0.163 → 0.0.165

package/README.md

@@ -1,110 +1,468 @@
-# create-svelte
+# KoppeliaJS SDK 🎮
 
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
+**The official SvelteKit SDK for the Koppelia Console: Building accessible, real-time, zero-overstimulation games for seniors.**
 
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+KoppeliaJS is a specialized framework designed to bridge the gap between game development and cognitive accessibility. It allows developers to create synchronized, asymmetric, multi-screen experiences tailored for retirement homes and senior care facilities. By leveraging SvelteKit, WebSockets, and our Filarmonic Master Server, KoppeliaJS synchronizes UI, shared state, and physical IoT hardware seamlessly.
 
-## Creating a project
+---
 
-If you're seeing this, you've probably already done this step. Congrats!
+## 🌟 The Koppelia Ecosystem (Context)
 
-```bash
-# create a new project in the current directory
-npx sv create
+Koppelia is an asymmetric gaming console designed with a strict focus on cognitive accessibility and ergonomic physical interactions.
 
-# create a new project in my-app
-npx sv create my-app
-```
+### The Screens
+* 📺 **The Monitor (Players' Screen):** Plugged via HDMI to a TV. It displays **only essential information**. It is intentionally stripped of complex UI elements (no cursors, no complicated menus, no over-stimulation) to prevent cognitive overload for senior players.
+* 📱 **The Controller (Animator's Tablet):** Connected via Wi-Fi. This is the control center for the animator. It features the game settings, scores, real-time difficulty adjustments, and hidden mechanics. It acts as the "Dungeon Master" interface.
+
+### The Hardware & Backend
+* 🕹️ **The Devices:** Accessible controllers connected via BLE to the console. They feature a single luminous button, an IMU (Inertial Measurement Unit to detect orientation/motion), and a modular design (e.g., they can be clipped to an exercise bike).
+* 🖧 **Filarmonic (Master Server):** The core console server orchestrating Docker containers to spin up a dedicated web server for every game launch.
 
-## Developing
+---
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+## 🚀 Getting Started
+
+### 1. Initialize a New Game Project
+We recommend using Node.js version 20 to manage dependencies.
 
 ```bash
+npx sv create my-game
+# Prompts:
+# - Add to project: prettier, eslint
+# - SvelteKit adapter: auto
+# - Package manager: npm
+
+cd my-game
+npm install
 npm run dev
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+# Install the KoppeliaJS SDK
+npm install @momo2555/koppeliajs
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
-
-## Building
-
-To build your library:
+### 2. Configure the Environment
+Contact the administration to get your unique Game ID. Create an `.env` file at the root of your project:
 
-```bash
-npm run package
+```env
+PUBLIC_GAME_ID=your-unique-game-id
+PUBLIC_MOCE_ENV=dev
 ```
 
-To create a production version of your showcase app:
+*Note: In your `package.json`, update the preview script to expose your host: `"preview": "vite preview --host 0.0.0.0"`.*
+
+### 3. Basic Directory Structure
+Koppelia relies on SvelteKit dynamic routing to serve both the Monitor and the Controller from the same codebase. Create the necessary files:
 
 ```bash
-npm run build
+mkdir -p "src/routes/game/[type]/home"
+touch "src/routes/game/[type]/home/+page.svelte"
+touch "src/routes/+layout.svelte" 
 ```
 
-You can preview the production build with `npm run preview`.
+---
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+## 📖 Core Concepts & APIs
 
-## Publishing
+The KoppeliaJS SDK abstracts complex WebSocket networking and IoT Bluetooth management into simple Svelte stores and TypeScript classes. Below is a comprehensive breakdown of every system, how it works, its full capabilities, and an example.
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+### 1. Smart Routing (`routeType`)
 
-To publish your library to [npm](https://www.npmjs.com):
+#### How it works & Capabilities
+Because your codebase serves both the TV (Monitor) and the Tablet (Controller), the SDK provides a reactive Svelte store (`routeType`) to identify the current environment context. When the application loads, `updateRoute()` parses the URL to determine if the device is at `/game/monitor/...` or `/game/controller/...`. 
+This is the cornerstone of **isomorphic game design**: you write one Svelte component, and you use `if ($routeType === 'monitor')` to strip away buttons and complex UI, ensuring the TV remains accessible and visually clean for seniors.
 
-```bash
-npm publish
+#### Example
+**In `src/routes/+layout.svelte`:**
+```svelte
+<script>
+    import { updateRoute } from "@momo2555/koppeliajs";
+    // Parses the URL and sets the store globally
+    updateRoute();
+</script>
+
+<slot />
 ```
 
-```bash
-npm install --save-dev @types/node
+**In any component:**
+```svelte
+<script>
+    import { routeType } from "@momo2555/koppeliajs";
+</script>
+
+{#if $routeType === 'monitor'}
+    <h1>Welcome Players!</h1>
+    {:else if $routeType === 'controller'}
+    <h1>Animator Dashboard</h1>
+    <button>Force Next Level</button>
+{/if}
 ```
 
-# Features of Koppeliajs
-## Monitor and Controller
-**Monitor**: This the screen shown on the tv
+---
+
+### 2. Global State Synchronization (`koppelia.state`)
 
-**Controller**: This is the screen shown on the smartphone (Koppeli'App)
+#### How it works & Capabilities
+The `State` is a synchronized, real-time Svelte `Writable` store shared across the entire network. It is designed for **persistent game data** (e.g., scores, current question index, timers, player names).
+Under the hood, when you mutate the state, KoppeliaJS performs a diffing operation and broadcasts only the changes via WebSocket to all other connected screens. Because it extends a Svelte store, any UI bound to `$state` will automatically re-render when the server or another device alters the data.
 
-KoppeliaJS provides tools
+**Available Methods:**
+* `koppelia.updateState(partialObject)`: Merges the provided keys/values into the existing state (Recommended for performance).
+* `koppelia.setState(fullObject)`: Completely overwrites the global state tree.
 
-## State management
-Manage the state of the game, change easily the state, and get all updates from the server
+#### Example
+```svelte
+<script lang="ts">
+    import { Koppelia } from "@momo2555/koppeliajs";
+    
+    let koppelia = Koppelia.instance;
+    let state = koppelia.state;
 
-## Stage management
-A stage is a part of the game (it is a page), when the stage changes, it changes for the controller and monitor
+    function awardPoints() {
+        // Broadcasts the updated score to all screens instantly
+        koppelia.updateState({ 
+            score: $state.score + 10,
+            lastAction: "Points Awarded!"
+        });
+    }
+</script>
 
-## Device management
-Manage the devices connected to the console.
+<p>Current Score: {$state.score}</p>
 
-## Play management
-Manage the plays of the game. You can create new plays for a specific game on KOppelia'App.
+{#if $routeType === 'controller'}
+    <button on:click={awardPoints}>Award 10 Points</button>
+{/if}
+```
+
+---
+
+### 3. IoT Hardware Control (`Device`)
+
+#### How it works & Capabilities
+The `Device` class is your bridge to the physical world. Instead of dealing with BLE (Bluetooth Low Energy) protocols, the Master Server handles the connection and exposes an abstracted API through KoppeliaJS. You can control the visual feedback of the controllers and listen to their onboard IMU sensors.
+
+**Available Output Methods (Feedback):**
+* `setColor({ r, g, b, lon?, loff? })`: Sets a solid color. `lon` and `loff` can be used to create an automatic hardware blinking effect.
+* `setColorSequence(["RED", "BLUE", "GREEN"], reset)`: Sends a predefined color loop to the device.
+* `vibrate(time, blink?, blinkOff?, blinkCount?)`: Triggers the haptic motor. Can be set to a single long buzz, or a pulsing pattern (e.g., heartbeat effect).
+
+**Available Input Listeners:**
+* `onEvent(eventName, callback)`: Listens for physical button presses (e.g., "buzz").
+* `onVerticalDetector(callback(isVertical))`: Uses the IMU to detect if the controller is held upright or flat.
+* `onCursor(callback(x, y))`: Translates IMU spatial movement into 2D coordinates.
+* `onBiking(callback(speed))`: Reads data if the modular controller is clipped to a physical exercise bike pedal.
+
+#### Example
+```typescript
+import { Koppelia, Device } from "@momo2555/koppeliajs";
+let koppelia = Koppelia.instance;
+
+koppelia.onReady(async () => {
+    let devices: Device[] = await koppelia.getDevices();
+
+    for (let device of devices) {
+        // Setup visual feedback
+        device.setColor({ r: 0, g: 255, b: 0 }); // Green
+
+        // Listen for physical button press
+        device.onEvent("buzz", () => {
+            console.log(`${device.name} pressed the button!`);
+            // Trigger 500ms haptic feedback
+            device.vibrate(500); 
+            // Update the game state to lock out other players
+            koppelia.updateState({ winner: device.name });
+        });
+
+        // Listen for orientation (e.g., raising a hand/controller)
+        device.onVerticalDetector((isVertical) => {
+            if (isVertical) console.log(`${device.name} is holding the device up!`);
+        });
+    }
+});
+```
+
+---
+
+### 4. Remote Procedure Calls (`CustomCallbacks`)
+
+#### How it works & Capabilities
+While `State` is used for persistent data, **Custom Callbacks** are designed for **transient events**. If you need to trigger a one-off action (like playing a sound effect, triggering a CSS explosion animation, or forcing a hardware reset), using state is inefficient. Custom Callbacks act as a Remote Procedure Call (RPC) system to broadcast functions across the network.
+
+**Available Methods:**
+* `koppelia.on(name, callback(args))`: Registers a listener on the current device.
+* `koppelia.run(name, args)`: Broadcasts an execution request to all devices.
+* `koppelia.unsub(name)`: Removes a listener. **Crucial:** Always call this in Svelte's `onDestroy` lifecycle to prevent memory leaks when changing stages.
+
+#### Example
+```svelte
+<script lang="ts">
+    import { onMount, onDestroy } from "svelte";
+    import { Koppelia, routeType } from "@momo2555/koppeliajs";
+    let koppelia = Koppelia.instance;
+
+    if ($routeType === 'monitor') {
+        // The Monitor listens for the trigger
+        onMount(() => {
+            koppelia.on("playExplosion", (args) => {
+                showVisualExplosionAt(args.x, args.y);
+                audioManager.play("boom.mp3");
+            });
+        });
+
+        onDestroy(() => {
+            koppelia.unsub("playExplosion"); // Prevent memory leaks!
+        });
+    }
+
+    function triggerEventFromTablet() {
+        // The Animator clicks a button, sending the command to the Monitor
+        koppelia.run("playExplosion", { x: 50, y: 50 });
+    }
+</script>
+
+{#if $routeType === 'controller'}
+    <button on:click={triggerEventFromTablet}>Trigger Explosion</button>
+{/if}
+```
+
+---
 
-## difficulty Cursor
-Change the difficulty of the game in real time. The DifficultyCurser option should be activated on KoppeliaJS.
+### 5. Game Options (Live Settings)
 
-## Growable Element
-Growable elements are elements (generally text) that are shown on the monitor screen. Those elements can be expanded from the controller. They will take all the surface of the monitor screen.
+#### How it works & Capabilities
+Game Options allow the animator to adjust variables dynamically from their tablet menu without altering the core game state tree. The Master server processes these UI definitions and generates Native UI components on the Flutter Controller App. The Svelte application receives real-time updates when the animator moves a slider or toggles a switch.
 
-## Resizable Text
-Resizable text are text shwon on monitor screen and the font size can be changed in real time from Koppeli'App
+**Available Generators (Called by Controller):**
+* `createSliderOption(name, label, value, min, max, step)`: Creates a numeric slider.
+* `createSwitchOption(name, label, value)`: Creates a boolean toggle.
+* `createChoicesOption(name, label, value, choicesArray)`: Creates a dropdown/segmented control.
 
-## ScrollSyncer
+**Available Listeners (Used by both screens):**
+* `onOptionChanged(name, callback(data))`: Fires whenever the animator adjusts the generated UI.
 
-## StageButton
+#### Example
+```typescript
+import { Koppelia, routeType } from "@momo2555/koppeliajs";
+import { get } from "svelte/store";
+let koppelia = Koppelia.instance;
 
-# Start a new project with Koppelia js
+// Only the controller asks the Master Server to generate the UI
+if (get(routeType) === 'controller') {
+    koppelia.createSliderOption("gameSpeed", "Game Speed Modifier", 1.0, 0.5, 2.0, 0.1);
+    koppelia.createSwitchOption("hardMode", "Enable Hard Mode", false);
+}
 
-## Create a new project with npm
+// Both screens listen to the changes to adapt their logic
+koppelia.onOptionChanged("hardMode", (data) => {
+    let isHardModeEnabled = data.value;
+    if (isHardModeEnabled) {
+        enableStrictTimer();
+    }
+});
+```
+
+---
+
+### 6. CMS & Content (`Play`, `Resident`, `Song`)
+
+#### How it works & Capabilities
+Koppelia games are "engines" populated by content stored in the Filarmonic database. The SDK provides classes to securely fetch this data, automatically resolving complex media paths into usable URLs.
+* **`Resident`**: Profiles of the seniors. Contains `.name` and `.imageUrl` (automatically resolved) to display their faces on the TV.
+* **`Play`**: The content payload. E.g., a specific quiz deck. You must call `updatePlayContent()` to download the JSON payload into memory.
+* **`Song`**: Structured audio data featuring separate URLs for backing tracks, vocals, lyrics, and album covers.
+
+#### Example
+```typescript
+import { Koppelia, Resident, Play } from "@momo2555/koppeliajs";
+let koppelia = Koppelia.instance;
+
+koppelia.onReady(async () => {
+    // 1. Load Residents (Avatars)
+    let residents: Resident[] = await koppelia.getResidents();
+    console.log("Player 1 is:", residents[0].name);
+
+    // 2. Load the specific Game Content
+    let currentPlay: Play = await koppelia.getCurrentPlay();
+    await currentPlay.updatePlayContent(); // Triggers the actual download
+    
+    // Access the JSON payload created by the animator
+    let quizQuestions = currentPlay.playContent.questions;
+});
+```
 
-## Install sveltekit library
+---
 
-## Install koppeliajs library
+### 7. Stage Management (Server-Driven Navigation)
 
-## Minimum required files (file tree)
+#### How it works & Capabilities
+A "Stage" correlates directly to a SvelteKit route (e.g., `home`, `game`, `explanation`). Navigation in Koppelia is driven by the server. You do not use standard `<a>` tags or Svelte's `goto` manually. Instead, you ask the SDK to change the stage, which ensures that **both the Monitor and Controller transition to the new screen simultaneously**.
 
-## Run your game
+**Available Methods:**
+* `init(defaultState, stagesArray)`: Registers the permitted routes with the server.
+* `goto(stageName)`: Broadcasts a navigation command. The SDK will automatically clean up internal event listeners and force the browser to change URLs.
 
-## dockerize
+#### Example
+```typescript
+import { Koppelia } from "@momo2555/koppeliajs";
+let koppelia = Koppelia.instance;
+
+// Called on the boot screen
+koppelia.init(
+    { score: 0 }, 
+    ['home', 'game', 'results']
+);
+
+function startGame() {
+    // Both TV and Tablet will navigate to /game/[type]/game instantly
+    koppelia.goto('game'); 
+}
+```
 
+---
+
+## 🛠️ Global Practical Example
+
+Here is a comprehensive example demonstrating how Routing, State, Hardware, and Custom Callbacks come together in a single isomorphic `+page.svelte` file to create a fully functioning Quiz Game environment.
+
+```svelte
+<script lang="ts">
+    import { onDestroy, onMount } from "svelte";
+    import { get } from "svelte/store";
+    import { routeType, Koppelia, Device } from "@momo2555/koppeliajs";
+    
+    // Abstracted UI Components (Assumed to exist in your project)
+    import QuestionDisplay from "$lib/components/QuestionDisplay.svelte";
+    import Button from "$lib/components/Button.svelte";
+
+    let koppelia = Koppelia.instance;
+    let state = koppelia.state; 
+    let devices: Device[] = [];
+
+    // ==========================================
+    // 📺 MONITOR LOGIC (Game Rules & Hardware Hub)
+    // ==========================================
+    if ($routeType === "monitor") {
+        
+        onMount(() => {
+            // Track persistent data in the global state
+            koppelia.updateState({ questionStartTime: Date.now() });
+        });
+
+        onDestroy(() => {
+            // Prevent memory leaks when changing stages!
+            koppelia.unsub("qpc-unbuzz");
+            koppelia.unsub("resetDevices");
+        });
+
+        koppelia.onReady(async () => {
+            devices = await koppelia.getDevices();
+            let players = get(koppelia.state).players || {};
+
+            // 1. RPC Callback: Listen for Animator forcing a hardware reset
+            koppelia.on("resetDevices", () => {
+                for (let device of devices) device.setColorSequence([], true);
+            });
+
+            // 2. Hardware Initialization
+            for (let device of devices) {
+                // Initialize player data in the state
+                if (!Object.hasOwn(players, device.name)) {
+                    players[device.name] = { score: 0, name: device.name };
+                }
+
+                // Listen for physical buzzer presses
+                device.onEvent("buzz", () => {
+                    // Only accept buzz if nobody has buzzed yet
+                    if ($state.buzz === null) {
+                        device.vibrate(700); // Haptic feedback
+                        
+                        // Update global state! The tablet will instantly see who buzzed.
+                        koppelia.updateState({ buzz: $state.players[device.name] });
+                    }
+                });
+            }
+            // Push the registered players to the network
+            koppelia.updateState({ players });
+
+            // 3. RPC Callback: Reset the UI state if the Animator rejects an answer
+            koppelia.on("qpc-unbuzz", () => {
+                koppelia.updateState({ buzz: null }); 
+            });
+        });
+    }
+
+    // ==========================================
+    // 📱 CONTROLLER LOGIC (Animator Actions)
+    // ==========================================
+    function onSkip() {
+        koppelia.updateState({ buzz: null });
+        // Forces both screens to navigate to the explanation stage
+        koppelia.goto("explanation"); 
+    }
+
+    function onCorrect() {
+        // Mutate persistent state
+        let players = $state.players;
+        players[$state.buzz.name].score += 1;
+        koppelia.updateState({ players, answerState: "right" });
+        
+        // Wait 2 seconds, then change stage
+        setTimeout(() => {
+            koppelia.goto("explanation");
+            koppelia.updateState({ buzz: null });
+        }, 2000);
+    }
+
+    function onWrong() {
+        koppelia.updateState({ answerState: "bad" });
+        // RPC: Tell the Monitor to reset hardware/buzzer lockout
+        koppelia.run("qpc-unbuzz", {}); 
+    }
+</script>
+
+<div class="game-content">
+    
+    {#if $routeType === "controller"}
+        <div class="top-dashboard">
+            <p>Game Difficulty: {$state.difficulty}</p>
+        </div>
+    {/if}
+
+    <QuestionDisplay question={$state.question}></QuestionDisplay>
+
+    {#if $state.buzz !== null}
+        <h2>{$state.buzz.name} Buzzed!</h2>
+    {/if}
+
+    {#if $routeType === "controller"}
+        <div class="actions">
+            {#if $state.buzz !== null}
+                <Button text="Correct" color="green" callback={onCorrect} />
+                <Button text="Wrong" color="red" callback={onWrong} />
+            {:else}
+                <Button text="Skip Question" callback={onSkip} />
+            {/if}
+        </div>
+    {/if}
+</div>
+
+<style>
+    /* Strict layout control to prevent scrolling issues on the TV */
+    :global(body, html) {
+        margin: 0;
+        padding: 0;
+        height: 100vh;
+        overflow: hidden; 
+    }
+    .game-content {
+        background-color: #f8f9fa;
+        display: flex;
+        flex-direction: column;
+        height: 100vh; 
+        text-align: center;
+    }
+    .actions {
+        margin-top: auto;
+        padding: 20px;
+    }
+</style>
+```

package/dist/scripts/device.d.ts

@@ -18,31 +18,34 @@ export declare class Device {
     private _console;
     private _attachedEvents;
     private _resident?;
+    private _callbackIds;
+    private _eventsIds;
     private isAttachedToResident;
     constructor(console: Console, address?: string);
     get color(): Color;
     get name(): string;
+    get address(): string;
     /**
      * Subscribes to a specific hardware event for this device.
      * @param eventName The name of the event to listen to.
      * @param callback Function to execute when the event is triggered.
      */
-    onEvent(eventName: string, callback: () => void): void;
+    onEvent(eventName: string, callback: () => void): string;
     /**
      * Enables the cursor module and listens for coordinate updates.
      * @param callback Function to execute with the incoming (x, y) coordinates.
      */
-    onCursor(callback: (x: number, y: number) => void): void;
+    onCursor(callback: (x: number, y: number) => void): string;
     /**
      * Enables the biking module and listens for speed updates.
      * @param callback Function to execute with the incoming speed data.
      */
-    onBiking(callback: (speed: number) => void): void;
+    onBiking(callback: (speed: number) => void): string;
     /**
      * Enables the vertical detector module and listens for orientation updates.
      * @param callback Function to execute with the boolean vertical state.
      */
-    onVerticalDetector(callback: (vertical: boolean) => void): void;
+    onVerticalDetector(callback: (vertical: boolean) => void): string;
     /**
      * Sends a request to the device to attach a specific event listener on the hardware side.
      * @param event The event name to attach.
@@ -72,6 +75,10 @@ export declare class Device {
      * @param blinkCount The number of pulsing cycles to execute.
      */
     vibrate(time: number, blink?: boolean, blinkOff?: number, blinkCount?: number): void;
+    clearCallback(callbackId: string): void;
+    clearAllCallbacks(): void;
+    clearEvent(eventId: string): void;
+    clearAllEvents(): void;
     /**
      * Serializes the Device object into a generic dictionary.
      * @returns A plain object representing the device's current state.

package/dist/scripts/device.js

@@ -12,6 +12,8 @@ export class Device {
     _console;
     _attachedEvents;
     _resident;
+    _callbackIds;
+    _eventsIds;
     isAttachedToResident;
     constructor(console, address = "") {
         this._address = address;
@@ -19,6 +21,8 @@ export class Device {
         this._name = "";
         this._console = console;
         this._attachedEvents = [];
+        this._callbackIds = [];
+        this._eventsIds = [];
         this.isAttachedToResident = false;
     }
     get color() {
@@ -27,6 +31,9 @@ export class Device {
     get name() {
         return this._name;
     }
+    get address() {
+        return this._address;
+    }
     /**
      * Subscribes to a specific hardware event for this device.
      * @param eventName The name of the event to listen to.
@@ -39,7 +46,7 @@ export class Device {
                 callback();
             }
         };
-        this._console.onDeviceEvent(consoleEvent);
+        return this._console.onDeviceEvent(consoleEvent);
     }
     /**
      * Enables the cursor module and listens for coordinate updates.
@@ -48,11 +55,13 @@ export class Device {
     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.
@@ -61,11 +70,13 @@ export class Device {
     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.
@@ -74,11 +85,13 @@ export class Device {
     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.
@@ -153,6 +166,26 @@ 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);
+        }
+    }
     /**
      * Serializes the Device object into a generic dictionary.
      * @returns A plain object representing the device's current state.

package/dist/scripts/koppelia.d.ts

@@ -64,6 +64,7 @@ export declare class Koppelia {
      * @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.
@@ -81,6 +82,10 @@ export declare class Koppelia {
      * @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;
     /**
      * Retrieves the unique identifier of the currently loaded game.
      * @returns The game ID string provided by public environment variables.

package/dist/scripts/koppelia.js

@@ -118,6 +118,9 @@ export class Koppelia {
     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.
@@ -144,9 +147,9 @@ export class Koppelia {
             getDevicesRequest.setRequest("getDevices");
             getDevicesRequest.setDestination(PeerType.MASTER, "");
             this._console.sendMessage(getDevicesRequest, (response) => {
-                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);
@@ -155,6 +158,26 @@ 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);
+    }
     /**
      * Retrieves the unique identifier of the currently loaded game.
      * @returns The game ID string provided by public environment variables.

package/dist/scripts/stage.d.ts

@@ -38,4 +38,6 @@ export declare class Stage {
      * @param receivedStage The name of the stage to load.
      */
     private _onReceiveStage;
+    get currentStage(): string;
+    get stages(): string[];
 }

package/dist/scripts/stage.js

@@ -34,6 +34,7 @@ export class Stage {
         req.setRequest("initStages");
         req.addParam("stages", stages);
         this._console.sendMessage(req);
+        this._stages = stages;
     }
     /**
      * Requests a stage transition via the server.
@@ -60,8 +61,14 @@ export class Stage {
      * @param receivedStage The name of the stage to load.
      */
     _onReceiveStage(from, receivedStage) {
-        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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@momo2555/koppeliajs",
-	"version": "0.0.163",
+	"version": "0.0.165",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run package",