feat: Scheduler Implementation for Pause and Resume Mechanic (FM-806)

[janfb-codev]

Changes

• Implemented Scheduler for the pause mechanic (FM-807)
• Used Scheduler for Gameplay (FM-808)
• Fixed issue with the timer rotation not resuming after paused before timer (FM-817)

How to test

• Pause and Resume at different stages of the game
• Pause when the stones are just flying thru
• Pause when the timer starts
• Pause after completing a puzzle
• Pause in Minigame via switching to different tab since pause button is not clickable at Minigame

Ref: FM-806

Summary by CodeRabbit

• New Features

  • Enhanced pause/resume functionality for game audio and animations with improved state management.
  • Improved animation timing synchronization across game elements.

• Bug Fixes

  • Fixed event subscription cleanup to prevent memory leaks.
  • Improved game state consistency during pause and resume.

• Chores

  • Version bumped to v1.3.2.
  • Internal game architecture improvements for better maintainability.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key(s) in object: 'version', 'enabled', 'branches', 'checks', 'ignore', 'notifications'

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

📝 Walkthrough

Walkthrough

This PR performs a major architectural refactoring of the gameplay system, introducing a scheduler service, manager-based orchestration, and transitioning from EventManager inheritance to a gameStateService pub-sub model. It adds frame-based animation timing, new pause/resume audio controls, and restructures GameplayScene with dedicated controllers for input, UI, flow, and monsters.

Changes

Cohort / File(s)	Summary
Version & Public Assets public/index.html	Bumps version from v1.3.1 to v1.3.2 in version-info elements and fixes trailing newline.
New Scheduler Service src/services/scheduler.ts	Adds delta-time-based scheduler for managing one-shot and repeating callbacks via setTimeout/setInterval equivalents; exported as singleton instance.
Event System & Utilities src/events/index.ts, src/common/utils.ts, src/common/index.ts	Removes EventManager class; adds unsubscribeAll utility function to bulk-invoke cleanup callbacks; exports unsubscribeAll from common module.
GameState Service Enhancement src/gameStateService/gameStateService.ts	Exposes LOADPUZZLE and STONEDROP event identifiers in the EVENTS interface; enables gameStateService subscriptions for core game events.
Audio System Enhancements src/components/audio-player.ts, src/components/__mocks__/audio-player.ts	Introduces non-pausable AudioContext, playUIAudio method (with volume/onEnded support), pauseAllAudios/resumeAllAudios methods; uses scheduler for prompt audio; adds mock methods.
Core Animation Timing src/common/stone-config/stone-config.ts, src/common/stone-config/stone-config.spec.ts	Changes draw signature from draw(shouldResize) to draw(deltaTime, shouldResize); replaces elapsed-time calculation with frame-based progress; adds isAnimating getter; updates test calls.
Event-Driven Component Refactoring src/components/level-indicator/level-indicator.ts, src/components/level-indicator/level-indicator.spec.ts	Removes EventManager inheritance; replaces with gameStateService.subscribe; stores unsubscribe function; updates tests to use subscription callbacks and verify cleanup.
Prompt Text & Animation src/components/prompt-text/prompt-text.ts, src/components/prompt-text/prompt-text.spec.ts, src/components/prompt-text/prompt-text.scss	Replaces EventManager with gameStateService subscriptions; uses scheduler.setTimeout; introduces handleGamePause for pause class toggling; adds paused animation-play-state CSS; updates test mocks.
Stone Handler Refactoring src/components/stone-handler/stone-handler.ts, src/components/stone-handler/stone-handler.spec.ts	Removes EventManager inheritance; uses gameStateService subscriptions; draw(deltaTime) now accepts and forwards deltaTime to stones; drawWordPuzzleLetters signature updated; uses unsubscribeAll for cleanup.
Timer & Animation Components src/components/timer-ticking.ts, src/components/timerHtml/timerHtml.spec.ts, src/components/riveComponent/rive-component.ts	TimerTicking removes EventManager, uses scheduler and gameStateService subscriptions; TimerHtml tests use scheduler.update; RiveComponent gains pause()/resume() methods.
Monster & Mini-Game Refactoring src/components/riveMonster/rive-monster-component.ts, src/miniGame/miniGames/miniGameHandler.ts, src/miniGame/miniGames/treasureChest/\\*	RiveMonsterComponent removes hitbox logic; MiniGameHandler.draw() renamed to start() with new update(deltaTime); TreasureChest classes refactored to use deltaTime instead of timestamp-based animations.
Pause Popup & UI src/components/popups/pause-popup/pause-popup-component.ts	Replaces playAudio with playUIAudio; updates base handler invocation with explicit arguments for pause/resume handling.
Feedback & Puzzle Handlers src/gamepuzzles/feedbackAudioHandler/feedbackAudioHandler.ts, src/gamepuzzles/puzzleHandler/puzzleHandler.ts	Replace setTimeout with scheduler.setTimeout for timing delayed callbacks in audio feedback and letter-drop animations.
Global API & Scene Setup src/feedTheMonster.ts, src/scenes/levelend-scene/levelend-scene.ts, src/scenes/progress-scene/progress-scene.ts	Adds setupMonsterEvolutionStateAPI for global getMonsterEvolutionState access; LevelEndScene coerces currentLevel to number; ProgressionScene introduces newScoreEarned field.
Tutorial Scheduler Integration src/tutorials/index.ts	Replaces setTimeout/clearTimeout with scheduler equivalents; adjusts TimerId type; normalizes levelNumber extraction.
New Gameplay Controllers & Managers src/scenes/gameplay-scene/monster-controller.ts, src/scenes/gameplay-scene/gameplay-input-manager.ts, src/scenes/gameplay-scene/gameplay-flow-manager.ts, src/scenes/gameplay-scene/gameplay-ui-manager.ts	Introduces four new manager/controller classes: MonsterController (Rive animation & hitbox), GameplayInputManager (input event dispatch), GameplayFlowManager (puzzle progression & flow orchestration), GameplayUIManager (UI component lifecycle & events).
GameplayScene Major Restructuring src/scenes/gameplay-scene/gameplay-scene.ts, src/scenes/gameplay-scene/gameplay-scene.spec.ts	Replaces direct UI component properties with manager/controller instances; introduces dispose, pauseGamePlay, resumeGame, handleVisibilityChange, and UI event handlers; restructures initialization, draw loop, and event handling; updates all tests to use new mocks and scheduler; integrates flow manager for puzzle progression.

