Tutorial Overlay Fix

🛠️ Devlog — Issue #48: Tutorial Overlay Fix

Version: v0.0.9-patch

Date: 2026-08-11

Author: Weired Codes

Issue: #48 — Tutorial overlay/guide cards block gameplay view

Tags: bug UI tutorial fix

Closes: #48

---

🇮🇳 हिंदी विवरण

समस्या क्या थी?

गुरु-दीक्षा (Tutorial) के guide cards पूरे gameplay canvas के ऊपर centered दिखते थे — जिससे खिलाड़ी को न माया दिखती थी, न भक्ति-मार्ग, न अपना रथ। Card के dismiss होने तक gameplay भी चलती रहती थी, जिससे player बिना देखे ही कर्म-बंधन में फँस सकता था।

क्या-क्या fix हुआ?

समस्या	समाधान
Tutorial card पूरा gameplay block करती थी	Card को semi-transparent किया (rgba(0,0,0,0.40)) — पीछे gameplay दिखे
Card visible होने पर gameplay चलती रहती थी	gameLoop में tutorial.hasActiveCard() check जोड़ा — card दिखे तो game pause
Dismiss के बाद dt spike आता था	Card dismiss होने पर lastTime = ts reset किया
Skip करने का स्पष्ट बटन नहीं था	Top-right corner पर ✕ छोड़ें / 5 skip button जोड़ा
CARD_Y variable missing था	render.js में const CARD_Y = (H - CARD_H) / 2 + 30 define किया

तकनीकी विवरण

src/render.js:

• drawTutorialCard() में CARD_Y की missing definition जोड़ी
• Card background rgba(0,0,0,0.72) → rgba(0,0,0,0.40) — semi-transparent
• Renderer._tutorialSkipBounds से skip button का hit-area store किया

src/main.js:

• gameLoop() में condition:

  // पहले:
  if (!engine.isPaused && !engine.gameOver && !engine.won && !engine.isShaashtraVisible)
  // अब:
  if (!engine.isPaused && !engine.gameOver && !engine.won && !engine.isShaashtraVisible && !tutorial.hasActiveCard())

• Card dismiss होने पर lastTime reset — अचानक dt jump रोकें

---

शास्त्र-संगति

गुरु-दीक्षा का उद्देश्य मार्गदर्शन है, बाधा नहीं।

जैसे सारथी यात्री को मार्ग दिखाता है, रथ नहीं रोकता —

वैसे ही tutorial card gameplay के साथ-साथ चले, उसे ढके नहीं।

---

🇬🇧 English Summary

Problem

Tutorial guide cards were centered and fully opaque, completely blocking the gameplay canvas. The game logic also continued running while the card was visible, meaning players could accumulate karma bondage without being able to see or react to it.

Fixes

• Semi-transparent card background — gameplay remains visible behind tutorial card
• Gameplay pause — gameLoop skips engine.update() while any tutorial card is active
• lastTime reset on dismiss — prevents dt spike / frame jump after card closes
• Skip button — clear ✕ Skip / 5 button in top-right corner of card
• CARD_Y ReferenceError — missing const CARD_Y definition added in render.js

Files Changed

File	Change
src/render.js	Added missing CARD_Y definition; semi-transparent card bg; skip button bounds
src/main.js	gameLoop pauses on tutorial.hasActiveCard(); lastTime reset on dismiss

---

📁 Files Changed

src/render.js
src/main.js

---

Closes #48 — Developed by Weired Codes — मोक्ष, एक आध्यात्मिक खेल।