riichi-mahjong-studio - 日麻桌面应用

项目说明

Riichi Mahjong Studio

中文 | 日本語 | English

![Release]()
!Platform
![CI]()

---

<div lang="zh-CN">

中文

!Riichi Mahjong Studio 中文界面

立直麻将研究室

一款用于立直麻将牌谱研究和对局练习的桌面程序，可加载兼容 Riichi Engine Protocol 的外部引擎。

主要功能

* 在研究模式中回看牌局、建立分支，并为各个节点记录评注
* 在对局模式中从完整牌山开始练习，其他玩家由引擎控制
* 通过 Riichi Engine Protocol 安装外部引擎，不同分析项目可以使用不同引擎
* 根据已加载引擎的能力显示动作推荐、对手向听、放铳风险、暗牌和牌山预测、打点与结果预测等信息
* 导入 Mortal 在线分析报告和天凤自定义牌谱
* 使用 .mjstudio 保存牌局、研究分支和评注，也可以与他人分享
* 支持自定义音效包
* 界面支持简体中文、日文和英文

分析信息

加载具有相应能力的外部引擎后，Studio 可以在牌局中显示以下类型的分析信息：

| 类别 | 信息 |
| ---- | ------------------ |
| 动作分析 | 候选动作、推荐动作、动作评价 |
| 对手状态 | 三名对手的向听状态 |
| 放铳风险 | 各牌张对三名对手的放铳概率或风险 |
| 对手暗牌 | 对手手牌的预测分布 |
| 牌山 | 未见牌和剩余牌山的预测 |
| 手牌价值 | 对手宝牌数量、打点等估计 |
| 小局结果 | 和牌、放铳、流局等结果及分数变化预测 |
| 整场结果 | 最终顺位和终局分数预测 |

一个引擎可以提供多项输出，也可以为不同输出分别配置不同的引擎。

牌谱研究

研究模式以节点和分支保存牌局。

可以回到牌局中的任意节点建立新的分支，选择不同的动作并继续向后研究，也可以在各个节点之间切换。节点可以添加评注，用来记录当时的判断、不同选择的比较或其他研究内容。

牌局及其分支、评注可以一起保存在 .mjstudio 文件中，之后继续编辑或分享给其他人。

对局练习

新建牌局时，程序会随机生成一副完整牌山，并由引擎控制其他三名玩家。

对局过程中可以使用已经配置的外部引擎获取相应的分析信息。

从导入牌谱进入对局模式时，也可以重新构建牌谱中未知的牌山部分，从已有局面继续尝试不同的后续选择。

导入牌谱

目前支持导入：

* Mortal 在线分析报告
* 天凤自定义牌谱的地址或内容

导入后可以直接查看牌局，也可以添加评注、建立研究分支，或从其中的局面进入对局模式继续练习。

获取与启动

前往 Releases 下载最新版本，解压后运行 Riichi Mahjong Studio.exe。

当前发布版本提供 Windows x64 便携版。

基本使用

* 新建牌局： 点击“新建”，从随机生成的完整牌山开始练习。
* 打开存档： 点击“打开”，选择此前保存的 .mjstudio 文件。旧 .mjtrain 存档也可以打开。
* 导入牌谱： 点击“导入”，粘贴 Mortal 在线分析报告地址，或天凤自定义牌谱的地址或内容。
* 研究牌局： 在研究模式中浏览牌局、建立分支、切换节点并添加评注。
* 保存存档： 使用“保存”或“另存为”保存当前牌局及其研究内容。

外部引擎

Studio 通过 Riichi Engine Protocol 与外部引擎通信。

外部引擎会声明自己提供的输出类型。一个引擎可以同时提供多项输出，也可以分别为动作分析、对手分析等功能配置不同引擎。

牌谱浏览、分支和评注等功能由主程序直接提供。对局中的其他玩家控制，以及动作推荐、对手分析等模型功能，需要加载具有相应能力的引擎。

#### 配置引擎

1. 准备兼容 Riichi Engine Protocol 的引擎程序及其所需模型权重。
2. 打开“引擎”，点击“添加引擎”，选择引擎的可执行文件或 Python 入口。
3. 等待主程序读取引擎声明，然后选择需要使用的输出。
4. 按界面提示选择模型权重、运行设备并调整引擎参数。
5. 点击“加载”。加载完成后，相应输出即可用于分析界面或对局流程。
6. 需要修改已加载引擎的配置时，请先将其卸载。

音效包

将兼容的音效包完整解压到主程序旁的 sound-packs 目录中；如果没有该目录，可以自行创建。

