Added Tutorial Mode | Moksha

🕉️ Devlog — गुरु-दीक्षा: Teaching Karma Without Breaking Immersion "गुरु बिना ज्ञान नहीं।" Without a Guru, there is no knowledge. Moksha is a game rooted in Sanatan Shastra — Vedic Karma mechanics, Sanskrit concepts, rebirth cycles. It's intentionally deep. And that depth was quietly becoming its biggest barrier. New players would start the game and immediately face naama-jaap, vairaagya, prarabdha, chetana-jagriti — all at once, with no guidance. Within the first 30 seconds, most had no idea what they were doing or why. The game needed a tutorial. But it needed one that didn't betray what Moksha is. The obvious solution — pause the game, show a tooltip, unpause — felt completely wrong for Moksha. Spiritually, a hard pause breaks the flow of consciousness. Mechanically, isPaused = true is deeply wired into audio ducking, gamepad state, and ambient layers. Hijacking it for tutorial logic would have introduced subtle bugs across every system. An earlier attempt at a tutorial (Issue #30) tried to live inside engine.js itself. That was worse — the engine is already the heaviest file in the codebase, and embedding tutorial step state there violated the entire modular architecture we'd been building toward. So I scrapped both approaches and started over. The new system is built around one philosophical reframe: a Guru doesn't stop the world to teach. They walk alongside you. This became the technical foundation too. src/tutorial.js TutorialManager is a self-contained ES6 class. It doesn't import from engine.js or touch any game state directly. Instead, main.js passes it an engine state snapshot every frame via checkCompletion(state). The tutorial reads — never writes. engine.js ──(no connection)──> tutorial.js main.js ──(snapshot feed)──> tutorial.js Zero coupling. Zero risk to existing systems. When a tutorial card is visible, the game doesn't stop. Instead, dt is multiplied by 0.3 in the game loop: const dt = tutorial.isSlowMode() ? rawDt * 0.3 : rawDt; The world keeps moving — entities drift, the cosmos breathes — but at a contemplative pace. It feels like the Guru has slowed time itself to let you absorb the teaching. As soon as you dismiss the card, full speed resumes instantly. _forceSpawnMaya(type, x, y) Some tutorial steps require specific entities to appear — a naama (ॐ) to collect, a specific Maya type to encounter. Random spawning can't be trusted for this. A new method was added to KarmaMixin in karma.js: _forceSpawnMaya(type, x, y) { // Deterministic pool slot allocation — no random, no push/splice for (let i = 0; i < this.mayaPool.length; i++) { if (!this.mayaPool[i].active) { // assign type + position directly break; } } } It follows the same fixed-size object pool pattern used everywhere in the engine — no heap allocation, no GC pressure. Step What You Do Shaastra 1 Move your Pankhudi (सारथी) "उद्धरेदात्मनात्मानं" — Gita 6.5 2 Collect a Naama (ॐ) "मायाजालमिदं विश्वं" — Yogavasishtha 3 Perform Naama-Jaap "नाम जपत मंगल" — Ramcharitmanas 4 Enter the Bhakti-Maarg "भक्त्या मामभिजानाति" — Gita 18.55 5 Learn about Prarabdha "भोगेन क्षीयते पापं" — Skanda Purana Each card shows the relevant Sanskrit shloka with attribution — scripture style, not tooltip style. The last step is information-only (Prarabdha cannot be "completed," only endured — which is the point). drawTutorialCard() in render.js renders a full overlay card: Dark semi-transparent backdrop (game remains visible beneath) Saffron accent line at the top Gold 🕉️ header Sanskrit shloka in italic serif Source attribution (Gita, Upanishad, Purana) Task text with multi-line support Dismiss button: ENTER / TAP / Gamepad START ESC skips the entire initiation The card is visually distinct from the existing alert system — bigger, centered, designed to be read slowly. Once completed or skipped, localStorage records it: localStorage.setItem('moksha_tutorial_seen', '1'); The tutorial never shows again. Players who know what they're doing aren't forced to sit through it. This implementation resolves Issue #37 and supersedes the earlier attempt in Issue #30. The checklist from the issue spec: ✅ src/tutorial.js — TutorialManager ✅ Slow-motion dt × 0.3 (not isPaused) ✅ _forceSpawnMaya(type, x, y) in karma.js ✅ Scripture-style dismissible card in render.js ✅ localStorage persistence ✅ ESC to skip ✅ ENTER / click / Gamepad START to dismiss ✅ Engine fully decoupled — engine.js untouched https://github.com/weirdcodesofficial/MOKSHA/commit/dca7f3e13d654644d61231233002b4e851bd42ac The tutorial lays the foundation for v0.1.0 — Pankhudi Directional Mechanics, where active pankhudi direction will drive power shoot, Maya pull, and Indriya pull. That's a significant gameplay overhaul and deserves its own devlog when the time comes. For now — if you've played Moksha before and found it confusing, try it again. The Guru is waiting. Moksha is a solo-developed browser game rooted in Sanatan Shastra. Play it at weirdcodes.itch.io/moksha Support the project at ko-fi.com/weirdcodes