brick-engine-js 1.0.39 → 1.0.40

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

@@ -5,7 +5,7 @@
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="generator" content="Asciidoctor 2.0.20">
-<meta name="description" content="Manages the engine's logical clock, decoupling game logic ticks from the visual frame rate.">
+<meta name="description" content="Orchestrates the engine's logical clock and performance metrics.">
 <meta name="keywords" content="time, clock, tick, interval, game-loop">
 <title>GameTime Module Reference</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
@@ -446,19 +446,27 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#architectural-purpose">1. Architectural Purpose</a></li>
 <li><a href="#api-reference">2. API Reference</a>
 <ul class="sectlevel2">
-<li><a href="#tickinterval-number">2.1. <code>tickInterval: number</code></a></li>
-<li><a href="#totalticks-number">2.2. <code>totalTicks: number</code></a></li>
-<li><a href="#elapsedtime-number">2.3. <code>elapsedTime: number</code></a></li>
-<li><a href="#shouldtick-boolean">2.4. <code>shouldTick(): boolean</code></a></li>
-<li><a href="#updatedeltatime-number-void">2.5. <code>update(deltaTime: number): void</code></a></li>
-<li><a href="#reset-void">2.6. <code>reset(): void</code></a></li>
-<li><a href="#istickeveryinterval-number-boolean">2.7. <code>isTickEvery(interval: number): boolean</code></a></li>
-<li><a href="#incrementtickintervalamount-number-void">2.8. <code>incrementTickInterval(amount: number): void</code></a></li>
-<li><a href="#decrementtickintervalamount-number-void">2.9. <code>decrementTickInterval(amount: number): void</code></a></li>
-<li><a href="#settickintervalinterval-number-void">2.10. <code>setTickInterval(interval: number): void</code></a></li>
-<li><a href="#setmintickintervalinterval-number-void">2.11. <code>setMinTickInterval(interval: number): void</code></a></li>
-<li><a href="#getdebugdata-recordstring-string-number-boolean">2.12. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></li>
-<li><a href="#captureinitialstate-void">2.13. <code>captureInitialState(): void</code></a></li>
+<li><a href="#core-loop-control">2.1. Core Loop Control</a>
+<ul class="sectlevel3">
+<li><a href="#updatedeltatime-number-void">2.1.1. <code>update(deltaTime: number): void</code></a></li>
+<li><a href="#accumulatedeltatime-number-void">2.1.2. <code>accumulate(deltaTime: number): void</code></a></li>
+<li><a href="#shouldtick-boolean">2.1.3. <code>shouldTick(): boolean</code></a></li>
+<li><a href="#reset-void">2.1.4. <code>reset(): void</code></a></li>
+</ul>
+</li>
+<li><a href="#declarative-timing">2.2. Declarative Timing</a>
+<ul class="sectlevel3">
+<li><a href="#atintervalms-number-boolean">2.2.1. <code>atInterval(ms: number): boolean</code></a></li>
+<li><a href="#everyms-number-action-void-void">2.2.2. <code>every(ms: number, action: () &#8658; void): void</code></a></li>
+</ul>
+</li>
+<li><a href="#persistence-debug">2.3. Persistence &amp; Debug</a>
+<ul class="sectlevel3">
+<li><a href="#getdebugdata-recordstring-string-number-boolean">2.3.1. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></li>
+<li><a href="#serialize-string">2.3.2. <code>serialize(): string</code></a></li>
+<li><a href="#deserializedata-string-void">2.3.3. <code>deserialize(data: string): void</code></a></li>
+</ul>
+</li>
 </ul>
 </li>
 </ul>
@@ -469,7 +477,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <h2 id="architectural-purpose"><a class="link" href="#architectural-purpose">1. Architectural Purpose</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>The <code>GameTime</code> module manages the engine&#8217;s logical clock independent of the visual context. By decoupling the deterministic game logic "ticks" from the unpredictable visual frame rate of the browser, it ensures consistent gameplay speed and difficulty-progression physics regardless of the device&#8217;s hardware performance capabilities.</p>
+<p>The <code>GameTime</code> module is designed to decouple deterministic game logic "ticks" from the unpredictable visual frame rate of the browser. By maintaining an internal time accumulator, it ensures that gameplay events (like physics, timers, and difficulty scaling) execute at a consistent speed regardless of the host device&#8217;s hardware performance or FPS fluctuations.</p>
 </div>
 </div>
 </div>
@@ -477,61 +485,14 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <h2 id="api-reference"><a class="link" href="#api-reference">2. API Reference</a></h2>
 <div class="sectionbody">
 <div class="sect2">
-<h3 id="tickinterval-number"><a class="link" href="#tickinterval-number">2.1. <code>tickInterval: number</code></a></h3>
-<div class="paragraph">
-<p>Getter/Setter for the game logic speed in milliseconds.</p>
-</div>
-<div class="paragraph">
-<p><strong>Returns</strong></p>
-</div>
-<div class="paragraph">
-<p><code>number</code> - The current time between logic ticks.</p>
-</div>
-<div class="paragraph">
-<p><strong>Behavior</strong></p>
-</div>
-<div class="paragraph">
-<p>Lowering this value makes the game run faster (e.g., used for difficulty progression).</p>
-</div>
-<hr>
-</div>
-<div class="sect2">
-<h3 id="totalticks-number"><a class="link" href="#totalticks-number">2.2. <code>totalTicks: number</code></a></h3>
-<div class="paragraph">
-<p>Read-only property returning the total number of logic ticks that have occurred since the game started.</p>
-</div>
-<hr>
-</div>
-<div class="sect2">
-<h3 id="elapsedtime-number"><a class="link" href="#elapsedtime-number">2.3. <code>elapsedTime: number</code></a></h3>
-<div class="paragraph">
-<p>Read-only property returning the total time in milliseconds elapsed since the game started.</p>
-</div>
-<hr>
-</div>
-<div class="sect2">
-<h3 id="shouldtick-boolean"><a class="link" href="#shouldtick-boolean">2.4. <code>shouldTick(): boolean</code></a></h3>
-<div class="paragraph">
-<p>Determines if a logic update should be executed.</p>
-</div>
-<div class="paragraph">
-<p><strong>Returns</strong></p>
-</div>
-<div class="paragraph">
-<p><code>boolean</code> - <code>true</code> if the internal ticker buffer (accumulator) has exceeded the <code>tickInterval</code>.</p>
-</div>
+<h3 id="core-loop-control"><a class="link" href="#core-loop-control">2.1. Core Loop Control</a></h3>
 <div class="paragraph">
-<p><strong>Behavior</strong></p>
-</div>
-<div class="paragraph">
-<p>Called by the main loop. If it returns true, it automatically subtracts the <code>tickInterval</code> from the <code>tickAccumulator</code> to maintain a stable clock.</p>
-</div>
-<hr>
+<p>These methods are used by the engine&#8217;s main loop to synchronize logical state updates with the physical rendering time.</p>
 </div>
-<div class="sect2">
-<h3 id="updatedeltatime-number-void"><a class="link" href="#updatedeltatime-number-void">2.5. <code>update(deltaTime: number): void</code></a></h3>
+<div class="sect3">
+<h4 id="updatedeltatime-number-void"><a class="link" href="#updatedeltatime-number-void">2.1.1. <code>update(deltaTime: number): void</code></a></h4>
 <div class="paragraph">
-<p>Advances the internal time buffer (tick accumulator).</p>
+<p>Calculates the current physical performance metrics (FPS/TPS). This method should be called exactly once per visual frame.</p>
 </div>
 <div class="paragraph">
 <p><strong>Parameters</strong></p>
@@ -551,29 +512,16 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>deltaTime</code></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>number</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Time physically elapsed since the last rendering frame (in milliseconds).</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The physical time elapsed since the last rendering frame in milliseconds.</p></td>
 </tr>
 </tbody>
 </table>
 <hr>
 </div>
-<div class="sect2">
-<h3 id="reset-void"><a class="link" href="#reset-void">2.6. <code>reset(): void</code></a></h3>
+<div class="sect3">
+<h4 id="accumulatedeltatime-number-void"><a class="link" href="#accumulatedeltatime-number-void">2.1.2. <code>accumulate(deltaTime: number): void</code></a></h4>
 <div class="paragraph">
-<p>Clears the tick accumulator.</p>
-</div>
-<div class="paragraph">
-<p><strong>Behavior</strong></p>
-</div>
-<div class="paragraph">
-<p>Prevents a "burst" of logic updates after resuming from a long pause or game restart.</p>
-</div>
-<hr>
-</div>
-<div class="sect2">
-<h3 id="istickeveryinterval-number-boolean"><a class="link" href="#istickeveryinterval-number-boolean">2.7. <code>isTickEvery(interval: number): boolean</code></a></h3>
-<div class="paragraph">
-<p>Returns <code>true</code> if the <code>totalTicks</code> is a multiple of the specified <code>interval</code>. Useful for scheduling recurring game events (e.g., spawning an item every 20 ticks).</p>
+<p>Adds elapsed time to the logical simulation accumulator. This allows the engine to track how much logical time needs to be processed.</p>
 </div>
 <div class="paragraph">
 <p><strong>Parameters</strong></p>
@@ -591,53 +539,56 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <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>interval</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>deltaTime</code></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>number</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The tick frequency interval constraint to check against.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Time in milliseconds to add to the logic simulation.</p></td>
 </tr>
 </tbody>
 </table>
+<hr>
+</div>
+<div class="sect3">
+<h4 id="shouldtick-boolean"><a class="link" href="#shouldtick-boolean">2.1.3. <code>shouldTick(): boolean</code></a></h4>
+<div class="paragraph">
+<p>Evaluates if the engine should execute a logical simulation tick based on the accumulated time.</p>
+</div>
 <div class="paragraph">
 <p><strong>Returns</strong></p>
 </div>
 <div class="paragraph">
-<p><code>boolean</code> - <code>true</code> if the current tick is a multiple of the interval (and greater than 0).</p>
+<p><code>boolean</code> - <code>true</code> if at least one tick&#8217;s worth of time was consumed from the accumulator.</p>
+</div>
+<div class="paragraph">
+<p><strong>Behavior</strong></p>
+</div>
+<div class="paragraph">
+<p>When this method returns <code>true</code>, it has already internally consumed all pending ticks from the <code>_tickAccumulator</code> to prevent "speed-up" bursts after lag, while allowing the caller to perform a single logical update.</p>
 </div>
 <hr>
 </div>
-<div class="sect2">
-<h3 id="incrementtickintervalamount-number-void"><a class="link" href="#incrementtickintervalamount-number-void">2.8. <code>incrementTickInterval(amount: number): void</code></a></h3>
+<div class="sect3">
+<h4 id="reset-void"><a class="link" href="#reset-void">2.1.4. <code>reset(): void</code></a></h4>
 <div class="paragraph">
-<p>Slows down the game by increasing the time between ticks.</p>
+<p>Resets all internal timers, statistical accumulators, and logical counters to their baseline values.</p>
 </div>
 <div class="paragraph">
-<p><strong>Parameters</strong></p>
+<p><strong>Behavior</strong></p>
+</div>
+<div class="paragraph">
+<p>Prevents a "burst" of logic updates after resuming from a long pause or game restart by clearing the time accumulator.</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>amount</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>number</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Milliseconds to add to the interval.</p></td>
-</tr>
-</tbody>
-</table>
 <hr>
 </div>
+</div>
 <div class="sect2">
-<h3 id="decrementtickintervalamount-number-void"><a class="link" href="#decrementtickintervalamount-number-void">2.9. <code>decrementTickInterval(amount: number): void</code></a></h3>
+<h3 id="declarative-timing"><a class="link" href="#declarative-timing">2.2. Declarative Timing</a></h3>
 <div class="paragraph">
-<p>Speeds up the game by decreasing the time between ticks.</p>
+<p>These methods provide a high-level API for developers to schedule events based on logical game time rather than raw frame counts.</p>
+</div>
+<div class="sect3">
+<h4 id="atintervalms-number-boolean"><a class="link" href="#atintervalms-number-boolean">2.2.1. <code>atInterval(ms: number): boolean</code></a></h4>
+<div class="paragraph">
+<p>Checks if the logical game clock has just crossed a multiple of the specified millisecond interval.</p>
 </div>
 <div class="paragraph">
 <p><strong>Parameters</strong></p>
@@ -655,18 +606,34 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <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>amount</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ms</code></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>number</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Milliseconds to subtract from the interval.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The millisecond interval to check against.</p></td>
 </tr>
 </tbody>
 </table>
+<div class="paragraph">
+<p><strong>Returns</strong></p>
+</div>
+<div class="paragraph">
+<p><code>boolean</code> - <code>true</code> if the logical clock just crossed a boundary of the interval.</p>
+</div>
+<div class="paragraph">
+<p><strong>Example</strong></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">if (time.atInterval(500)) {
+    this.blink();
+}</code></pre>
+</div>
+</div>
 <hr>
 </div>
