brick-engine-js 1.0.38 → 1.0.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/README.adoc +1 -1
  2. package/dist/docs/index.html +2 -2
  3. package/dist/docs/reference/enums/ControlKey.html +4 -0
  4. package/dist/docs/reference/enums/ScoreProperty.html +526 -0
  5. package/dist/docs/reference/enums/StateProperty.html +4 -0
  6. package/dist/docs/reference/interfaces/StateSyncable.html +1 -1
  7. package/dist/docs/reference/interfaces/modules/Score.html +182 -32
  8. package/dist/docs/reference/interfaces/modules/State.html +88 -36
  9. package/dist/docs/reference/interfaces/modules/Time.html +61 -145
  10. package/dist/docs/reference/modules/GameEventRegistry.html +10 -4
  11. package/dist/docs/reference/modules/GameScore.html +339 -71
  12. package/dist/docs/reference/modules/GameState.html +256 -163
  13. package/dist/docs/reference/modules/GameTime.html +136 -149
  14. package/dist/game.bundle.js +1 -1
  15. package/dist/types/config/configs.d.ts +2 -4
  16. package/dist/types/core/Game.d.ts +17 -10
  17. package/dist/types/core/module/score/GameScore.d.ts +24 -0
  18. package/dist/types/core/module/time/GameTime.d.ts +62 -63
  19. package/dist/types/core/types/enums.d.ts +11 -0
  20. package/dist/types/core/types/modules.d.ts +70 -60
  21. package/dist/types/view/ShortcutsModal.test.d.ts +1 -0
  22. package/package.json +1 -1
package/dist/docs/reference/modules/GameState.html CHANGED
@@ -448,36 +448,57 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
448
448
  <li><a href="#persistence-vs-session">3. Persistence vs. Session</a></li>
449
449
  <li><a href="#api-reference">4. API Reference</a>
450
450
  <ul class="sectlevel2">