重新启动程序后，在“设置 → 音效 → 音效包”中选择需要使用的音效包。

自定义音效包的制作方法见音效包文档。

相关项目

* Riichi Engine Protocol：Studio 与外部引擎之间使用的通信协议和程序包格式。
* Riichi Analysis Engine：正在开发中的立直麻将分析引擎，覆盖动作推荐、对手状态、隐藏信息和牌局结果等分析任务。

开发与贡献

欢迎提交 Issue、参与讨论或贡献代码。

主程序的构建、调试和测试方法见开发文档。

外部引擎的接口和程序包格式见 Riichi Engine Protocol。

许可证

主程序采用 Apache License 2.0。

第三方代码、素材和外部组件适用各自的许可条款，详见第三方声明。

</div>

---

<div lang="ja">

日本語

!立直麻雀スタジオ 日本語画面

立直麻雀スタジオ

リーチ麻雀の牌譜検討と対局練習を行うためのデスクトップアプリケーションです。Riichi Engine Protocol に対応した外部エンジンを読み込めます。

主な機能

* 研究モードで牌譜を確認し、分岐を作成して各ノードにコメントを記録
* 対局モードで完全な牌山から練習し、他家はエンジンが操作
* Riichi Engine Protocol を通じて外部エンジンを追加し、解析項目ごとに異なるエンジンを使用可能
* 読み込んだエンジンの機能に応じて、推奨行動、相手のシャンテン数、放銃リスク、手牌や牌山の予測、打点、対局結果などを表示
* Mortal Online Analysis のレポートと天鳳カスタム牌譜をインポート
* .mjstudio ファイルに牌譜、研究分岐、コメントを保存し、他のユーザーと共有
* カスタムサウンドパックに対応
* 簡体字中国語、日本語、英語のUIに対応

解析情報

対応する機能を持つ外部エンジンを読み込むと、Studio では以下のような解析情報を表示できます。

| 分類 | 情報 |
| ----- | ------------------------------ |
| 行動解析 | 候補行動、推奨行動、行動評価 |
| 相手状態 | 3人の相手のシャンテン状態 |
| 放銃リスク | 各牌について、3人の相手それぞれに対する放銃確率またはリスク |
| 相手手牌 | 相手手牌の予測分布 |
| 牌山 | 未知牌と残りの牌山の予測 |
| 手牌価値 | 相手のドラ枚数、打点などの推定 |
| 局結果 | 和了、放銃、流局などの結果と得失点の予測 |
| 半荘結果 | 最終順位と最終持ち点の予測 |

1つのエンジンから複数の出力を利用することも、出力ごとに別のエンジンを設定することもできます。

牌譜研究

研究モードでは、牌局をノードと分岐として保存します。

任意のノードに戻って新しい分岐を作り、別の行動を選んでその先を検討できます。ノード間は自由に移動でき、各ノードにはその時点での判断や選択肢の比較などをコメントとして記録できます。

牌局、分岐、コメントはまとめて .mjstudio ファイルに保存でき、後から続きを編集したり他のユーザーと共有したりできます。

対局練習

新しい対局を作成すると、プログラムが完全な牌山をランダムに生成し、他の3人をエンジンが操作します。

対局中は、設定済みの外部エンジンから対応する解析情報を取得できます。

インポートした牌譜から対局モードへ移る場合は、牌譜からは分からない牌山部分を再構成し、既存の局面から別の展開を試すこともできます。

牌譜のインポート

現在、以下のデータをインポートできます。

* Mortal Online Analysis のレポート
* 天鳳カスタム牌譜 のURLまたは内容

インポート後は牌譜を閲覧できるほか、コメントの追加、研究分岐の作成、局面から対局モードへ移っての練習もできます。

入手と起動

Releases から最新版をダウンロードし、展開後に Riichi Mahjong Studio.exe を実行してください。

現在は Windows x64 向けのポータブル版を配布しています。

基本操作

* 新しい対局： 「新規」をクリックし、ランダムに生成された完全な牌山から練習を開始します。
* 保存データを開く： 「開く」をクリックし、保存済みの .mjstudio ファイルを選択します。旧 .mjtrain ファイルも開けます。
* 牌譜をインポート： 「インポート」をクリックし、Mortal Online Analysis のレポートURL、または天鳳カスタム牌譜のURLや内容を入力します。
* 牌譜を研究： 研究モードで牌局を確認し、分岐の作成、ノードの切り替え、コメントの追加を行います。
* 保存： 「保存」または「名前を付けて保存」で、現在の牌局と研究内容を保存します。

