brick-engine-js 1.0.16 → 1.0.18

package/dist/docs/reference/modules/GameScore.html

@@ -453,10 +453,11 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#resetscore-void">1.6. <code>resetScore(): void</code></a></li>
 <li><a href="#increaselevelamount-number-void">1.7. <code>increaseLevel(amount: number): void</code></a></li>
 <li><a href="#resetlevel-void">1.8. <code>resetLevel(): void</code></a></li>
-<li><a href="#getformattedscoredigits-number-string">1.9. <code>getFormattedScore(digits: number): string</code></a></li>
-<li><a href="#serialize-string">1.10. <code>serialize(): string</code></a></li>
-<li><a href="#deserializedata-string-void">1.11. <code>deserialize(data: string): void</code></a></li>
-<li><a href="#getdebugdata-recordstring-string-number-boolean">1.12. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></li>
+<li><a href="#setupgamehighscoreid-string-void">1.9. <code>setupGameHighScore(id: string): void</code></a></li>
+<li><a href="#getformattedscoredigits-number-string">1.10. <code>getFormattedScore(digits: number): string</code></a></li>
+<li><a href="#serialize-string">1.11. <code>serialize(): string</code></a></li>
+<li><a href="#deserializedata-string-void">1.12. <code>deserialize(data: string): void</code></a></li>
+<li><a href="#getdebugdata-recordstring-string-number-boolean">1.13. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></li>
 </ul>
 </li>
 </ul>
@@ -503,7 +504,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <p><strong>Behavior</strong></p>
 </div>
 <div class="paragraph">
-<p>When set, it automatically persists the value directly to <code>LocalStorage</code> under the <code>highScore</code> key. It does not use <code>GameState</code> for this persistence.</p>
+<p>When set, it automatically persists the value directly to <code>LocalStorage</code> under the namespaced key <code>${gameId}::highScore</code>. This ensures that different games do not overwrite each other&#8217;s records.</p>
 </div>
 <hr>
 </div>
@@ -581,12 +582,41 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div class="sect2">
 <h3 id="resetlevel-void"><a class="link" href="#resetlevel-void">1.8. <code>resetLevel(): void</code></a></h3>
 <div class="paragraph">
