Akagi

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



Ask me anything about this at Discord

中文
Report Bug . Request Feature

GitHub stars GitHub release GitHub issues Top language Discord Ask DeepWiki

About

"The purpose of this project is to provide people with a convenient way to real-time understand their performance in Mahjong game matches and to learn and improve from it. This project is intended for educational purposes only, and the author is not responsible for any actions taken by users using this project. Game developers and publishers have the right to take action against users who violate their terms of service, any consequences such as account suspension are not related to the author."

image

Feature

Table of Contents

⚠️ READ THE DOC BEFORE YOU START

⚠️ READ THE DOC BEFORE YOU START

⚠️ READ THE DOC BEFORE YOU START

Before You Start

🎥YouTube Video for you to follow.

You will need:

  1. A mjai_bot.
    1. A working one is already included here.
      • Because the limit of the file size, the mortal.pth here is a tiny weak small model.
      • It is not recommended to use it in a real game.
      • You can get a better model from Discord.
      • Or use the hosted model from the online server.
      • You can get the API key from Discord.
    2. Or make your own one, check Developer setcion.
  2. Use Windows Terminal to open akagi for a nice looking TUI.
  3. Proxifier or similar tools to redirect game client to the MITM port.

[!TIP] Some people have wrote a keygen for Proxifier, you can find it using Google.

Authors of this project are not responsible for any illegal actions taken by users.

[!WARNING]
Windows Terminal is required for user interface to work properly. Defalt Windows console will make the UI look ugly and not usable.

Supported Mahjong Games:

Platform Four Player Three Player AutoPlay
Majsoul ✓ ✓ *✓
Tenhou ✓ ✓ ✗
RiichiCity ✓ ✓ *✓
Amatsuki ✓ ✓ *✓

*AutoPlay only avaliable on Windows Release version when ot_server is running.

Installation

Usage

  1. Check your settings and AI Model.
    1. Select a Model.
      • By clicking on the "Model" button in the bottom left corner.
      • Select a model from the list.
      • If you don't have a model, get it from Discord.
      • Builtin default model is weak AI.
      • Choose 3P model for 3P game!
      • Do not join 3P game with 4P model!
    2. Check your settings.
      • By clicking on the "Settings" button in the bottom left corner.
      • Check your settings and make sure they are correct.
      • Set the MITM type to the game you are playing.
      • Set the MITM host and port to the correct values.
      • If you don't know what to set, leave it as default.
      • Default: (host: 127.0.0.1) (port: 7880)
      • If you have got a Online server API key, set it in the settings.
      • Online server provides a stronger AI model.
      • You can get the API key from Discord.
    3. Save your settings.
      • By clicking on the "Save" button.
      • This will save your settings.
    4. Restart Akagi.
      • Close Akagi and open it again.
      • This will apply the settings.
    5. Start MITM.
      • By clicking on the "MITM Stopped" button in the bottom left corner.
      • This will start the MITM proxy server.
  2. Install MITM Proxy Certificate.
    1. Open File Explorer (press Windows key + E)
    2. In the address bar at the top, type: %USERPROFILE%\.mitmproxy and press Enter.
    3. Look for a file called mitmproxy-ca-cert.cer.
    4. Double-click on the mitmproxy-ca-cert.cer file.
    5. Click the "Install Certificate" button.
    6. If you see a choice, select "Local Machine" and click "Next".
    7. Choose "Place all certificates in the following store", then click "Browse..."
    8. Select "Trusted Root Certification Authorities", click OK, then click "Next" and "Finish".
    9. If you're asked for permission, click "Yes".
  3. Proxifier Setup
    1. Open Proxifier and go to "Profile" > "Proxy Servers..."
    2. Click "Add..." and enter the following:
      • Address: The host you set in Akagi settings (default: 127.0.0.1)
      • Port: The port you set in Akagi settings (default: 7880)
      • Protocol: HTTPS
    3. Click "OK" to save the proxy settings.
    4. Go to "Profile" > "Proxification Rules..."
    5. Add a new rule by clicking "Add..."
    6. In the "Applications" tab, click "Browse..." and select the game executable.
      • This is usually located in the game installation folder.
      • For example, for Mahjong Soul Steam version:
        • Browse to your game in Steam library.
        • Click the manage button (gear icon) and select "Browse local files..."
        • This will open the game installation folder.
        • You should see the game executable file (e.g., Jantama_MahjongSoul.exe).
      • For web version, you can use the browser executable (e.g., chrome.exe or firefox.exe).
    7. In the "Target Hosts" tab, you can leave it default.
    8. In the "Action" tab, select the proxy server you just added.
    9. Click "OK" to save the rule.
  4. Start the game client.
    • Launch the game client (e.g., Mahjong Soul) and log in.
  5. Join a game.
    • Join a game as you normally would.
  6. Check Akagi.
    • You should see the AI analyzing the game in real-time.
    • If you see any errors, check the Logs for more information.
    • Or ask for help in the Discord server.

Instructions

Akagi

Starting MITM Proxy Server:

image

Selecting AI Model:

Models are stored in ./mjai_bot/ folder. image

Changing Settings:

[!IMPORTANT]
Restart might be required to apply the settings.

image

Opening Logs:

When you encounter a problem, you can open the logs to see what happened. Report the issue with the logs.

logs are saved in ./logs/ folder. image

Changing MJAI Info Window:

Click on the MJAI Info window to change kind of info you want to see. image

AutoPlay:

[!NOTE] AutoPlay is only available on Windows Release version when ot_server is running.

Make sure you have set the display of the game client to 16:9 aspect ratio. image image image

Changing theme:

image

Call Reach

The recommendation window does not show which tile to discard for riichi? You have to click on the "Reach" button to show the call reach recommendation. image

Proxifier

[!NOTE]
Proxifier is a tool that allows you to redirect network traffic through a proxy server. You can use it to redirect the game client traffic to the MITM proxy server.

Example Proxifier proxy settings:

image image

Example Proxifier proxy rules:

image image

Troubleshooting

You can ask for help in the Discord server.

[!TIP] If you encounter any issues, please check the logs in ./logs/ folder. The logs are saved in the ./logs/ folder. You can also check the GitHub Issues

[!NOTE] If you find a bug, please report it in the GitHub Issues. You can also report it in the Discord server. If you have a feature request, please report it in the GitHub Issues.

Developer

File Structure

Bridge

To make a bridge, you need to implement two things:

  1. ClientWebSocketABC in mitm/bridge/mitm_abc.py.
  2. Bridge in mitm/bridge/bridge_base.py.

For ClientWebSocketABC, this is an mitmproxy addon, main goal is to convert the game client protocol to MJAI protocol, and push it in to mjai_messages: queue.Queue[dict] = queue.Queue(). You can check the mitm/majsoul/ for the example.

For Bridge, this is the main class for the bridge. You need to implement the parse() method to parse the byte content from the game client into None | list[dict], you can check the mitm/bridge/amatsuki/bridge.py for the example.

MJAI Bot

To make a MJAI bot, you need to implement the Bot class in mjai_bot/base/bot.py.

TODO: make an tsumogiri bot example.

TODO

Contact

LICENSE

“Commons Clause” License Condition v1.0

The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.

Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.

For purposes of the foregoing, “Sell” means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/ support services related to the Software), a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.

Software: Akagi

License: GNU Affero General Public License version 3 with Commons Clause

Licensor: shinkuan