Sequence Diagrams

sequenceDiagram
    participant App as Application
    participant GS as GameStateService
    participant Comp as Component
    participant Unsub as Unsubscribe Fn

    Note over App,Unsub: OLD: EventManager-Based Pattern
    App->>Comp: new Component(handler)
    Comp->>Comp: super(handler)<br/>register callbacks
    Comp->>Comp: addEventListener<br/>STONEDROP/LOADPUZZLE
    
    Note over App,Unsub: NEW: Pub-Sub Service Pattern
    App->>Comp: new Component()
    Comp->>GS: subscribe(STONEDROP)
    GS-->>Comp: Unsub Fn
    Comp->>Comp: store unsubscribe
    GS->>Comp: emit STONEDROP event
    Comp->>Comp: handle event
    App->>Comp: dispose()
    Comp->>Unsub: invoke stored<br/>unsubscribe

Loading

sequenceDiagram
    participant User as User Input
    participant IM as GameplayInputManager
    participant GS as GameStateService
    participant FM as GameplayFlowManager
    participant SH as StoneHandler
    participant PH as PuzzleHandler

    User->>IM: mouse click on stone
    IM->>IM: pickStone()
    IM->>GS: publish INPUT_DRAG_START
    GS->>FM: event received
    
    User->>IM: drag stone
    IM->>SH: updateStonePosition()
    IM->>GS: publish INPUT_STONE_DROP_ON_TARGET
    GS->>FM: handleStoneDropResult()
    FM->>PH: check answer
    PH-->>FM: isCorrect
    FM->>FM: determineNextStep()
    FM->>SH: loadPuzzle()

Loading

sequenceDiagram
    participant Sched as Scheduler
    participant Anim as AnimationComponent
    participant DrawLoop as Game Draw Loop

    Note over Sched,DrawLoop: Delta-Time-Based Animation Flow
    DrawLoop->>Sched: update(deltaTime)
    Sched->>Sched: advance all timers
    Sched->>Anim: callback() if ready
    Anim->>Anim: state transition
    
    DrawLoop->>Anim: draw(deltaTime)
    Anim->>Anim: frame += deltaTime/frameDuration
    Anim->>Anim: render based on frame progress

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

This PR introduces an entirely new architectural layer (scheduler, four new manager/controller classes), refactors event handling across 15+ components from inheritance-based to pub-sub-based, changes timing mechanisms throughout the codebase from timestamp-based to delta-time-based, and substantially restructures GameplayScene. The complexity is heightened by the interdependencies between the new managers, the cascading refactors across event-driven components, and the integration with multiple subsystems (audio, animation, input, UI). Heterogeneous changes demand separate reasoning for each manager and component refactoring pattern.

Possibly related PRs

• Refactor Gameplay Scene (FM-799) #1883 — Modifies GameplayScene architecture and GameplayInputManager with overlapping input/scene refactors, directly related at code level.
• chore: Test to Production deployment #1847 — Modifies src/components/audio-player.ts with overlapping AudioPlayer enhancements (volume/onEnded support), related at audio subsystem level.
• Test to Production Deployment #1861 — Modifies src/scenes/gameplay-scene/gameplay-scene.ts initialization and audio asset preloading, related through shared GameplayScene restructuring.

Suggested reviewers

• bernhardccodev
• ashwinnair-chimple
• miguelccodev

Poem

🐰 A new scheduler hops in time,
Delta flows in perfect rhyme,
EventManager bids adieu,
Managers orchestrate anew,
Pub-sub threads the grand design,
Gameplay's gears align! ⚙️✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the primary architectural change: implementing a Scheduler for pause/resume mechanics, which is reflected throughout the changeset (scheduler service added, integrated into gameplay components, timer/animation logic refactored).

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[miguelccodev]

Added comments. Please have a look.

[bernhardccodev]

Hi @janfb-codev looks good to me. I have reviewed it carefully and I am alright with the overall implementation.

I left some comments but it is more polishing and clean up and optional. Thanks!