Mahjong Haven Project Report
1. The Concept
Mahjong Haven is a calming, mobile-first Mahjong matching game designed around a traditional East Asian garden atmosphere. The experience combines classic Mahjong rules with a clean 9:16 full-screen interface, illustrated zen backgrounds, traditional tile artwork, and a simple progression system across four difficulty levels.
The goal was to make the game feel approachable: players can select matching free tiles, request a hint when needed, and move naturally from the home screen to difficulty selection, gameplay, and a completion screen.
2. The Stack
The Stack: HTML, CSS, and vanilla JavaScript in a single dependency-free static web app. The game stores progress and settings in browser local storage, so no backend or database is needed.
The AI Assist: Codex supported the implementation of game logic, UI refinements, traditional Mahjong tile assets, gameplay animations, responsive 9:16 layouts, board validation, and project documentation.
3. The 1 Day Sprint
Morning (Hours 1–3): Established the core app structure and screens: home, difficulty selection, gameplay HUD, game board, settings, help, and victory states. Built the Mahjong board data model, free-tile rules, matching logic, and the four difficulty categories.
Afternoon (Hours 4–6): Added the visual direction: zen garden backgrounds, home-screen artwork, level-select icons, traditional Mahjong tile PNG assets, full-screen mobile sizing, tile layering, shadows, selected states, hints, and matching feedback.
The Finish Line (Hours 7–8): Refined tile visibility and spacing, removed distracting borders from hint states, added automatic reshuffling and safe handling for an unexpected final tile, verified JavaScript syntax, and wrote the README and project report.
4. The Roadblocks
Roadblocks: The largest challenge was making independently generated PNG tile assets feel like one coherent Mahjong board. Transparent edges, baked-in shadows, overlapping layers, and blocked-tile opacity could make tiles appear disconnected or allow artwork underneath to show through. The solution was to tune image cropping, tile packing, opaque blocked states, and layer shadows until the board remained readable while preserving depth.
Another challenge was ensuring the player could never become stuck. The board layouts are generated in pairs and validated for even tile counts, with automatic reshuffling when no valid pair remains. A defensive final-tile recovery was also added to guarantee that an unexpected state cannot prevent board completion.
5. Key Takeaways
Small visual details have a major impact in a puzzle game. Tile spacing, opacity, shadows, and selection feedback all affect whether the board feels clear and satisfying to play.
Keeping the project dependency-free made iteration fast and keeps the game easy to run locally: open the page in a browser or serve the folder with a small local web server.
My final thought: Mahjong Haven shows that a focused one-day build can still deliver a complete, polished game loop when the visual style, game rules, responsive layout, and player feedback are designed together.