Bubble Blaster
A timed target-popping game where players identify correct answers by tapping bubbles. Supports three game modes (Continuous, Clear All, Quick Pick), four difficulty tiers, and a combo/multiplier system that rewards speed and accuracy. Content is topic-based with educational prompts and explanations.
Game Flow
Topic Selection → Level Selection → Level Intro → Countdown → Playing (timed run) → Results
- Topic Selection: Choose from available topics (Science Basics, BIM & VDC Fundamentals)
- Level Selection: Grid of levels with high scores, best grades, and accuracy stats
- Level Intro: Shows mode description, difficulty, run duration, and tips
- Countdown: 3-2-1-GO
- Playing: Bubbles spawn on screen with a prompt displayed at top. Pop correct bubbles, avoid incorrect ones. Run lasts for a configured duration (default 60s).
- Results: Score breakdown with grade, accuracy, streak stats, and top-5 mistakes review with explanations
Game Modes
Continuous (default)
Bubbles spawn continuously at a rate that ramps up over time. Prompts rotate -- a new question appears after the current one's correct targets are cleared or the prompt timer expires.
Clear All
All targets for a prompt appear at once. Player must find and pop every correct bubble to advance to the next prompt. Incorrect bubbles are mixed in as distractors.
Quick Pick
Multiple choice format: 5 bubbles appear (1 correct, 4 incorrect). Points decay over time -- faster answers earn more. Starting at 150 points, decaying to a floor of 50.
Content Structure
Topic
└─ Level (difficulty, mode, duration)
└─ Question (prompt text)
└─ Target (label or image, isCorrect, explanation)
Topics
| Topic | Slug | Description |
|---|---|---|
| Science Basics | science | 5 levels, 17 questions -- states of matter, elements, forces |
| BIM & VDC Fundamentals | cad | Multi-level -- BIM tools, workflows, coordination |
Each question has a prompt (e.g., "Click all SOLIDS") and an array of targets with isCorrect flags and explanation strings shown in the mistakes review.
Difficulty Scaling
| Setting | Easy | Medium | Hard | Expert |
|---|---|---|---|---|
| Spawn rate (start) | 1/1400ms | 1/1200ms | 1/1000ms | 1/800ms |
| Spawn rate (end) | 1/900ms | 1/700ms | 1/550ms | 1/400ms |
| Target lifetime | 4500ms | 3800ms | 3000ms | 2500ms |
| Decoy ratio | 30% | 35% | 40% | 50% |
| Target size | Large | Medium | Medium | Small |
| Drift | No | No | No | Yes |
| Score multiplier | 1.0x | 1.15x | 1.3x | 1.5x |
Expert mode adds target drift -- bubbles slowly move across the playfield.
Scoring
Per-Hit Scoring
Hit Score = (100 + Speed Bonus) × Streak Multiplier
| Action | Points |
|---|---|
| Correct hit | +100 base |
| Speed bonus | Up to +75 (reaction < 1200ms) |
| Incorrect hit | -75, resets streak |
| Missed correct | -40, reduces streak (Easy/Medium: -5, Hard/Expert: reset) |
Speed bonus formula:
Speed Bonus = 75 × (1 - reactionMs / 1200)
Streak Multiplier
Builds with consecutive correct hits, resets on incorrect hit.
| Streak | Multiplier |
|---|---|
| 0-4 | 1.0x |
| 5-9 | 1.2x |
| 10-14 | 1.4x |
| 15-24 | 1.7x |
| 25-34 | 2.0x |
| 35+ | 2.5x |
End-of-Run Bonuses
| Bonus | Calculation |
|---|---|
| Accuracy bonus | accuracy% × 12 (max 1200) |
| Perfect bonus | 1500 base, scales with engagement (+20 per hit beyond 10, up to 2x) |
| Completion bonus | 500 flat |
Difficulty Multiplier
Applied to final score: Easy 1.0x, Medium 1.15x, Hard 1.3x, Expert 1.5x.
Grades
| Grade | Min Score | Min Accuracy |
|---|---|---|
| S+ | 12000 | 95% |
| S | 8500 | 90% |
| A | 5500 | 80% |
| B | 3500 | 70% |
| C | 2000 | 55% |
| D | < 2000 | < 55% |
Technical Architecture
Key Files
| Area | File | Purpose |
|---|---|---|
| Types | games/bubble-blaster/types.ts | GamePhase, GameState, ActiveTarget, RunStats, Difficulty, GameMode, Topic, Level, Question |
| Config | games/bubble-blaster/config.ts | Difficulty configs, mode configs, scoring constants, spawn rates, target sizes |
| Store | games/bubble-blaster/store.ts | Zustand store: spawn system, game tick, hit detection, streak tracking, prompt rotation |
| Content | games/bubble-blaster/content.ts | loadTopic(), getLevel(), shuffleQuestions(), pickTargetToSpawn() |
| Scoring | games/bubble-blaster/scoring.ts | calculateCorrectHitScore(), calculateEndOfRunBonuses(), calculateGrade(), updateStreak() |
| Audio | games/bubble-blaster/audio.ts | Audio pool (8 instances per SFX), pitch variation, background music loop |
| Hook | games/bubble-blaster/hooks/use-game-actions.ts | updateLevelProgress(), getLevelProgress() |
| Audio Hook | games/bubble-blaster/hooks/use-game-audio.ts | Phase-aware SFX/music management |
Components
| Component | Purpose |
|---|---|
playfield.tsx | Game area with grid background, target rendering, spawn orchestration |
target.tsx | Individual bubble: lifetime ring animation, hit feedback, drift (Expert) |
hud.tsx | Score, timer, streak bar, multiplier badge, prompt + progress bar, pause/mute |
results.tsx | Score breakdown, grade, top-5 mistakes review with explanations |
score-popup.tsx | Floating score animations, streak milestone celebrations |
level-list.tsx | Level grid with progress cards |
level-extras.tsx | Level card metadata: mode badge, run time, accuracy, grade |
grade-badge.tsx | Small grade badge |
topic-button.tsx | Topic selection card |
Uses shared components: LevelCard, LevelIntro, Countdown, PauseMenu, ResultsScreen, GameShell, GameHeader, GuestBadge.
Persistence
Storage key: bubble-blaster-state
Save data:
{
levelProgress: { [topicId_levelId]: { highScore, bestStreak, bestAccuracy, bestGrade, completedAt, attempts } },
lastPlayedLevel, lastPlayedTopic
}
Score submitted via submitScore() with metadata. Completion signaled via signalComplete().
Notable Mechanics
Grid-Based Spawn System
O(1) positioning algorithm using a grid overlay. Each target occupies a 3x3 cell zone to prevent overlap. Falls back to distance-maximization when the grid is full.
Prompt Timer
Each prompt has a configurable display duration. A visual progress bar under the prompt text shows remaining time. Auto-advances to the next question on expiration (behavior varies by mode).
Audio System
- Audio pool of 8 instances per sound effect to prevent clipping on rapid hits
- Pitch variation on hit sounds (±15%) for variety
- Background music with seamless loop
- Streak milestone sounds at 5, 10, 15, 20, 25, 30
Streak Celebrations
Visual celebrations at milestones with escalating messages:
| Streak | Message |
|---|---|
| 5 | "NICE!" |
| 10 | "GREAT!" |
| 15 | "AWESOME!" |
| 20 | "ON FIRE!" |
| 25 | "UNSTOPPABLE!" |
| 30+ | "LEGENDARY!" |
Mistake Tracking
Records every incorrect hit and missed correct target during a run. Results screen shows the top 5 mistakes with the original prompt and target explanation, reinforcing the educational content.
Mobile Optimization
- Larger touch targets on mobile (+8px padding)
- Responsive HUD layout switches between mobile and desktop arrangements
- Safe area handling for notched devices
Target Lifetime Ring
Each bubble renders a circular lifetime indicator using requestAnimationFrame for smooth animation. The ring depletes as the target approaches expiration, providing visual urgency.