451
- <li><a href="#ison-boolean">4.1. <code>isOn(): boolean</code></a></li>
452
- <li><a href="#isoff-boolean">4.2. <code>isOff(): boolean</code></a></li>
453
- <li><a href="#isstarted-boolean">4.3. <code>isStarted(): boolean</code></a></li>
454
- <li><a href="#isplaying-boolean">4.4. <code>isPlaying(): boolean</code></a></li>
455
- <li><a href="#ispaused-boolean">4.5. <code>isPaused(): boolean</code></a></li>
456
- <li><a href="#isgameover-boolean">4.6. <code>isGameOver(): boolean</code></a></li>
457
- <li><a href="#turnon-void">4.7. <code>turnOn(): void</code></a></li>
458
- <li><a href="#turnoff-void">4.8. <code>turnOff(): void</code></a></li>
459
- <li><a href="#startgame-void">4.9. <code>startGame(): void</code></a></li>
460
- <li><a href="#exitgame-void">4.10. <code>exitGame(): void</code></a></li>
461
- <li><a href="#pause-void">4.11. <code>pause(): void</code></a></li>
462
- <li><a href="#resume-void">4.12. <code>resume(): void</code></a></li>
463
- <li><a href="#triggergameover-void">4.13. <code>triggerGameOver(): void</code></a></li>
464
- <li><a href="#resetgame-void">4.14. <code>resetGame(): void</code></a></li>
465
- <li><a href="#resetgameover-void">4.15. <code>resetGameOver(): void</code></a></li>
466
- <li><a href="#iscolorenabled-boolean">4.16. <code>isColorEnabled(): boolean</code></a></li>
467
- <li><a href="#setcolorenabledvalue-boolean-void">4.17. <code>setColorEnabled(value: boolean): void</code></a></li>
468
- <li><a href="#togglecolorenabled-void">4.18. <code>toggleColorEnabled(): void</code></a></li>
469
- <li><a href="#ismuted-boolean">4.19. <code>isMuted(): boolean</code></a></li>
470
- <li><a href="#setmutedvalue-boolean-void">4.20. <code>setMuted(value: boolean): void</code></a></li>
471
- <li><a href="#togglemuted-void">4.21. <code>toggleMuted(): void</code></a></li>
472
- <li><a href="#notifyproperty-stateproperty-void">4.22. <code>notify(property: StateProperty): void</code></a></li>
473
- <li><a href="#syncstatestate-state-void">4.23. <code>syncState(state: State): void</code></a></li>
474
- <li><a href="#subscribeproperty-stateproperty-callback-value-boolean-number-void-void">4.24. <code>subscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></li>
475
- <li><a href="#unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void">4.25. <code>unsubscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></li>
476
- <li><a href="#subscribefortitlescreen-unsubscribefortitlescreen">4.26. <code>subscribeForTitleScreen(&#8230;&#8203;) / unsubscribeForTitleScreen(&#8230;&#8203;)</code></a></li>
477
- <li><a href="#subscribeforgameoverscreen-unsubscribeforgameoverscreen">4.27. <code>subscribeForGameOverScreen(&#8230;&#8203;) / unsubscribeForGameOverScreen(&#8230;&#8203;)</code></a></li>
478
- <li><a href="#subscribeforplayingscreen-unsubscribeforplayingscreen">4.28. <code>subscribeForPlayingScreen(&#8230;&#8203;) / unsubscribeForPlayingScreen(&#8230;&#8203;)</code></a></li>
479
- <li><a href="#subscribeforpausedscreen-unsubscribeforpausedscreen">4.29. <code>subscribeForPausedScreen(&#8230;&#8203;) / unsubscribeForPausedScreen(&#8230;&#8203;)</code></a></li>
480
- <li><a href="#getdebugdata-recordstring-string-number-boolean">4.30. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></li>
451
+ <li><a href="#lifecycle-management">4.1. Lifecycle Management</a>
452
+ <ul class="sectlevel3">
453
+ <li><a href="#turnon-void">4.1.1. <code>turnOn(): void</code></a></li>
454
+ <li><a href="#turnoff-void">4.1.2. <code>turnOff(): void</code></a></li>
455
+ <li><a href="#startgame-void">4.1.3. <code>startGame(): void</code></a></li>
456
+ <li><a href="#exitgame-void">4.1.4. <code>exitGame(): void</code></a></li>
457
+ <li><a href="#triggergameover-void">4.1.5. <code>triggerGameOver(): void</code></a></li>
458
+ <li><a href="#resetgame-void">4.1.6. <code>resetGame(): void</code></a></li>
459
+ <li><a href="#resetgameover-void">4.1.7. <code>resetGameOver(): void</code></a></li>
460
+ </ul>
461
+ </li>
462
+ <li><a href="#runtime-status">4.2. Runtime Status</a>
463
+ <ul class="sectlevel3">
464
+ <li><a href="#ison-boolean">4.2.1. <code>isOn(): boolean</code></a></li>
465
+ <li><a href="#isoff-boolean">4.2.2. <code>isOff(): boolean</code></a></li>
466
+ <li><a href="#isstarted-boolean">4.2.3. <code>isStarted(): boolean</code></a></li>
467
+ <li><a href="#isplaying-boolean">4.2.4. <code>isPlaying(): boolean</code></a></li>
468
+ <li><a href="#ispaused-boolean">4.2.5. <code>isPaused(): boolean</code></a></li>
469
+ <li><a href="#isgameover-boolean">4.2.6. <code>isGameOver(): boolean</code></a></li>
470
+ </ul>
471
+ </li>
472
+ <li><a href="#user-preferences">4.3. User Preferences</a>
473
+ <ul class="sectlevel3">
474
+ <li><a href="#iscolorenabled-boolean">4.3.1. <code>isColorEnabled(): boolean</code></a></li>
475
+ <li><a href="#setcolorenabledvalue-boolean-void">4.3.2. <code>setColorEnabled(value: boolean): void</code></a></li>
476
+ <li><a href="#togglecolorenabled-void">4.3.3. <code>toggleColorEnabled(): void</code></a></li>
477
+ <li><a href="#istrackpadenabled-boolean">4.3.4. <code>isTrackpadEnabled(): boolean</code></a></li>
478
+ <li><a href="#settrackpadenabledvalue-boolean-void">4.3.5. <code>setTrackpadEnabled(value: boolean): void</code></a></li>
479
+ <li><a href="#toggletrackpadenabled-void">4.3.6. <code>toggleTrackpadEnabled(): void</code></a></li>
480
+ <li><a href="#ismuted-boolean">4.3.7. <code>isMuted(): boolean</code></a></li>
481
+ <li><a href="#setmutedvalue-boolean-void">4.3.8. <code>setMuted(value: boolean): void</code></a></li>
482
+ <li><a href="#togglemuted-void">4.3.9. <code>toggleMuted(): void</code></a></li>
483
+ </ul>
484
+ </li>
485
+ <li><a href="#subscriptions">4.4. Subscriptions</a>
486
+ <ul class="sectlevel3">
487
+ <li><a href="#subscribeproperty-stateproperty-callback-value-boolean-number-void-void">4.4.1. <code>subscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></li>
488
+ <li><a href="#unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void">4.4.2. <code>unsubscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></li>
489
+ <li><a href="#subscribefortitlescreen-unsubscribefortitlescreen">4.4.3. <code>subscribeForTitleScreen(&#8230;&#8203;) / unsubscribeForTitleScreen(&#8230;&#8203;)</code></a></li>
490
+ <li><a href="#subscribeforgameoverscreen-unsubscribeforgameoverscreen">4.4.4. <code>subscribeForGameOverScreen(&#8230;&#8203;) / unsubscribeForGameOverScreen(&#8230;&#8203;)</code></a></li>
491
+ <li><a href="#subscribeforplayingscreen-unsubscribeforplayingscreen">4.4.5. <code>subscribeForPlayingScreen(&#8230;&#8203;) / unsubscribeForPlayingScreen(&#8230;&#8203;)</code></a></li>
492
+ <li><a href="#subscribeforpausedscreen-unsubscribeforpausedscreen">4.4.6. <code>subscribeForPausedScreen(&#8230;&#8203;) / unsubscribeForPausedScreen(&#8230;&#8203;)</code></a></li>
493
+ </ul>
494
+ </li>
495
+ <li><a href="#utilities">4.5. Utilities</a>
496
+ <ul class="sectlevel3">
497
+ <li><a href="#notifyproperty-stateproperty-void">4.5.1. <code>notify(property: StateProperty): void</code></a></li>
498
+ <li><a href="#syncstatestate-state-void">4.5.2. <code>syncState(state: State): void</code></a></li>
499
+ <li><a href="#getdebugdata-recordstring-string-number-boolean">4.5.3. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></li>
500
+ </ul>
501
+ </li>
481
502
  </ul>
482
503
  </li>
483
504
  </ul>
@@ -522,202 +543,193 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
522
543
  <h2 id="api-reference"><a class="link" href="#api-reference">4. API Reference</a></h2>
523
544
  <div class="sectionbody">
524
545
  <div class="sect2">
525
- <h3 id="ison-boolean"><a class="link" href="#ison-boolean">4.1. <code>isOn(): boolean</code></a></h3>
526
- <div class="paragraph">
527
- <p>Checks if the game system is powered up.</p>
528
- </div>
529
- <div class="paragraph">
530
- <p><strong>Returns</strong></p>
531
- </div>
546
+ <h3 id="lifecycle-management"><a class="link" href="#lifecycle-management">4.1. Lifecycle Management</a></h3>
532
547
  <div class="paragraph">
533
- <p><code>boolean</code> - <code>true</code> if system is on.</p>
534
- </div>
535
- <hr>
548
+ <p>Methods for controlling the coarse transitions of the physical engine system and gameplay boundaries.</p>
536
549
  </div>
537
- <div class="sect2">
538
- <h3 id="isoff-boolean"><a class="link" href="#isoff-boolean">4.2. <code>isOff(): boolean</code></a></h3>
550
+ <div class="sect3">
551
+ <h4 id="turnon-void"><a class="link" href="#turnon-void">4.1.1. <code>turnOn(): void</code></a></h4>
539
552
  <div class="paragraph">
540
- <p>Checks if the game system is powered down.</p>
553
+ <p>Powers on the game system.</p>
541
554
  </div>
542
555
  <div class="paragraph">
543
- <p><strong>Returns</strong></p>
556
+ <p><strong>Behavior</strong></p>
544
557
  </div>
545
558
  <div class="paragraph">
546
- <p><code>boolean</code> - <code>true</code> if system is off.</p>
559
+ <p>Sets the <code>on</code> property to true and ensures <code>start</code>, <code>playing</code>, and <code>gameOver</code> are initialized to false.</p>
547
560
  </div>
548
561
  <hr>
549
562
  </div>
550
- <div class="sect2">
551
- <h3 id="isstarted-boolean"><a class="link" href="#isstarted-boolean">4.3. <code>isStarted(): boolean</code></a></h3>
563
+ <div class="sect3">
564
+ <h4 id="turnoff-void"><a class="link" href="#turnoff-void">4.1.2. <code>turnOff(): void</code></a></h4>
552
565
  <div class="paragraph">
553
- <p>Checks if a game session is active (passed the title screen).</p>
566
+ <p>Powers off the game system.</p>
554
567
  </div>
555
568
  <div class="paragraph">
556
- <p><strong>Returns</strong></p>
569
+ <p><strong>Behavior</strong></p>
557
570
  </div>
558
571
  <div class="paragraph">
559
- <p><code>boolean</code> - <code>true</code> if the game has started.</p>
572
+ <p>Sets the <code>on</code> property to false and wipes transient state.</p>
560
573
  </div>
561
574
  <hr>
562
575
  </div>
563
- <div class="sect2">
564
- <h3 id="isplaying-boolean"><a class="link" href="#isplaying-boolean">4.4. <code>isPlaying(): boolean</code></a></h3>
576
+ <div class="sect3">
577
+ <h4 id="startgame-void"><a class="link" href="#startgame-void">4.1.3. <code>startGame(): void</code></a></h4>
565
578
  <div class="paragraph">
566
- <p>Checks if the game loop is actively updating logic.</p>
579
+ <p>Initiates gameplay from the title screen.</p>
567
580
  </div>
568
581
  <div class="paragraph">
569
- <p><strong>Returns</strong></p>
582
+ <p><strong>Behavior</strong></p>
570
583
  </div>
571
584
  <div class="paragraph">
572
- <p><code>boolean</code> - <code>true</code> if gameplay is active and not paused.</p>
585
+ <p>Sets <code>start</code> and <code>playing</code> to true. This method only has effect if the system is already <code>on</code>.</p>
573
586
  </div>
574
587
  <hr>
575
588
  </div>
576
- <div class="sect2">
577
- <h3 id="ispaused-boolean"><a class="link" href="#ispaused-boolean">4.5. <code>isPaused(): boolean</code></a></h3>
589
+ <div class="sect3">
590
+ <h4 id="exitgame-void"><a class="link" href="#exitgame-void">4.1.4. <code>exitGame(): void</code></a></h4>
578
591
  <div class="paragraph">
579
- <p>Checks if the game is currently paused.</p>
592
+ <p>Ends the session and returns to the title screen.</p>
580
593
  </div>
581
594
  <div class="paragraph">
582
- <p><strong>Returns</strong></p>
595
+ <p><strong>Behavior</strong></p>
583
596
  </div>
584
597
  <div class="paragraph">
585
- <p><code>boolean</code> - <code>true</code> if the game is started but halted.</p>
598
+ <p>Resets <code>start</code>, <code>playing</code>, and <code>gameOver</code> to false.</p>
586
599
  </div>
587
600
  <hr>
588
601
  </div>
589
- <div class="sect2">
590
- <h3 id="isgameover-boolean"><a class="link" href="#isgameover-boolean">4.6. <code>isGameOver(): boolean</code></a></h3>
602
+ <div class="sect3">
603
+ <h4 id="triggergameover-void"><a class="link" href="#triggergameover-void">4.1.5. <code>triggerGameOver(): void</code></a></h4>
591
604
  <div class="paragraph">
592
- <p>Checks if the current session has ended in a Game Over.</p>
605
+ <p>Forces the game into a Game Over state.</p>
593
606
  </div>
594
607
  <div class="paragraph">
595
- <p><strong>Returns</strong></p>
608
+ <p><strong>Behavior</strong></p>
596
609
  </div>
597
610
  <div class="paragraph">
598
- <p><code>boolean</code> - <code>true</code> if player has lost.</p>
611
+ <p>Sets <code>playing</code> to false and <code>gameOver</code> to true.</p>
599
612
  </div>
600
613
  <hr>
601
614
  </div>
602
- <div class="sect2">
603
- <h3 id="turnon-void"><a class="link" href="#turnon-void">4.7. <code>turnOn(): void</code></a></h3>
615
+ <div class="sect3">
616
+ <h4 id="resetgame-void"><a class="link" href="#resetgame-void">4.1.6. <code>resetGame(): void</code></a></h4>
604
617
  <div class="paragraph">
605
- <p>Powers on the game system.</p>
618
+ <p>Prepares the state for a new round (hard restart).</p>
606
619
  </div>
607
620
  <div class="paragraph">
608
621
  <p><strong>Behavior</strong></p>
609
622
  </div>
610
623
  <div class="paragraph">
611
- <p>Sets the <code>on</code> property to true and ensures <code>start</code>, <code>playing</code>, and <code>gameOver</code> are initialized to false.</p>
624
+ <p>Clears the <code>gameOver</code> flag and resumes <code>playing</code> status. Unlike <code>resetGameOver</code>, this is intended for a complete session reset from any state.</p>
612
625
  </div>
613
626
  <hr>
614
627
  </div>
615
- <div class="sect2">
616
- <h3 id="turnoff-void"><a class="link" href="#turnoff-void">4.8. <code>turnOff(): void</code></a></h3>
628
+ <div class="sect3">
629
+ <h4 id="resetgameover-void"><a class="link" href="#resetgameover-void">4.1.7. <code>resetGameOver(): void</code></a></h4>
617
630
  <div class="paragraph">
618
- <p>Powers off the game system.</p>
631
+ <p>Resets the state specifically after a Game Over to allow immediate restart.</p>
619
632
  </div>
620
633
  <div class="paragraph">
621
634
  <p><strong>Behavior</strong></p>
622
635
  </div>
623
636
  <div class="paragraph">
624
- <p>Sets the <code>on</code> property to false and wipes transient state.</p>
637
+ <p>Sets <code>gameOver</code> to false and <code>playing</code> to true. This is the recommended way to handle "Try Again" scenarios.</p>
625
638
  </div>
626
639
  <hr>
627
640
  </div>
628
- <div class="sect2">
629
- <h3 id="startgame-void"><a class="link" href="#startgame-void">4.9. <code>startGame(): void</code></a></h3>
630
- <div class="paragraph">
631
- <p>Initiates gameplay from the title screen.</p>
632
641
  </div>
642
+ <div class="sect2">
643
+ <h3 id="runtime-status"><a class="link" href="#runtime-status">4.2. Runtime Status</a></h3>
633
644
  <div class="paragraph">
634
- <p><strong>Behavior</strong></p>
645
+ <p>Logical predicates for checking the current active lifecycle phase of the engine.</p>
635
646
  </div>
647
+ <div class="sect3">
648
+ <h4 id="ison-boolean"><a class="link" href="#ison-boolean">4.2.1. <code>isOn(): boolean</code></a></h4>
636
649
  <div class="paragraph">
637
- <p>Sets <code>start</code> and <code>playing</code> to true. This method only has effect if the system is already <code>on</code>.</p>
638
- </div>
639
- <hr>
640
- </div>
641
- <div class="sect2">
642
- <h3 id="exitgame-void"><a class="link" href="#exitgame-void">4.10. <code>exitGame(): void</code></a></h3>
643
- <div class="paragraph">
644
- <p>Ends the session and returns to the title screen.</p>
650
+ <p>Checks if the game system is powered up.</p>
645
651
  </div>
646
652
  <div class="paragraph">
647
- <p><strong>Behavior</strong></p>
653
+ <p><strong>Returns</strong></p>
648
654
  </div>
649
655
  <div class="paragraph">
650
- <p>Resets <code>start</code>, <code>playing</code>, and <code>gameOver</code> to false.</p>
656
+ <p><code>boolean</code> - <code>true</code> if system is on.</p>
651
657
  </div>
652
658
  <hr>
653
659
  </div>
654
- <div class="sect2">
655
- <h3 id="pause-void"><a class="link" href="#pause-void">4.11. <code>pause(): void</code></a></h3>
660
+ <div class="sect3">
661
+ <h4 id="isoff-boolean"><a class="link" href="#isoff-boolean">4.2.2. <code>isOff(): boolean</code></a></h4>
656
662
  <div class="paragraph">
657
- <p>Halts gameplay logic.</p>
663
+ <p>Checks if the game system is powered down.</p>
658
664
  </div>
659
665
  <div class="paragraph">
660
- <p><strong>Behavior</strong></p>
666
+ <p><strong>Returns</strong></p>
661
667
  </div>
662
668
  <div class="paragraph">
663
- <p>Sets <code>playing</code> to false. Only works if the game is already started.</p>
669
+ <p><code>boolean</code> - <code>true</code> if system is off.</p>
664
670
  </div>
665
671
  <hr>
666
672
  </div>
667
- <div class="sect2">
668
- <h3 id="resume-void"><a class="link" href="#resume-void">4.12. <code>resume(): void</code></a></h3>
673
+ <div class="sect3">
674
+ <h4 id="isstarted-boolean"><a class="link" href="#isstarted-boolean">4.2.3. <code>isStarted(): boolean</code></a></h4>
669
675
  <div class="paragraph">
670
- <p>Restarts gameplay logic from a paused state.</p>
676
+ <p>Checks if a game session is active (passed the title screen).</p>
671
677
  </div>
672
678
  <div class="paragraph">
673
- <p><strong>Behavior</strong></p>
679
+ <p><strong>Returns</strong></p>
674
680
  </div>
675
681
  <div class="paragraph">
676
- <p>Sets <code>playing</code> to true.</p>
682
+ <p><code>boolean</code> - <code>true</code> if the game has started.</p>
677
683
  </div>
678
684
  <hr>
679
685
  </div>
680
- <div class="sect2">
681
- <h3 id="triggergameover-void"><a class="link" href="#triggergameover-void">4.13. <code>triggerGameOver(): void</code></a></h3>
686
+ <div class="sect3">
687
+ <h4 id="isplaying-boolean"><a class="link" href="#isplaying-boolean">4.2.4. <code>isPlaying(): boolean</code></a></h4>
682
688
  <div class="paragraph">
683
- <p>Forces the game into a Game Over state.</p>
689
+ <p>Checks if the game loop is actively updating logic.</p>
684
690
  </div>
685
691
  <div class="paragraph">
686
- <p><strong>Behavior</strong></p>
692
+ <p><strong>Returns</strong></p>
687
693
  </div>
688
694
  <div class="paragraph">
689
- <p>Sets <code>playing</code> to false and <code>gameOver</code> to true.</p>
695
+ <p><code>boolean</code> - <code>true</code> if gameplay is active and not paused.</p>
690
696
  </div>
691
697
  <hr>
692
698
  </div>
693
- <div class="sect2">
694
- <h3 id="resetgame-void"><a class="link" href="#resetgame-void">4.14. <code>resetGame(): void</code></a></h3>
699
+ <div class="sect3">
700
+ <h4 id="ispaused-boolean"><a class="link" href="#ispaused-boolean">4.2.5. <code>isPaused(): boolean</code></a></h4>
695
701
  <div class="paragraph">
696
- <p>Prepares the state for a new round (hard restart).</p>
702
+ <p>Checks if the game is currently paused.</p>
697
703
  </div>
698
704
  <div class="paragraph">
699
- <p><strong>Behavior</strong></p>
705
+ <p><strong>Returns</strong></p>
700
706
  </div>
701
707
  <div class="paragraph">
702
- <p>Clears the <code>gameOver</code> flag and resumes <code>playing</code> status. Unlike <code>resetGameOver</code>, this is intended for a complete session reset from any state.</p>
708
+ <p><code>boolean</code> - <code>true</code> if the game is started but halted.</p>
703
709
  </div>
704
710
  <hr>
705
711
  </div>
706
- <div class="sect2">
707
- <h3 id="resetgameover-void"><a class="link" href="#resetgameover-void">4.15. <code>resetGameOver(): void</code></a></h3>
712
+ <div class="sect3">
713
+ <h4 id="isgameover-boolean"><a class="link" href="#isgameover-boolean">4.2.6. <code>isGameOver(): boolean</code></a></h4>
708
714
  <div class="paragraph">
709
- <p>Resets the state specifically after a Game Over to allow immediate restart.</p>
715
+ <p>Checks if the current session has ended in a Game Over.</p>
710
716
  </div>
711
717
  <div class="paragraph">
712
- <p><strong>Behavior</strong></p>
718
+ <p><strong>Returns</strong></p>
713
719
  </div>
714
720
  <div class="paragraph">
715
- <p>Sets <code>gameOver</code> to false and <code>playing</code> to true. This is the recommended way to handle "Try Again" scenarios.</p>
721
+ <p><code>boolean</code> - <code>true</code> if player has lost.</p>
716
722
  </div>
717
723
  <hr>
718
724
  </div>
725
+ </div>
719
726
  <div class="sect2">
720
- <h3 id="iscolorenabled-boolean"><a class="link" href="#iscolorenabled-boolean">4.16. <code>isColorEnabled(): boolean</code></a></h3>
727
+ <h3 id="user-preferences"><a class="link" href="#user-preferences">4.3. User Preferences</a></h3>
728
+ <div class="paragraph">
729
+ <p>Methods for managing persistent environment flags such as audio, color themes, and input mechanics.</p>
730
+ </div>
731
+ <div class="sect3">
732
+ <h4 id="iscolorenabled-boolean"><a class="link" href="#iscolorenabled-boolean">4.3.1. <code>isColorEnabled(): boolean</code></a></h4>
721
733
  <div class="paragraph">
722
734
  <p>Checks if theme color mode is active.</p>
723
735
  </div>
@@ -729,8 +741,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
729
741
  </div>
730
742
  <hr>
731
743
  </div>
732
- <div class="sect2">
733
- <h3 id="setcolorenabledvalue-boolean-void"><a class="link" href="#setcolorenabledvalue-boolean-void">4.17. <code>setColorEnabled(value: boolean): void</code></a></h3>
744
+ <div class="sect3">
745
+ <h4 id="setcolorenabledvalue-boolean-void"><a class="link" href="#setcolorenabledvalue-boolean-void">4.3.2. <code>setColorEnabled(value: boolean): void</code></a></h4>
734
746
  <div class="paragraph">
735
747
  <p>Sets the color mode preference.</p>
736
748
  </div>
@@ -764,30 +776,30 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
764
776
  </div>
765
777
  <hr>
766
778
  </div>
767
- <div class="sect2">
768
- <h3 id="togglecolorenabled-void"><a class="link" href="#togglecolorenabled-void">4.18. <code>toggleColorEnabled(): void</code></a></h3>
779
+ <div class="sect3">
780
+ <h4 id="togglecolorenabled-void"><a class="link" href="#togglecolorenabled-void">4.3.3. <code>toggleColorEnabled(): void</code></a></h4>
769
781
  <div class="paragraph">
770
782
  <p>Toggles the current color mode.</p>
771
783
  </div>
772
784
  <hr>
773
785
  </div>
774
- <div class="sect2">
775
- <h3 id="ismuted-boolean"><a class="link" href="#ismuted-boolean">4.19. <code>isMuted(): boolean</code></a></h3>
786
+ <div class="sect3">
787
+ <h4 id="istrackpadenabled-boolean"><a class="link" href="#istrackpadenabled-boolean">4.3.4. <code>isTrackpadEnabled(): boolean</code></a></h4>
776
788
  <div class="paragraph">
777
- <p>Checks if master audio is muted.</p>
789
+ <p>Checks if the trackpad input mode is active.</p>
778
790
  </div>
779
791
  <div class="paragraph">
780
792
  <p><strong>Returns</strong></p>
781
793
  </div>
782
794
  <div class="paragraph">
783
- <p><code>boolean</code> - <code>true</code> if sound is disabled.</p>
795
+ <p><code>boolean</code> - <code>true</code> if trackpad is enabled.</p>
784
796
  </div>
785
797
  <hr>
786
798
  </div>
787
- <div class="sect2">
788
- <h3 id="setmutedvalue-boolean-void"><a class="link" href="#setmutedvalue-boolean-void">4.20. <code>setMuted(value: boolean): void</code></a></h3>
799
+ <div class="sect3">
800
+ <h4 id="settrackpadenabledvalue-boolean-void"><a class="link" href="#settrackpadenabledvalue-boolean-void">4.3.5. <code>setTrackpadEnabled(value: boolean): void</code></a></h4>
789
801
  <div class="paragraph">
790
- <p>Sets the master mute status.</p>
802
+ <p>Sets the trackpad input mode preference.</p>
791
803
  </div>
792
804
  <div class="paragraph">
793
805
  <p><strong>Parameters</strong></p>
@@ -807,7 +819,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
807
819
  <tr>
808
820
  <td class="tableblock halign-left valign-top"><p class="tableblock"><code>value</code></p></td>
809
821
  <td class="tableblock halign-left valign-top"><p class="tableblock"><code>boolean</code></p></td>
810
- <td class="tableblock halign-left valign-top"><p class="tableblock">New mute status.</p></td>
822
+ <td class="tableblock halign-left valign-top"><p class="tableblock">New trackpad status.</p></td>
811
823
  </tr>
812
824
  </tbody>
813
825
  </table>
@@ -815,36 +827,34 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
815
827
  <p><strong>Behavior</strong></p>
816
828
  </div>
817
829
  <div class="paragraph">
818
- <p>Updates the property and persists it to <code>LocalStorage</code>.</p>
830
+ <p>Updates the property and automatically persists the value to <code>LocalStorage</code>.</p>
819
831
  </div>
820
832
  <hr>
821
833
  </div>
822
- <div class="sect2">
823
- <h3 id="togglemuted-void"><a class="link" href="#togglemuted-void">4.21. <code>toggleMuted(): void</code></a></h3>
834
+ <div class="sect3">
835
+ <h4 id="toggletrackpadenabled-void"><a class="link" href="#toggletrackpadenabled-void">4.3.6. <code>toggleTrackpadEnabled(): void</code></a></h4>
824
836
  <div class="paragraph">
825
- <p>Toggles the master mute status.</p>
837
+ <p>Toggles the current trackpad setting.</p>
826
838
  </div>
827
839
  <hr>
828
- <hr>
829
840
  </div>
830
- <div class="sect2">
831
- <h3 id="notifyproperty-stateproperty-void"><a class="link" href="#notifyproperty-stateproperty-void">4.22. <code>notify(property: StateProperty): void</code></a></h3>
841
+ <div class="sect3">
842
+ <h4 id="ismuted-boolean"><a class="link" href="#ismuted-boolean">4.3.7. <code>isMuted(): boolean</code></a></h4>
832
843
  <div class="paragraph">
833
- <p>Manually triggers notifications for a state property.</p>
844
+ <p>Checks if master audio is muted.</p>
834
845
  </div>
835
- <div class="admonitionblock important">
836
- <table>
837
- <tr>
838
- <td class="icon">
839
- <i class="fa icon-important" title="Important"></i>
840
- </td>
841
- <td class="content">
842
846
  <div class="paragraph">
843
- <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>
847
+ <p><strong>Returns</strong></p>
844
848
  </div>
845
- </td>
846
- </tr>
847
- </table>
849
+ <div class="paragraph">
850
+ <p><code>boolean</code> - <code>true</code> if sound is disabled.</p>
851
+ </div>
852
+ <hr>
853
+ </div>
854
+ <div class="sect3">
855
+ <h4 id="setmutedvalue-boolean-void"><a class="link" href="#setmutedvalue-boolean-void">4.3.8. <code>setMuted(value: boolean): void</code></a></h4>
856
+ <div class="paragraph">
857
+ <p>Sets the master mute status.</p>
848
858
  </div>
849
859
  <div class="paragraph">
850
860
  <p><strong>Parameters</strong></p>
@@ -862,23 +872,35 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
862
872
  <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
863
873
  </tr>
864
874
  <tr>
865
- <td class="tableblock halign-left valign-top"><p class="tableblock"><code>property</code></p></td>
866
- <td class="tableblock halign-left valign-top"><p class="tableblock"><code><a href="../enums/StateProperty.html">StateProperty</a></code></p></td>
867
- <td class="tableblock halign-left valign-top"><p class="tableblock">The property to trigger notifications for.</p></td>
875
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>value</code></p></td>
876
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>boolean</code></p></td>
877
+ <td class="tableblock halign-left valign-top"><p class="tableblock">New mute status.</p></td>
868
878
  </tr>
869
879
  </tbody>
870
880
  </table>
881
+ <div class="paragraph">
882
+ <p><strong>Behavior</strong></p>
883
+ </div>
884
+ <div class="paragraph">
885
+ <p>Updates the property and persists it to <code>LocalStorage</code>.</p>
886
+ </div>
871
887
  <hr>
872
888
  </div>
873
- <div class="sect2">
874
- <h3 id="syncstatestate-state-void"><a class="link" href="#syncstatestate-state-void">4.23. <code>syncState(state: State): void</code></a></h3>
889
+ <div class="sect3">
890
+ <h4 id="togglemuted-void"><a class="link" href="#togglemuted-void">4.3.9. <code>toggleMuted(): void</code></a></h4>
875
891
  <div class="paragraph">
876
- <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>
892
+ <p>Toggles the master mute status.</p>
877
893
  </div>
878
894
  <hr>
879
895
  </div>
896
+ </div>
880
897
  <div class="sect2">
881
- <h3 id="subscribeproperty-stateproperty-callback-value-boolean-number-void-void"><a class="link" href="#subscribeproperty-stateproperty-callback-value-boolean-number-void-void">4.24. <code>subscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></h3>
898
+ <h3 id="subscriptions"><a class="link" href="#subscriptions">4.4. Subscriptions</a></h3>
899
+ <div class="paragraph">
900
+ <p>Reactivity mechanisms for observing property changes through the <code><a href="EventEmitter.html">EventEmitter</a></code>.</p>
901
+ </div>
902
+ <div class="sect3">
903
+ <h4 id="subscribeproperty-stateproperty-callback-value-boolean-number-void-void"><a class="link" href="#subscribeproperty-stateproperty-callback-value-boolean-number-void-void">4.4.1. <code>subscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></h4>
882
904
  <div class="paragraph">
883
905
  <p>Registers a listener for state changes.</p>
884
906
  </div>
@@ -923,8 +945,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
923
945
  </div>
924
946
  <hr>
925
947
  </div>
926
- <div class="sect2">
927
- <h3 id="unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void"><a class="link" href="#unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void">4.25. <code>unsubscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></h3>
948
+ <div class="sect3">
949
+ <h4 id="unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void"><a class="link" href="#unsubscribeproperty-stateproperty-callback-value-boolean-number-void-void">4.4.2. <code>unsubscribe(property: StateProperty, callback: (value: boolean | number) &#8658; void): void</code></a></h4>
928
950
  <div class="paragraph">
929
951
  <p>Removes a state change listener.</p>
930
952
  </div>
@@ -957,8 +979,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
957
979
  </table>
958
980
  <hr>
959
981
  </div>
960
- <div class="sect2">
961
- <h3 id="subscribefortitlescreen-unsubscribefortitlescreen"><a class="link" href="#subscribefortitlescreen-unsubscribefortitlescreen">4.26. <code>subscribeForTitleScreen(&#8230;&#8203;) / unsubscribeForTitleScreen(&#8230;&#8203;)</code></a></h3>
982
+ <div class="sect3">
983
+ <h4 id="subscribefortitlescreen-unsubscribefortitlescreen"><a class="link" href="#subscribefortitlescreen-unsubscribefortitlescreen">4.4.3. <code>subscribeForTitleScreen(&#8230;&#8203;) / unsubscribeForTitleScreen(&#8230;&#8203;)</code></a></h4>
962
984
  <div class="paragraph">
963
985
  <p>Specialized methods to listen for state changes <strong>ONLY</strong> while the engine is in the Title Screen state.</p>
964
986
  </div>
@@ -978,22 +1000,22 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
978
1000
  </div>
979
1001
  <hr>
980
1002
  </div>
981
- <div class="sect2">
982
- <h3 id="subscribeforgameoverscreen-unsubscribeforgameoverscreen"><a class="link" href="#subscribeforgameoverscreen-unsubscribeforgameoverscreen">4.27. <code>subscribeForGameOverScreen(&#8230;&#8203;) / unsubscribeForGameOverScreen(&#8230;&#8203;)</code></a></h3>
1003
+ <div class="sect3">
1004
+ <h4 id="subscribeforgameoverscreen-unsubscribeforgameoverscreen"><a class="link" href="#subscribeforgameoverscreen-unsubscribeforgameoverscreen">4.4.4. <code>subscribeForGameOverScreen(&#8230;&#8203;) / unsubscribeForGameOverScreen(&#8230;&#8203;)</code></a></h4>
983
1005
  <div class="paragraph">
984
1006
  <p>Specialized methods to listen for state changes <strong>ONLY</strong> while the engine is in the Game Over state.</p>
985
1007
  </div>
986
1008
  <hr>
987
1009
  </div>
988
- <div class="sect2">
989
- <h3 id="subscribeforplayingscreen-unsubscribeforplayingscreen"><a class="link" href="#subscribeforplayingscreen-unsubscribeforplayingscreen">4.28. <code>subscribeForPlayingScreen(&#8230;&#8203;) / unsubscribeForPlayingScreen(&#8230;&#8203;)</code></a></h3>
1010
+ <div class="sect3">
1011
+ <h4 id="subscribeforplayingscreen-unsubscribeforplayingscreen"><a class="link" href="#subscribeforplayingscreen-unsubscribeforplayingscreen">4.4.5. <code>subscribeForPlayingScreen(&#8230;&#8203;) / unsubscribeForPlayingScreen(&#8230;&#8203;)</code></a></h4>
990
1012
  <div class="paragraph">
991
1013
  <p>Specialized methods to listen for state changes <strong>ONLY</strong> while the engine is in the active Gameplay state.</p>
992
1014
  </div>
993
1015
  <hr>
994
1016
  </div>
995
- <div class="sect2">
996
- <h3 id="subscribeforpausedscreen-unsubscribeforpausedscreen"><a class="link" href="#subscribeforpausedscreen-unsubscribeforpausedscreen">4.29. <code>subscribeForPausedScreen(&#8230;&#8203;) / unsubscribeForPausedScreen(&#8230;&#8203;)</code></a></h3>
1017
+ <div class="sect3">
1018
+ <h4 id="subscribeforpausedscreen-unsubscribeforpausedscreen"><a class="link" href="#subscribeforpausedscreen-unsubscribeforpausedscreen">4.4.6. <code>subscribeForPausedScreen(&#8230;&#8203;) / unsubscribeForPausedScreen(&#8230;&#8203;)</code></a></h4>
997
1019
  <div class="paragraph">
998
1020
  <p>Specialized methods to listen for state changes <strong>ONLY</strong> while the engine is in the Paused state.</p>
999
1021
  </div>
@@ -1013,8 +1035,78 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
1013
1035
  </div>
1014
1036
  <hr>
1015
1037
  </div>
1038
+ </div>
1016
1039
  <div class="sect2">
1017
- <h3 id="getdebugdata-recordstring-string-number-boolean"><a class="link" href="#getdebugdata-recordstring-string-number-boolean">4.30. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></h3>
1040
+ <h3 id="utilities"><a class="link" href="#utilities">4.5. Utilities</a></h3>
1041
+ <div class="paragraph">
1042
+ <p>Internal helpers for system synchronization and debugging.</p>
1043
+ </div>
1044
+ <div class="sect3">
1045
+ <h4 id="notifyproperty-stateproperty-void"><a class="link" href="#notifyproperty-stateproperty-void">4.5.1. <code>notify(property: StateProperty): void</code></a></h4>
1046
+ <div class="paragraph">
1047
+ <p>Manually triggers notifications for a state property.</p>
1048
+ </div>
1049
+ <div class="admonitionblock important">
1050
+ <table>
1051
+ <tr>
1052
+ <td class="icon">
1053
+ <i class="fa icon-important" title="Important"></i>
1054
+ </td>
1055
+ <td class="content">
1056
+ <div class="paragraph">
1057
+ <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>
1058
+ </div>
1059
+ </td>
1060
+ </tr>
1061
+ </table>
1062
+ </div>
1063
+ <div class="paragraph">
1064
+ <p><strong>Parameters</strong></p>
1065
+ </div>
1066
+ <table class="tableblock frame-all grid-all stretch">
1067
+ <colgroup>
1068
+ <col style="width: 20%;">
1069
+ <col style="width: 20%;">
1070
+ <col style="width: 60%;">
1071
+ </colgroup>
1072
+ <tbody>
1073
+ <tr>
1074
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Name</p></td>
1075
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Type</p></td>
1076
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
1077
+ </tr>
1078
+ <tr>
1079
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>property</code></p></td>
1080
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code><a href="../enums/StateProperty.html">StateProperty</a></code></p></td>
1081
+ <td class="tableblock halign-left valign-top"><p class="tableblock">The property to trigger notifications for.</p></td>
1082
+ </tr>
1083
+ </tbody>
1084
+ </table>
1085
+ <hr>
1086
+ </div>
1087
+ <div class="sect3">
1088
+ <h4 id="syncstatestate-state-void"><a class="link" href="#syncstatestate-state-void">4.5.2. <code>syncState(state: State): void</code></a></h4>
1089
+ <div class="paragraph">
1090
+ <p>Syncs the internal state with another <code><a href="#">GameState</a></code> instance.</p>
1091
+ </div>
1092
+ <div class="admonitionblock note">
1093
+ <table>
1094
+ <tr>
1095
+ <td class="icon">
1096
+ <i class="fa icon-note" title="Note"></i>
1097
+ </td>
1098
+ <td class="content">
1099
+ <div class="paragraph">
1100
+ <p>This is primarily used during engine initialization to link the persistent store.</p>
1101
+ </div>
1102
+ </td>
1103
+ </tr>
1104
+ </table>
1105
+ </div>
1106
+ <hr>
1107
+ </div>
1108
+ <div class="sect3">
1109
+ <h4 id="getdebugdata-recordstring-string-number-boolean"><a class="link" href="#getdebugdata-recordstring-string-number-boolean">4.5.3. <code>getDebugData(): Record&lt;string, string | number | boolean&gt;</code></a></h4>
1018
1110
  <div class="paragraph">
1019
1111
  <p>Returns metadata for the real-time debugger.</p>
1020
1112
  </div>
@@ -1022,6 +1114,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
1022
1114
  </div>
1023
1115
  </div>
1024
1116
  </div>
1117
+ </div>
1025
1118
  <div id="footer">
1026
1119
  <div id="footer-text">
1027
1120
  </div>