-<p>Resets the level counter to 1.</p>
+<p>Resets the level counter to 1.
+'''</p>
 </div>
+</div>
+<div class="sect2">
+<h3 id="setupgamehighscoreid-string-void"><a class="link" href="#setupgamehighscoreid-string-void">1.9. <code>setupGameHighScore(id: string): void</code></a></h3>
+<div class="paragraph">
+<p>Initializes the module with the specific game ID and loads the corresponding high score.</p>
+</div>
+<div class="paragraph">
+<p><strong>Parameters</strong></p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 20%;">
+<col style="width: 20%;">
+<col style="width: 60%;">
+</colgroup>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Name</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Type</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>id</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>string</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The unique game identifier used as a prefix for LocalStorage.</p></td>
+</tr>
+</tbody>
+</table>
 <hr>
 </div>
 <div class="sect2">
-<h3 id="getformattedscoredigits-number-string"><a class="link" href="#getformattedscoredigits-number-string">1.9. <code>getFormattedScore(digits: number): string</code></a></h3>
+<h3 id="getformattedscoredigits-number-string"><a class="link" href="#getformattedscoredigits-number-string">1.10. <code>getFormattedScore(digits: number): string</code></a></h3>
 <div class="paragraph">
 <p>Returns the score as a padded string suitable for HUD display.</p>
 </div>
@@ -621,7 +651,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <hr>
 </div>
 <div class="sect2">
-<h3 id="serialize-string"><a class="link" href="#serialize-string">1.10. <code>serialize(): string</code></a></h3>
+<h3 id="serialize-string"><a class="link" href="#serialize-string">1.11. <code>serialize(): string</code></a></h3>
 <div class="paragraph">
 <p><strong>Behavior</strong></p>
 </div>
@@ -631,7 +661,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <hr>
 </div>
 <div class="sect2">
-<h3 id="deserializedata-string-void"><a class="link" href="#deserializedata-string-void">1.11. <code>deserialize(data: string): void</code></a></h3>
+<h3 id="deserializedata-string-void"><a class="link" href="#deserializedata-string-void">1.12. <code>deserialize(data: string): void</code></a></h3>
 <div class="paragraph">
 <p><strong>Behavior</strong></p>
 </div>
@@ -641,7 +671,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <hr>
 </div>
 <div class="sect2">
-<h3 id="getdebugdata-recordstring-string-number-boolean"><a class="link" href="#getdebugdata-recordstring-string-number-boolean">1.12. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></h3>
+<h3 id="getdebugdata-recordstring-string-number-boolean"><a class="link" href="#getdebugdata-recordstring-string-number-boolean">1.13. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></h3>
 <div class="paragraph">
 <p>Returns metadata for the real-time debugger.</p>
 </div>

package/dist/docs/reference/modules/GameSession.html

@@ -445,8 +445,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#_session_management">1. Session Management</a>
 <ul class="sectlevel2">
 <li><a href="#_savesession_void">1.1. <code>saveSession(): void</code></a></li>
-<li><a href="#_clearsession_void">1.2. <code>clearSession(): void</code></a></li>
-<li><a href="#_syncstatestate_state_void">1.3. <code>syncState(state: State): void</code></a></li>
+<li><a href="#_setsessionenabledenabled_boolean_void">1.2. <code>setSessionEnabled(enabled: boolean): void</code></a></li>
+<li><a href="#_clearsession_void">1.3. <code>clearSession(): void</code></a></li>
+<li><a href="#_syncstatestate_state_void">1.4. <code>syncState(state: State): void</code></a></li>
 </ul>
 </li>
 <li><a href="#_internals">2. Internals</a></li>
@@ -467,17 +468,46 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div class="sect2">
 <h3 id="_savesession_void"><a class="link" href="#_savesession_void">1.1. <code>saveSession(): void</code></a></h3>
 <div class="paragraph">
-<p>Creates or updates the session. Early returns if the <code>GameID</code> belongs to the main menu (<code>game-menu</code>) or if the <code>SessionModal</code> (if existing) has not been confirmed/rejected yet.</p>
+<p>Creates or updates the session. Early returns if the session is disabled (via <code>setSessionEnabled</code>) or if the <code>SessionModal</code> (if existing) has not been confirmed/rejected yet.</p>
 </div>
+<hr>
 </div>
 <div class="sect2">
-<h3 id="_clearsession_void"><a class="link" href="#_clearsession_void">1.2. <code>clearSession(): void</code></a></h3>
+<h3 id="_setsessionenabledenabled_boolean_void"><a class="link" href="#_setsessionenabledenabled_boolean_void">1.2. <code>setSessionEnabled(enabled: boolean): void</code></a></h3>
+<div class="paragraph">
+<p>Enables or disables the session recovery mechanism. When disabled, the engine will neither show the session recovery modal nor save the session.</p>
+</div>
+<div class="paragraph">
+<p><strong>Parameters</strong></p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 20%;">
+<col style="width: 20%;">
+<col style="width: 60%;">
+</colgroup>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Name</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Type</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>enabled</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>boolean</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Whether the session should be enabled.</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="sect2">
+<h3 id="_clearsession_void"><a class="link" href="#_clearsession_void">1.3. <code>clearSession(): void</code></a></h3>
 <div class="paragraph">
 <p>Removes the saved instances from <code>localStorage</code>.</p>
 </div>
 </div>
 <div class="sect2">
-<h3 id="_syncstatestate_state_void"><a class="link" href="#_syncstatestate_state_void">1.3. <code>syncState(state: State): void</code></a></h3>
+<h3 id="_syncstatestate_state_void"><a class="link" href="#_syncstatestate_state_void">1.4. <code>syncState(state: State): void</code></a></h3>
 <div class="paragraph">
 <p>Subscribes to <code><a href="GameState.html">GameState</a></code> interactions.</p>
 </div>
@@ -508,7 +538,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 </div>
 <div class="paragraph">
 <p>Reacts to:
-- <code>PLAYING</code>: If a session for the current <code>gameId</code> exists, is NOT the game menu, and the modal hasn&#8217;t been closed, it invokes the modal via <code>_showSessionModal</code>. If accepted, calls deserialize on all registered targets. If canceled or if no previous session exists, proceeds normally. The modal state is tracked to prevent re-triggering during the same power cycle.
+- <code>PLAYING</code>: If a session for the current <code>gameId</code> exists, session is enabled, and the modal hasn&#8217;t been closed, it invokes the modal via <code>_showSessionModal</code>. If accepted, calls deserialize on all registered targets. If canceled or if no previous session exists, proceeds normally. The modal state is tracked to prevent re-triggering during the same power cycle.
 - <code>ON</code> (when false): Resets the modal state tracking closure, allowing the session modal to appear again after the device is powered back on.
 - <code>GAME_OVER</code>: Clears active session entirely.</p>
 </div>
@@ -526,7 +556,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-02-22 22:09:51 -0300
+Last updated 2026-02-24 23:17:20 -0300
 </div>
 </div>
 </body>

package/dist/docs/reference/modules/GameState.html

@@ -468,9 +468,15 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#ismuted-boolean">3.19. <code>isMuted(): boolean</code></a></li>
 <li><a href="#setmutedvalue-boolean-void">3.20. <code>setMuted(value: boolean): void</code></a></li>
 <li><a href="#togglemuted-void">3.21. <code>toggleMuted(): void</code></a></li>
-<li><a href="#subscribeproperty-stateproperty-callback-value-boolean-number-void-void">3.22. <code>subscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></li>
-<li><a href="#unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void">3.23. <code>unsubscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></li>
-<li><a href="#getdebugdata-recordstring-string-number-boolean">3.24. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></li>
+<li><a href="#notifyproperty-stateproperty-void">3.22. <code>notify(property: StateProperty): void</code></a></li>
+<li><a href="#syncstatestate-state-void">3.23. <code>syncState(state: State): void</code></a></li>
+<li><a href="#subscribeproperty-stateproperty-callback-value-boolean-number-void-void">3.24. <code>subscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></li>
+<li><a href="#unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void">3.25. <code>unsubscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></li>
+<li><a href="#subscribefortitlescreen-unsubscribefortitlescreen">3.26. <code>subscribeForTitleScreen(&#8230;&#8203;) / unsubscribeForTitleScreen(&#8230;&#8203;)</code></a></li>
+<li><a href="#subscribeforgameoverscreen-unsubscribeforgameoverscreen">3.27. <code>subscribeForGameOverScreen(&#8230;&#8203;) / unsubscribeForGameOverScreen(&#8230;&#8203;)</code></a></li>
+<li><a href="#subscribeforplayingscreen-unsubscribeforplayingscreen">3.28. <code>subscribeForPlayingScreen(&#8230;&#8203;) / unsubscribeForPlayingScreen(&#8230;&#8203;)</code></a></li>
+<li><a href="#subscribeforpausedscreen-unsubscribeforpausedscreen">3.29. <code>subscribeForPausedScreen(&#8230;&#8203;) / unsubscribeForPausedScreen(&#8230;&#8203;)</code></a></li>
+<li><a href="#getdebugdata-recordstring-string-number-boolean">3.30. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></li>
 </ul>
 </li>
 </ul>
@@ -817,9 +823,60 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <p>Toggles the master mute status.</p>
 </div>
 <hr>
+<hr>
+</div>
+<div class="sect2">
+<h3 id="notifyproperty-stateproperty-void"><a class="link" href="#notifyproperty-stateproperty-void">3.22. <code>notify(property: StateProperty): void</code></a></h3>
+<div class="paragraph">
+<p>Manually triggers notifications for a state property.</p>
+</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>This method dispatches to the base property channel AND to state-specific context channels (e.g., <code>TITLE</code>, <code>GAME_OVER</code>, <code>PLAYING</code>) based on the current engine state.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p><strong>Parameters</strong></p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 20%;">
+<col style="width: 20%;">
+<col style="width: 60%;">
+</colgroup>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Name</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Type</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>property</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code><a href="../enums/StateProperty.html">StateProperty</a></code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The property to trigger notifications for.</p></td>
+</tr>
+</tbody>
+</table>
+<hr>
+</div>
+<div class="sect2">
+<h3 id="syncstatestate-state-void"><a class="link" href="#syncstatestate-state-void">3.23. <code>syncState(state: State): void</code></a></h3>
+<div class="paragraph">
+<p>Syncs the internal state with the <code><a href="#">GameState</a></code>. This is required for modules that implement the <code><a href="../interfaces/StateSyncable.html">StateSyncable</a></code> interface.</p>
+</div>
+<hr>
 </div>
 <div class="sect2">
-<h3 id="subscribeproperty-stateproperty-callback-value-boolean-number-void-void"><a class="link" href="#subscribeproperty-stateproperty-callback-value-boolean-number-void-void">3.22. <code>subscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></h3>
+<h3 id="subscribeproperty-stateproperty-callback-value-boolean-number-void-void"><a class="link" href="#subscribeproperty-stateproperty-callback-value-boolean-number-void-void">3.24. <code>subscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></h3>
 <div class="paragraph">
 <p>Registers a listener for state changes.</p>
 </div>
@@ -865,7 +922,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <hr>
 </div>
 <div class="sect2">
-<h3 id="unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void"><a class="link" href="#unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void">3.23. <code>unsubscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></h3>
+<h3 id="unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void"><a class="link" href="#unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void">3.25. <code>unsubscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></h3>
 <div class="paragraph">
 <p>Removes a state change listener.</p>
 </div>
@@ -899,7 +956,63 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <hr>
 </div>
 <div class="sect2">
-<h3 id="getdebugdata-recordstring-string-number-boolean"><a class="link" href="#getdebugdata-recordstring-string-number-boolean">3.24. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></h3>
+<h3 id="subscribefortitlescreen-unsubscribefortitlescreen"><a class="link" href="#subscribefortitlescreen-unsubscribefortitlescreen">3.26. <code>subscribeForTitleScreen(&#8230;&#8203;) / unsubscribeForTitleScreen(&#8230;&#8203;)</code></a></h3>
+<div class="paragraph">
+<p>Specialized methods to listen for state changes <strong>ONLY</strong> while the engine is in the Title Screen state.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>These follow the same signature as <code>subscribe</code>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<hr>
+</div>
+<div class="sect2">
+<h3 id="subscribeforgameoverscreen-unsubscribeforgameoverscreen"><a class="link" href="#subscribeforgameoverscreen-unsubscribeforgameoverscreen">3.27. <code>subscribeForGameOverScreen(&#8230;&#8203;) / unsubscribeForGameOverScreen(&#8230;&#8203;)</code></a></h3>
+<div class="paragraph">
+<p>Specialized methods to listen for state changes <strong>ONLY</strong> while the engine is in the Game Over state.</p>
+</div>
+<hr>
+</div>
+<div class="sect2">
+<h3 id="subscribeforplayingscreen-unsubscribeforplayingscreen"><a class="link" href="#subscribeforplayingscreen-unsubscribeforplayingscreen">3.28. <code>subscribeForPlayingScreen(&#8230;&#8203;) / unsubscribeForPlayingScreen(&#8230;&#8203;)</code></a></h3>
+<div class="paragraph">
+<p>Specialized methods to listen for state changes <strong>ONLY</strong> while the engine is in the active Gameplay state.</p>
+</div>
+<hr>
+</div>
+<div class="sect2">
+<h3 id="subscribeforpausedscreen-unsubscribeforpausedscreen"><a class="link" href="#subscribeforpausedscreen-unsubscribeforpausedscreen">3.29. <code>subscribeForPausedScreen(&#8230;&#8203;) / unsubscribeForPausedScreen(&#8230;&#8203;)</code></a></h3>
+<div class="paragraph">
+<p>Specialized methods to listen for state changes <strong>ONLY</strong> while the engine is in the Paused state.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>These follow the same signature as <code>subscribe</code>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<hr>
+</div>
+<div class="sect2">
+<h3 id="getdebugdata-recordstring-string-number-boolean"><a class="link" href="#getdebugdata-recordstring-string-number-boolean">3.30. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></h3>
 <div class="paragraph">
 <p>Returns metadata for the real-time debugger.</p>
 </div>

package/dist/docs/reference/modules/InitialStateSnapshot.html

@@ -493,7 +493,10 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div class="sect2">
 <h3 id="captureinitialstate"><a class="link" href="#captureinitialstate">1.2. <code>captureInitialState</code></a></h3>
 <div class="paragraph">
-<p>Stores the initial state of custom client properties. It selectively clones properties that were not present in the base properties and are not functions, using deep copying (<code>structuredClone</code>) with a fallback to referencing.</p>
+<p>Stores the initial state of custom client properties. It selectively clones properties that were not present in the base properties and are not functions. The deep cloning strategy involves:
+1. Checking if the object has a custom <code>clone()</code> method.
+2. Attempting to use <code>structuredClone</code> for plain objects.
+3. Safely falling back to by-reference assignment for complex objects like P5 Vectors if other methods fail.</p>
 </div>
 <table class="tableblock frame-all grid-all stretch">
 <colgroup>
@@ -550,7 +553,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-02-22 17:57:57 -0300
+Last updated 2026-02-25 03:59:03 -0300
 </div>
 </div>
 </body>