外部エンジン

Studio は Riichi Engine Protocol を通じて外部エンジンと通信します。

外部エンジンは、自身が提供する出力の種類を宣言します。1つのエンジンで複数の出力を提供することも、行動解析や相手解析などに別々のエンジンを設定することもできます。

牌譜の閲覧、分岐、コメントなどはStudio本体の機能です。他家の操作や、推奨行動、相手解析などのモデル機能には、対応する外部エンジンが必要です。

#### エンジンの設定

1. Riichi Engine Protocol に対応したエンジンプログラムと、必要なモデル重みを用意します。
2. 「エンジン」を開き、「エンジンを追加」をクリックして、エンジンの実行ファイルまたは Python エントリを選択します。
3. Studio がエンジン宣言を読み込んだ後、使用する出力を選択します。
4. 画面の案内に従って、モデル重み、実行デバイス、エンジンのパラメータを設定します。
5. 「読み込み」をクリックします。読み込みが完了すると、対応する出力を解析画面や対局で使用できます。
6. 読み込み済みのエンジン設定を変更する場合は、先にアンロードしてください。

サウンドパック

対応するサウンドパックを、プログラム本体と同じ場所にある sound-packs ディレクトリへ展開します。ディレクトリがない場合は作成してください。

プログラムを再起動し、「設定 → サウンド → サウンドパック」から使用するサウンドパックを選択します。

カスタムサウンドパックの作成方法はサウンドパックのドキュメントを参照してください。

関連プロジェクト

* Riichi Engine Protocol：Studio と外部エンジンの間で使用する通信プロトコルとパッケージ形式。
* Riichi Analysis Engine：現在開発中のリーチ麻雀解析エンジン。行動推薦、相手状態、非公開情報、対局結果などの解析タスクを扱います。

開発とコントリビュート

Issue の投稿、議論、コードへのコントリビュートを歓迎します。

ビルド、デバッグ、テストについては開発ドキュメントを参照してください。

外部エンジンのインターフェースとパッケージ形式については Riichi Engine Protocol を参照してください。

ライセンス

本体は Apache License 2.0 で提供しています。

サードパーティーのコード、素材、外部コンポーネントには、それぞれのライセンスが適用されます。詳細はサードパーティーに関する表記を参照してください。

</div>

---

<div lang="en">

English

!Riichi Mahjong Studio English interface

Riichi Mahjong Studio

A desktop application for Riichi 麻将 游戏-record study and 游戏 practice. It can load external engines compatible with the Riichi 引擎 协议.

Main Features

* Review games in Study Mode, create branches, and add annotations to indi nodes
* Practice from a complete wall in 游戏 Mode, with the other players controlled by engines
* Install external engines through the Riichi 引擎 协议 and use different engines for different analysis outputs
* Display action recommendations, opponent shanten, deal-in risk, concealed-hand and wall predictions, hand value, and outcome predictions according to the capabilities of the loaded engines
* Import Mortal Online Analysis reports and Tenhou custom 游戏 records
* Sa, study branches, and annotations in .mjstudio files and share them with others
* Use custom sound packs
* Use the interface in Simplified Chinese, Japanese, or English

Analysis Information

After loading an external 引擎 with the corresponding capabilities, Studio can display the following types of analysis:

| Category | Information |
| --------------- | ----------------------------------------------------------------------- |
| Action analysis | Candidate actions, recommended actions, action e |
| Opponent state | Shanten states of the three opponents |
| Deal-in risk | Deal-in probability or risk for each tile against each opponent |
| Opponent hands | Predicted distributions of opponents' concealed hands |
| Wall | Predictions for unseen tiles and the remaining wall |
| Hand value | Estimates of opponents' dora count, hand value, and related information |
| Kyoku result | Predictions for wins, deal-ins, draws, and score changes |
| Match result | Predicted final placement and final scores |

A single 引擎 can provide several outputs, or different engines can be assigned to different outputs.

Game Record Study

Study Mode stores the 游戏 as nodes and branches.

You can return to any node, create a new branch, choose a different action, and continue studying from there. You can mo nodes freely. Each node can also contain annotations for recording decisions, comparing alternatives, or keeping other notes.

The 游戏, its branches, and annotations can be sa in a .mjstudio file for later editing or sharing.

Game Practice

When creating a new 游戏, the program generates a complete wall at random and lets engines control the other three players.

Configured external engines can provide their analysis outputs during the 游戏.

When entering 游戏 Mode from an imported record, Studio can also reconstruct the unknown part of the wall and continue from an existing position to try a different continuation.

