🕉️ Devlog — गुरु-दीक्षा: Teaching Karma Without Breaking Immersion

"गुरु बिना ज्ञान नहीं।"
Without a Guru, there is no knowledge.

The Problem

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.

Why a Normal Tutorial Wouldn't Work

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 Solution: गुरु-दीक्षा (Guru's Initiation)

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.

A New Module — `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.

Slow Motion, Not Hard Pause

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.

Forced Spawns — `_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.

The 5 Steps

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).

Scripture-Style Card Rendering

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.

Persistence

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.

What This Closes

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

Commit:

https://github.com/weirdcodesofficial/MOKSHA/commit/dca7f3e13d654644d61231233002b4e851bd42ac

What's Next

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

StackFeed

Added Tutorial Mode | Moksha