User Manual — xMahjong WebApp
Comprehensive player guide for the xMahjong WebAssembly solitaire web app. Explore the 100-level multi-phase campaign, mobile Pagoda view, lives system, and scoring mechanics.
Overview & Web App Access
xMahjong is a high-performance web application that delivers the complete Tux Mahjong Solitaire experience straight to your web browser with no downloads, plugins, or account setup required.
Core WebApp Architecture
- Rust Engine in WASM: Reverse-deal solvable board generation, game state, hit-testing, and streak timers run at native speeds via
webxmahjong.wasm. - Web Audio Synthesizer: Clean sound effects (clicks, match chimes, shuffle, and victory fanfare) synthesized directly in real time.
- Persistent Storage: Your campaign progress, remaining lives, level unlocks, audio preference, and top 10 leaderboard entries are automatically saved to browser
LocalStorage. - WebP Asset Streaming: Ultra-fast load times with compressed sprite textures (~90% payload reduction) and lazy-loaded phase themes.
Desktop vs. Mobile Viewport Modes
The web app includes dedicated responsive layouts tailored specifically for widescreen monitors and portrait mobile screens.
| Feature | 🖥️ Desktop View (16:9) | 📱 Mobile View (Portrait) |
|---|---|---|
| Primary Layout | Classic Turtle formation (up to 144 tiles across 5 layers) | 8-column Pagoda / Tower formation with dynamic auto-framing |
| Navigation & Controls | Top bar pill badges + full keyboard shortcuts (H, U, S, P, M) | Dedicated 2-row mobile HUD + thumb-friendly 5-button bottom toolbar |
| Tile Scaling | Optimized for mouse cursors with z-index elevation hover | +5% enlarged touch-friendly scaling with active viewport auto-focus |
| Manual Switching | Toggle anytime using the 🖥️ Desktop / 📱 Mobile button in the HUD. Your view preference is saved locally. | |
Rules & Matching
The objective is to clear all tiles from the board by selecting and pairing identical matching free tiles.
The Free Tile Rule
A tile can be clicked and matched only if it satisfies both criteria:
- No Top Overlap: No other tile is resting on or partially overlapping its upper surface.
- Open Edge: Either its left side OR its right side is completely unblocked by adjacent tiles in the same layer.
100-Level Campaign Progression
The campaign spans 100 uniquely generated challenge levels divided into four distinct phases. Clear levels to unlock level jumps in the level selector.
| Phase | Levels | Sprite Pool & Themes | Tile Density |
|---|---|---|---|
| 🐧 Phase 1: Tux Penguin | Levels 1 – 25 | Linux Tux Penguin sprites exclusively (Face IDs 0–49) | Gradual ramp from 36 tiles to 144 full Turtle boards |
| 🐶 Phase 2: Puppy Dog | Levels 26 – 50 | Puppy and canine sprite families introduced (Face IDs 50–99) | Mixed 60 to 144 tiles with expanding distinct face pool |
| 🚀 Phase 3: Space Explorer | Levels 51 – 75 | Astronaut Tux, aliens, constellations & rockets (Face IDs 100–149) | Complex 5-layer deep structures with high face diversity |
| 👑 Phase 4: Grandmaster | Levels 76 – 100 | Full comprehensive 200-face pool spanning all themes (Face IDs 0–199) | Full 144-tile boards requiring strategic pair planning |
Lives System, Hints & Reshuffles
Manage your lives and strategic game helpers to complete challenging boards without failing the campaign run.
Lives & Game Over Mechanics
- Starting Lives: You begin the campaign with 3 lives.
- Spending Lives: Reshuffling a board when no obvious pairs remain consumes 1 life.
- Earning Lives: Each time you clear a level for the first time in your run, you are awarded +1 bonus life. Replaying already-cleared levels does not award duplicate lives (anti-cheat balance).
- Game Over: If you run out of lives (0 remaining) and the board is blocked, your run concludes and your final score is recorded to the leaderboard.
Hints & Multi-Undo
- Hint Finder: Press H or tap the Hint button to highlight an available solvable pair immediately.
- Multi-Level Undo: Press U or tap Undo to roll back moves and rethink your clearing strategy.
- Difficulty Modes: Switch between Normal (standard campaign pacing) and Easy (more visible match suggestions).
Scoring & Multipliers
Maximize your high score with quick consecutive pairings and fast clear times.
| Scoring Component | Points Awarded | Details |
|---|---|---|
| Base Match | +10 points | Awarded for every matched free pair removed from the canvas. |
| Streak Bonus | +2 to +20 points | Pairing tiles in rapid succession builds your streak counter, multiplying points per match. |
| Clear Time Bonus | Up to +500 points | Calculated as max(0, 500 − elapsed_seconds) upon clearing all tiles. |
| Hint Penalty | −5 points | Deducted whenever a hint suggestion is requested. |
| Shuffle Penalty | −10 points | Deducted per reshuffle in addition to consuming 1 life. |
Controls & Hotkeys
Play with touch gestures on mobile or use mouse and keyboard shortcuts on laptops and desktops for blazing-fast pairing.
| Action | Desktop Hotkey | Mouse / Touch Action |
|---|---|---|
| Select / Deselect Tile | — | Left Click or Tap |
| Suggest Hint | H | Click / Tap the 💡 Hint button |
| Undo Move | U | Click / Tap the ↩️ Undo button |
| Shuffle Board (Costs 1 Life) | S | Click / Tap the 🔀 Shuffle button |
| Pause / Resume Game | P or ESC | Click / Tap the ⏸️ Pause button |
| Toggle Sound Audio Mute | M | Click / Tap the 🔊 Sound button |
| Switch Desktop / Mobile View | — | Click / Tap the 🖥️ Desktop / 📱 Mobile toggle |
| Open High Score Leaderboard | — | Click / Tap the 🏆 High Scores button |
LocalStorage & Audio Settings
The web application does not require cookies, logins, or tracking scripts. All game data is stored directly in your browser's isolated LocalStorage container.
Data Saved Automatically
current_level: Highest level reached and current campaign resume point.accumulated_score: Total running campaign points.lives_remaining: Current pool of available reshuffle lives.sound_muted: Audio preferences (Web Audio synthesis mute state).view_mode: Preferred layout orientation (Desktop 16:9 vs Mobile Pagoda).leaderboard: Top 10 personal high scores with completion timestamps.