User Manual — xMahjong WebApp
Comprehensive player guide for the xMahjong WebAssembly solitaire web app. Explore the 1000-level multi-phase campaign across 5 phases, mobile Pagoda view with 3× magnifier, daily gifts & streaks, 12 languages, and trophy card export.
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.wasmacross 1000 uniquely generated levels. - 4 Visual Theme Sets: Dynamic loading across Classic Tux Penguin, Puppy Dog, Space Explorer, and Ocean themes with hardware-accelerated vibrancy (
ctx.filter). - Fail-Safe Web Audio Engine: Procedurally synthesized sound effects (clicks, pair matches, shuffles, and victory chimes) with decoupled progression that ensures smooth play across all browsers and desktop wrappers.
- Persistent Storage: Your campaign progress, remaining lives, level unlocks, audio preferences, daily streak records, and trophy statistics are automatically saved to browser
LocalStorage. - Desktop Packaging: Also packaged natively via Tauri v2 for Linux (.AppImage, .deb, .rpm, .snap), Windows (.exe installer & portable), and macOS (.dmg universal). Download 11 desktop packages →
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, ESC) | Dedicated 2-row mobile HUD + thumb-friendly 5-button bottom toolbar |
| Tile Scaling & Zoom | Optimized for mouse cursors with z-index elevation hover | +5% enlarged touch scaling, dynamic auto-framing, plus 3× Long-Press Magnifier Zoom |
| Manual Switching | Toggle anytime using the 🖥️ Desktop / 📱 Mobile button in the HUD. Your view preference is saved locally. | |
🔍 3× ZOOM callout badge for effortless inspection on smaller screens. When ≤6 tiles remain, auto-framing automatically enlarges the remaining tiles.
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.
1000-Level Campaign Progression
The campaign spans 1000 uniquely generated challenge levels divided into five progressive phases. Clear levels to unlock level jumps in the level selector.
| Phase | Levels | Sprite Pool & Themes | Tile Density & Mechanics |
|---|---|---|---|
| 🐧 Phase 1: Classic Tux Penguin | Levels 1 – 10 | Linux Tux Penguin sprites exclusively (Face IDs 0–49) | Gradual ramp from 36 tiles to 144 full Turtle boards |
| 🐶 Phase 2: Puppy Dog | Levels 11 – 20 | 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 21 – 50 | Astronaut Tux, aliens, constellations & rockets (Face IDs 100–149) | Complex 5-layer deep structures with high face diversity |
| ⚡ Phase 4: Endgame Phase | Levels 51 – 100 | Challenging layout variations and high-density formations | Strict solvable path requirements; tests advanced matching speed |
| 👑 Phase 5: Grandmaster Mixed | Levels 101 – 1000 | Comprehensive 4-theme sprite pool (Penguin, Dog, Space & Ocean) | Massive 900-level endgame across full 144-tile boards with auto-win detection |
Lives System, Daily Gift & Streaks
Manage your lives, claim your daily launch gift, and maintain unbroken play streaks across your campaign journey.
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).
- Daily Free Gift: On your first launch every calendar day, you receive a free +1 bonus life gift accompanied by an animated celebratory toast banner and sound chime.
- Daily Consistency Streaks: Track your current daily play streak and highest unbroken daily streak record directly in your player stats.
- 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 with an emerald green glow aura.
- 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).
Trophies & 1080×1080 Image Export
Track your lifetime achievements and share high-resolution social milestone cards with your friends.
Trophies Dashboard Features
- Official Branding: Prominent
🀄 xMahjongbadge header. - Career Metrics: Highest completed level, total accumulated score, hints used, and daily claim history.
- Consistency Tracker: Live display of current daily streak and personal best streak record.
- 1-Click Achievement Card Export: Click the Download Stats Card button to generate and download a crisp, square 1080×1080 PNG achievement graphic (
xmahjong-trophies.png) ready for Instagram, X (Twitter), Facebook, or Discord.
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. |
12 Languages & Glassmorphic UI
xMahjong offers native localized interfaces for 12 international languages with instant live switching.
Supported Languages
English (🇬🇧 EN), Spanish (🇪🇸 ES), French (🇫🇷 FR), German (🇩🇪 DE), Italian (🇮🇹 IT), Portuguese-BR (🇧🇷 PT), Dutch (🇳🇱 NL), Polish (🇵🇱 PL), Turkish (🇹🇷 TR), Tamil (🇮🇳 TA), Japanese (🇯🇵 JA), and Chinese (🇨🇳 ZH).
Click or tap the language selector in the top HUD to open the frosted-glass popover card. Select your preferred language for instant live translation across the game HUD, status pills, modals, and trophy dashboards.
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 |
| 3× Tile Magnifier (Mobile >6 tiles) | — | Long Press on any tile |
| 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 Trophies & Stats Modal | — | Click / Tap the 🏆 Trophies & Stats button |
| Switch Interface Language | — | Click / Tap the 🌐 Language selector popover |
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 (1–1000).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).language: Chosen interface language code (e.g.en,es,ja).daily_streak: Daily launch consistency tracking and claim records.trophy_stats: Lifetime hints used, completed milestones, and top high scores.leaderboard: Top 10 personal high scores with completion timestamps.