User Manual — LMahjong

Overview

LMahjong is a classic Tux penguin-themed tile-matching solitaire game built natively for speed and offline play. Matches are structured across a 5-layer Turtle configuration, featuring multiple challenge levels and smart game mechanics.

100% Solvable Guarantee: Every board layout is generated in reverse from a fully-solved game state, guaranteeing that every puzzle generated is solvable. There are no dead-ends caused by random shuffles during initial deal operations.

Key Features

Classic Turtle layout featuring 144 tiles across 5 vertical layers.
Two distinct sprite phases: Penguin Phase (Levels 1-10) and Dog Phase (Levels 11-20).
Dynamic helper mechanisms: hint suggestions, infinite undo stack (up to 10 moves), and board shuffles.
Comprehensive score calculation including streak multiplier tracking and local leaderboard storage.
Highly optimized native Rust binary communicating directly with hardware SDL2 libraries for performance.

Installation

LMahjong is cross-platform. We provide precompiled binaries for Windows, macOS, and Linux, as well as instructions for building from source.

Linux Packages

Precompiled packages are offered in .deb, .rpm, and standalone .AppImage formats:

Ubuntu / Debian (.deb):

sudo apt install ./lmahjong_0.1.1_amd64.deb

Fedora / Red Hat (.rpm):

sudo dnf install ./lmahjong-0.1.1-1.x86_64.rpm

Universal Linux (.AppImage):

chmod +x lmahjong-0.1.1-x86_64.AppImage
./lmahjong-0.1.1-x86_64.AppImage

macOS App Bundle

On macOS, copy the precompiled bundle into your system applications folder:

# For ARM64 (Apple Silicon) or Intel x86_64
cp -R LMahjong-0.1.1.app /Applications/
open /Applications/LMahjong-0.1.1.app

Building from Source (Rust Toolchain)

Ensure you have standard SDL2 development libraries configured on your path:

# Ubuntu / Debian
sudo apt install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev pkg-config

# Cargo Build Commands
cargo build --release
cargo run --release

Rules & Matching

The goal of LMahjong is to clear all tiles from the 5-layer board configuration by matching matching pairs of free tiles.

The "Free Tile" Rule

A tile is considered "free" and selectable only if it meets the following conditions:

No Tile on Top: No other tile overlaps any part of the target tile's top face.
Open Left or Right Side: The tile is open on its left or right side. If both left and right sides are blocked by other tiles in the same layer, the tile cannot be selected.

Blocked Tiles: A tile that has other tiles overlapping it or flanking both its left and right sides is blocked. You must clear the surrounding blocking tiles first.

Tile Selection

Left-clicking a free tile will highlight it. Left-clicking a second free tile with the exact same sprite face will match them and remove both from the board. Left-clicking the highlighted tile again deselects it.

Levels & Progression

LMahjong contains 20 challenge levels. Progression increases the number of tiles on the board and introduces new tile style pools.

Penguin Phase (Levels 1-10)

Features Tux penguin tile face sprites exclusively (face IDs 0-49). Tile counts increase steadily with each level:

Level	Tiles	Pairs	Faces Used	Theme
Level 1	36	18	9	Penguins Only
Level 3	60	30	15	Penguins Only
Level 5	84	42	21	Penguins Only
Level 8	120	60	30	Penguins Only
Level 10	144	72	36	Penguins Only (Full Turtle Board)

Dog Phase (Levels 11-20)

Repeats the tile count progression but mixes in puppy and dog tile face sprites. Each level introduces an additional dog style (10 variants per style) into the randomized generator pool:

Level	Tiles	Pairs	Dog Styles Added	Total Face Pool Size	Theme
Level 11	36	18	1 style (faces 50-59)	60 (50 Penguins + 10 Dogs)	Penguins + Dogs
Level 13	60	30	3 styles (faces 50-79)	80 (50 Penguins + 30 Dogs)	Penguins + Dogs
Level 15	84	42	5 styles (faces 50-99)	100 (50 Penguins + 50 Dogs)	Penguins + Dogs
Level 20	144	72	5 styles (faces 50-99)	100 (50 Penguins + 50 Dogs)	Penguins + Dogs (Full Board)

Scoring System

Scores start at 0 and increase based on paired speed and streaks, while helper options incur score penalties.

Scoring Mechanics

Base Score: +10 points per matched pair removed.
Streak Multiplier: +2 points per match added to the active streak. Continuously pairing tiles without long delays builds your streak.
Hint Penalty: −5 points for each hint suggestion triggered.
Shuffle Penalty: −10 points for each layout shuffle triggered.
Time Bonus: Upon clearing the board, you receive a time bonus equal to: max(0, 500 − elapsed_seconds).

Keyboard Shortcuts

Full key mappings allow you to navigate game screens, save files, and control layouts rapidly.

Shortcut Action	Keyboard Command
Select free tile	Left Click
Start New Game	Ctrl+N
Save Game State	Ctrl+S
Resume Paused Game	Ctrl+R
Pause / Resume (Toggle)	Ctrl+P or Escape
Toggle Audio Mute	Ctrl+M
Undo Move (up to 10 back)	Shift+U
Suggest Matching Hint	Shift+H
Shuffle Active Layout (3x max)	Shift+S
Toggle Fullscreen Mode	F11
Save and Quit Application	Ctrl+Q

Data & Persistence

LMahjong runs entirely client-side. Leaders, configurations, and savegames are stored locally on your hard drive.

Save Paths by Platform

Windows:

%APPDATA%\lmahjong\savegame.json
%APPDATA%\lmahjong\leaderboard.json
%APPDATA%\lmahjong\settings.json

macOS:

~/Library/Application Support/lmahjong/savegame.json
~/Library/Application Support/lmahjong/leaderboard.json
~/Library/Application Support/lmahjong/settings.json

Linux:

~/.local/share/lmahjong/savegame.json
~/.local/share/lmahjong/leaderboard.json
~/.local/share/lmahjong/settings.json

Quick Reference

Total Level Tiles

36 to 144 tiles

Layout Layers

5 stacked layers

Undo Limit

Up to 10 moves

Shuffle Limit

3 shuffles per board

Base Points

+10 per matched pair

Streak Bonus

+2 points per streak

Hint Penalty

−5 points per query

Shuffle Penalty

−10 points per action

Time Bonus Limit

Max 500 points

Leaderboard Entries

Top 10 local scores