🀄 麻雀ヒーロー (Mahjong Hero)

A Japanese Mahjong game where you play against 3 AI players powered by InsForge AI models. Features a beautiful Japanese manga-style UI and full game history tracking.

Features

• 🎮 Full Japanese Mahjong Gameplay: Complete implementation of Japanese Mahjong rules
• 🤖 AI Opponents: Play against 3 AI players using different AI models (GPT-4o, Claude Sonnet 4.5, Gemini 3 Flash)
• 🎨 Japanese Manga-Style UI: Beautiful, clean interface with manga-inspired design
• 📊 Game History: Track all your games, scores, and statistics
• 🔐 Authentication: Secure login with email/password or OAuth (Google, GitHub)
• 💾 Persistent Storage: All game data saved to InsForge backend

Tech Stack

• Frontend: React + TypeScript + Vite
• Backend: InsForge (BaaS platform)
• Database: PostgreSQL (via InsForge)
• AI: InsForge AI Integration (OpenAI, Anthropic, Google models)
• Styling: Tailwind CSS 3.4
• Authentication: InsForge Auth

Setup

Prerequisites

• Node.js 18+
• npm or yarn
• InsForge account and backend

Installation

1. Clone the repository

   git clone <repository-url>
   cd mahjong-hero

2. Install dependencies

   npm install

3. Set up environment variables

   Create a .env file in the root directory:

   VITE_INSFORGE_BASE_URL=https://your-backend.region.insforge.app
   VITE_INSFORGE_ANON_KEY=your_anon_key_here

   Get these values from your InsForge dashboard.

4. Run the development server

   npm run dev

5. Open your browser

   Navigate to http://localhost:5173

Database Schema

The app uses the following tables:

• games: Tracks game sessions
• game_players: Tracks players in each game
• game_turns: Records every action in the game

All tables have Row Level Security (RLS) enabled, so users can only see their own games.

Game Rules

This implementation follows Japanese Mahjong (Riichi Mahjong) rules:

• 4 players (1 human + 3 AI)
• 136 tiles (Man, Pin, Sou, Honors)
• Standard win conditions (4 melds + 1 pair, seven pairs, thirteen orphans)
• Chi, Pon, Kan calls
• Ron and Tsumo wins
• Riichi declaration
• Dora indicators

AI Players

The game uses three different AI models for variety:

1. Player 1: OpenAI GPT-4o
2. Player 2: Anthropic Claude Sonnet 4.5
3. Player 3: Google Gemini 3 Flash Preview

Each AI player receives the current game state and makes strategic decisions about their next move.

Project Structure

mahjong-hero/
├── src/
│   ├── components/       # React components
│   │   ├── Tile.tsx
│   │   ├── PlayerHand.tsx
│   │   ├── GameBoard.tsx
│   │   └── GameHistory.tsx
│   ├── hooks/            # Custom React hooks
│   │   └── useMahjongGame.ts
│   ├── lib/              # Library setup
│   │   └── insforge.ts
│   ├── types/            # TypeScript types
│   │   └── mahjong.ts
│   ├── utils/            # Utility functions
│   │   ├── mahjongLogic.ts
│   │   └── aiPlayer.ts
│   ├── App.tsx
│   └── main.tsx
├── .env                  # Environment variables (create this)
└── package.json

Development

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run lint - Run ESLint

License

MIT

Acknowledgments

• InsForge for the backend platform
• Japanese Mahjong community for the rules and terminology