-<div class="sect2">
-<h3 id="settickintervalinterval-number-void"><a class="link" href="#settickintervalinterval-number-void">2.10. <code>setTickInterval(interval: number): void</code></a></h3>
+<div class="sect3">
+<h4 id="everyms-number-action-void-void"><a class="link" href="#everyms-number-action-void-void">2.2.2. <code>every(ms: number, action: () &#8658; void): void</code></a></h4>
 <div class="paragraph">
-<p>Sets the tick interval exactly to the specified value.</p>
+<p>Executes a callback function every N milliseconds of logical game time.</p>
 </div>
 <div class="paragraph">
 <p><strong>Parameters</strong></p>
@@ -684,18 +651,63 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <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>interval</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ms</code></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>number</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The precise new integer interval interval between logic updates (in milliseconds).</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The millisecond interval between executions.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>action</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>() &#8658; void</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The callback function to execute.</p></td>
 </tr>
 </tbody>
 </table>
+<div class="paragraph">
+<p><strong>Example</strong></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-typescript hljs" data-lang="typescript">time.every(1000, () =&gt; this.spawnEnemy());</code></pre>
+</div>
+</div>
 <hr>
 </div>
+</div>
 <div class="sect2">
-<h3 id="setmintickintervalinterval-number-void"><a class="link" href="#setmintickintervalinterval-number-void">2.11. <code>setMinTickInterval(interval: number): void</code></a></h3>
+<h3 id="persistence-debug"><a class="link" href="#persistence-debug">2.3. Persistence &amp; Debug</a></h3>
 <div class="paragraph">
-<p>Sets the minimum limit for the tick interval, preventing the game from speeding up beyond this point.</p>
+<p>Methods for state serialization and performance inspection.</p>
+</div>
+<div class="sect3">
+<h4 id="getdebugdata-recordstring-string-number-boolean"><a class="link" href="#getdebugdata-recordstring-string-number-boolean">2.3.1. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></h4>
+<div class="paragraph">
+<p>Returns metadata for the real-time debugger and performance monitoring.</p>
+</div>
+<div class="paragraph">
+<p><strong>Returns</strong></p>
+</div>
+<div class="paragraph">
+<p><code>Record&lt;string, string | number | boolean&gt;</code> - Object containing <code>fps</code>, <code>tps</code>, and <code>elapsedTime</code>.</p>
+</div>
+<hr>
+</div>
+<div class="sect3">
+<h4 id="serialize-string"><a class="link" href="#serialize-string">2.3.2. <code>serialize(): string</code></a></h4>
+<div class="paragraph">
+<p>Converts the persistent time state into a JSON string.</p>
+</div>
+<div class="paragraph">
+<p><strong>Returns</strong></p>
+</div>
+<div class="paragraph">
+<p><code>string</code> - The serialized state.</p>
+</div>
+<hr>
+</div>
+<div class="sect3">
+<h4 id="deserializedata-string-void"><a class="link" href="#deserializedata-string-void">2.3.3. <code>deserialize(data: string): void</code></a></h4>
+<div class="paragraph">
+<p>Restores the time state from a JSON string.</p>
 </div>
 <div class="paragraph">
 <p><strong>Parameters</strong></p>
@@ -713,37 +725,12 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <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>interval</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>number</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The strict minimum boundary interval allowed (in milliseconds).</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>data</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 JSON string containing the state.</p></td>
 </tr>
 </tbody>
 </table>
-<hr>
-</div>
-<div class="sect2">
-<h3 id="getdebugdata-recordstring-string-number-boolean"><a class="link" href="#getdebugdata-recordstring-string-number-boolean">2.12. <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>
-<div class="paragraph">
-<p><strong>Returns</strong></p>
-</div>
-<div class="paragraph">
-<p><code>Record&lt;string, string | number | boolean&gt;</code> - Object containing <code>fps</code> (Frames Per Second), <code>tps</code> (Ticks Per Second), <code>tick_interval</code>, and <code>tick_accumulator</code>.</p>
-</div>
-<hr>
-</div>
-<div class="sect2">
-<h3 id="captureinitialstate-void"><a class="link" href="#captureinitialstate-void">2.13. <code>captureInitialState(): void</code></a></h3>
-<div class="paragraph">
-<p>Captures the current <code>tickInterval</code> as the starting speed for the game session.</p>
-</div>
-<div class="paragraph">
-<p><strong>Behavior</strong></p>
-</div>
-<div class="paragraph">
-<p>This method is called by the <code>Game</code> engine after the game-specific <code>setupGame()</code> has executed. It ensures that when <code>reset()</code> is called, the game returns to its intended initial speed rather than the engine&#8217;s global default.</p>
 </div>
 </div>
 </div>