Akagi-NG

Next Generation Mahjong AI Assistant
Inspired by Akagi and MajsoulHelper

「死ねば助かるのに……」— 赤木しげる

简体中文 | English

Akagi-NG is the next-generation rewrite of the original Akagi project.

It is an AI-powered assistant designed for Japanese Mahjong (Riichi Mahjong), aimed at providing real-time situation analysis and decision recommendations for online Mahjong games.

Core Philosophy of Akagi-NG:

• Modern Architecture: Rebuilt based on Electron-native architecture, Python 3.12 and React/Vite
• Decoupled Design: Complete separation of core logic, user interface, configuration management, and AI models
• High-Performance Inference: Integrated libriichi for blazing fast Mortal model inference capabilities
• Long-term Maintainability: Optimized code structure for continuous iteration

The graph below is the overall data flow of Akagi-NG in Electron desktop / MITM modes.

Components:

• Dual-Mode Interceptor: Provides two methods for game data acquisition

  • Desktop Mode: Intercepts game communication via built-in Chromium browser + resource hooks, no proxy/certificate configuration needed
  • MITM Mode: Intercepts traffic from external browsers/clients via mitmproxy, supports third-party devices

• Python Backend (DataServer): Core data processing hub

  • Protocol Bridge: Converts Mahjong Soul protocol to MJAI standard format
  • State Tracker Bot: Maintains complete game state machine
  • AI Controller: Manages AI model and Lookahead algorithm, provides decision recommendations
  • SSE Event Stream: Pushes AI decisions to frontend in real-time via Server-Sent Events

• Electron Frontend: User interface and window management

  • Main Process: Manages backend process and coordinates multiple windows
  • Dashboard: Provides configuration management and game launch entry
  • HUD Overlay: Transparent overlay window displaying AI recommendations in real-time

• Game Window: Final game presentation layer

  • In Desktop Mode: Chromium instance managed by Electron
  • In MITM Mode: User's own browser or game client

Data Flow:

1. Game Server → Interceptor: Raw game data transmitted via WebSocket
2. Interceptor → Python Backend: Converted to MJAI event format
3. Python Backend Processing: State tracking + AI decision computation
4. Python Backend → Electron: Pushes decision results via SSE
5. HUD Overlay: Displays AI suggestions overlaid on game window

graph TB
    %% Game Server
    GS["Game Server<br/>"]

    %% Dual Mode Entry
    subgraph Modes ["Dual-Mode Interceptor"]
        direction LR
        DesktopMode["Desktop Mode<br/>Built-in Chromium + Hook"]
        MitmMode["MITM Mode<br/>mitm-proxy"]
    end

    %% Python Backend Core
    subgraph Backend ["Python Backend"]
        direction TB
        Bridge["Protocol Bridge<br/>(MJAI Adapter)"]
        Bot["State Tracker Bot<br/>(Game State)"]
        Controller["AI Controller<br/>(Mortal + Lookahead)"]
        SSE["SSE Event Stream<br/>(Real-time Push)"]

        Bridge --> Bot
        Bridge --> Controller
        Bot --> SSE
        Controller --> SSE
    end

    %% Electron Frontend
    subgraph Frontend ["Electron Frontend"]
        direction TB
        MainProcess["Main Process<br/>(Backend Manager + Window Manager)"]
        Dashboard["Dashboard<br/>(React UI)"]
        HUD["HUD Overlay<br/>(Transparent Layer)"]

        MainProcess -- "Window Management" --> Dashboard
        MainProcess -- "Window Management" --> HUD
    end

    %% Game Window
    GameWin["Game Window<br/>(Chromium Instance or Client)"]

    %% Data Flow
    GS <-- "Game Data" --> DesktopMode
    GS <-- "Game Data" --> MitmMode

    DesktopMode -- "MJAI Events" --> Bridge
    MitmMode -- "MJAI Events" --> Bridge

    SSE -- "SSE Connection" --> Dashboard
    SSE -- "AI Decisions" --> HUD

    Dashboard -- "IPC" --> MainProcess
    MainProcess -- "Window Management (Desktop Mode Only)" --> GameWin
    HUD -- "Visual Overlay" --> GameWin

    %% Styling
    classDef serverStyle fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    classDef modeStyle fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    classDef backendStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef frontendStyle fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    classDef gameStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:3px

    class GS serverStyle
    class DesktopMode,MitmMode modeStyle
    class Bridge,Bot,Controller,SSE backendStyle
    class MainProcess,Dashboard,HUD frontendStyle
    class GameWin gameStyle

• 🎮 Supported Platforms

  • Mahjong Soul
  • Tenhou
  • Riichi City
  • Amatsuki Mahjong

• 🀄 Supported Modes

  • Four-Player Mahjong (4p)
  • Three-Player Mahjong (3p)

• 🤖 AI Models

  • Mortal (Mortal 4p / Mortal 3p)
  • AkagiOT (AkagiOT 4p / AkagiOT 3p)