Importing Game Records

Studio currently supports:

* Mortal Online Analysis reports
* Tenhou custom 游戏 records by URL or content

After importing a 游戏, you can review it directly, add annotations, create study branches, or enter 游戏 Mode from one of its positions.

Download and Launch

Go to Releases, download the latest , extract it, and run Riichi Mahjong Studio.exe.

The current release is a as a portable build for Windows x64.

Basic Usage

* New Game: Click “New” to start practicing from a randomly generated complete wall.
* Open: Click “Open” and select a pre saved .mjstudio file. Legacy .mjtrain files are also supported.
* Import: Click “Import” and enter a Mortal Online Analysis report URL or a Tenhou custom 游戏-record URL or its contents.
* Study: Use Study Mode to review the 游戏, create branches, switch between nodes, and add annotations.
* Save: Use “Save” or “Save As” to save the current 游戏 and study content.

External Engines

Studio communicates with external engines through the Riichi 引擎 协议.

Each external 引擎 declares the types of outputs it provides. One 引擎 may provide several outputs, or separate engines can be configured for action analysis, opponent analysis, and other functions.

游戏-record browsing, branches, and annotations are provided by Studio itself. 引擎-controlled opponents and model-based functions such as action recommendations and opponent analysis require an 引擎 with the corresponding capabilities.

#### Configuring an Engine

1. Prepare an 引擎 compatible with the Riichi 引擎 协议 and any model weights it requires.
2. Open “Engines”, click “Add Engine”, and select the 引擎 executable or Python entry point.
3. Wait for Studio to read the 引擎 declaration, then select the outputs you want to use.
4. Follow the interface to choose model weights, the runtime device, and 引擎 parameters.
5. Click “Load”. Once loading is complete, the selected outputs can be used in the corresponding analysis views or 游戏 flow.
6. Unload an 引擎 before changing its configuration.

Sound Packs

Extract a compatible sound pack into the sound-packs directory next to the program. Create the directory if it does not exist.

Restart the program, then select the sound pack under “Settings → Sound → Sound Pack”.

See the sound-pack documentation for instructions on creating custom sound packs.

Related Projects

* Riichi 引擎 协议: The communication 协议 and package format used between Studio and external engines.
* Riichi Analysis 引擎: A Riichi 麻将 analysis 引擎 currently under de, co action recommendations, opponent state, hidden information, and 游戏-outcome analysis.

De and Contribution

Issues, discussion, and 代码 contributions are welcome.

See the de documentation for build, debugging, and testing instructions.

See the Riichi 引擎 协议 for the external-引擎 interface and package format.

License

The main application is licensed under the Apache License 2.0.

Third-party 代码, assets, and external components are subject to their respecti. See THIRD_PARTY_NOTICES.md for details.

</div>

技术栈

开发语言：Python

项目类型：日麻桌面应用

Star 数：87

功能特点

这是一套日麻桌面应用，代码结构清晰，适合开发者学习游戏的客户端渲染、服务端逻辑、场景管理与资源加载。项目涵盖了游戏的核心玩法、界面交互、地图与角色系统等模块，对理解游戏开发的完整流程具有较高的参考价值。

从技术实现角度看，游戏项目的难点在于：游戏循环与状态管理、资源加载与渲染优化、客户端与服务端的协议同步、以及多平台适配。本项目在这些方面提供了可运行的实现，开发者可以在此基础上进行二次开发或学习研究。

部署说明

1. 下载源码压缩包，解压到本地开发环境。

2. 根据项目类型准备对应的运行环境（Node.js / Go / C# / Unity / Godot 等）。

3. 按照 README 中的步骤配置依赖、数据库和配置文件。

4. 先启动服务端，再运行客户端，即可进入游戏进行测试。

注意：本项目仅供学习研究使用，请勿用于商业或非法用途。

学习价值

对于想进入游戏开发领域的开发者来说，这套源码是一个很好的入门参考。通过阅读代码，可以学习到游戏的核心玩法实现、场景与资源管理、网络协议设计、以及渲染优化等关键技术点。

同时，项目中的代码组织方式和模块划分，也展示了游戏项目在工程化方面的实践经验，值得开发者深入研究和借鉴。理解一个完整游戏项目的架构，对后续开发其他类型游戏也很有帮助。

免责声明

本资源来源于开源社区，仅供学习研究和技术交流使用，请勿用于任何商业或违法违规用途。使用本项目产生的一切后果由使用者自行承担。若涉及第三方权益，请联系删除。