• 🧠 Core Functions

  • Real-time hand analysis and AI discard recommendations
  • Riichi Lookahead - Intelligent recommendation for the best discard after reaching
  • Comprehensive Fuuro Support - Clear action prompts for Chi, Pon, and all Kan variants
  • Modern Glassmorphism HUD - Smooth and unobtrusive floating window experience
  • Multi-language support - Simplified Chinese / Traditional Chinese / Japanese / English

This project is for educational and research purposes only.

Using third-party auxiliary tools in online games may violate the game's Terms of Service. The authors and contributors of Akagi-NG are NOT responsible for any consequences, including but not limited to account bans or suspensions.

Please fully understand and assume the relevant risks before use.

1. Download: Go to Releases and download the latest version, then extract it.
2. Deploy: Place AI model weight files (.pth) in the models/ directory, and binary extensions (.pyd/.so) in the lib/ directory.
3. Run: Double-click Akagi-NG.exe.
4. Play: Click "Launch Game" in the Dashboard and click the monitor icon at the top right to enable HUD.

To ensure the program runs correctly, please verify the directory structure where Akagi-NG.exe is located:

Akagi-NG/
  ├── Akagi-NG.exe     # Main Application (Electron Desktop)
  ├── assets/          # Platform-specific UI assets
  ├── bin/             # Backend core executable directory
  ├── config/          # Configuration directory (settings.json)
  ├── lib/             # libriichi binary extensions (.pyd/.so)
  │     ├── libriichi.pyd
  │     └── libriichi3p.pyd
  ├── locales/         # Localization resource files
  ├── logs/            # Runtime log directory
  ├── models/          # AI model weight files (.pth)
  │     ├── mortal.pth
  │     └── mortal3p.pth
  ├── resources/       # Electron core resources (app.asar)
  ├── LICENSE.txt      # Open source license
  ├── README.txt       # Quick start plain text guide
  └── ...              # Other runtime files (.dll, .pak, etc.)

When running Akagi-NG.exe for the first time, the integrated dashboard will appear. You can start the game directly from the dashboard to launch a dedicated browser window. Click the monitor icon in the top right of the dashboard to open the HUD overlay.

To exit the program, click the red power icon in the dashboard.

All configurations for Akagi-NG are located in the config/settings.json file. You can click the gear icon in the top right of the dashboard to enter the settings panel to modify them, or use a text editor to modify this file to adjust program behavior.

This is the default working mode of Akagi-NG.

In this mode, Akagi-NG leverages its Electron core to manage a specialized Chromium instance for the game.

• Key Features:

  • Zero Config: No certificates or proxy settings needed.
  • Environment Isolation: Completely isolated from your daily used browser.
  • Safe and Stable: Receives data from the game server directly.

• Usage:

  1. Run Akagi-NG.exe.
  2. Click "Launch Game" in the dashboard.

Akagi-NG supports intercepting game data via Man-in-the-Middle (MITM) attack. This allows you to play using any browser, client or on a mobile device (with proxy configured).

1. Enable Configuration: Switch on "External Proxy" in the configuration panel or modify the mitm field in config/settings.json:

   "mitm": { "enabled": true, "host": "127.0.0.1", "port": 6789 }

2. Set Proxy: Set your browser or system proxy to 127.0.0.1:6789.

3. Install Certificate:

   Note: If you use Scheme B (Clash splitting), you may be unable to open mitm.it. Method 2 is recommended.

   • Method 1: Online Installation (Recommended for Scheme A Users)

     • Start Akagi-NG.
     • Visit http://mitm.it.
     • Download the Windows certificate (p12 or cer).

   • Method 2: Local Installation (Recommended for Scheme B Users)

     • Find the .mitmproxy folder under the user directory (e.g., C:\Users\<YourName>\.mitmproxy).
     • Double-click mitmproxy-ca-cert.p12 to install.

   • Critical Step:

     • Double-click certificate -> Install Certificate -> Select Store Location "Trusted Root Certification Authorities".

Q: I launched the program for the first time, but it hangs on the welcome/loading screen. What should I do? A: This is usually caused by a conflict with the DataServer's default port 8765. Solution:

1. Open config/settings.json.
2. Find "server": { "port": 8765 } and change 8765 to another available port (e.g., 8888).
3. Restart the program.

Q: I am using proxy software like Clash/v2rayN (TUN/System Proxy mode), how should I configure it?

• Python 3.12+: Required for the backend engine.
• Node.js 24+ & npm: Required for the Electron desktop and React frontend.
• Git: For cloning the repository.
• Windows: Recommended development and build platform.

Clone the repository and initialize the project:

git clone https://github.com/Xe-Persistent/Akagi-NG.git
cd Akagi-NG

The integrated build system expects a virtual environment in the akagi_backend directory:

cd akagi_backend
python -m venv .venv
# Windows
.\.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -e .
cd ..

# Install frontend dependencies
cd akagi_frontend
npm install

# Install electron desktop dependencies
cd ../electron
npm install

To launch the integrated development environment:

cd electron
npm run dev

To package the application for your current platform:

cd electron
npm run build

The build artifacts will be generated in the dist/release directory.

This software follows the GNU Affero General Public License version 3 (AGPLv3) open source protocol.