Getting Started

About 3054 wordsAbout 10 min

Getting Started

	Windows	macOS	Linux	Android
System Requirements	Windows 10 and above	Self-test	Self-test	Not recommended
Environment Setup Required	Yes	Yes	Yes	Yes
Emulator Required	Yes	Yes	Emulator or containerized Android	No
Usage	GUI or CLI	GUI or CLI	GUI or CLI	CLI

	Notes
Windows Users	In most cases, please download the x86_64 architecture
Mac Users	M9A supports both Apple Silicon and Intel chip Mac computers But it's more recommended for Intel chip Mac computers to use Mac's built-in multi-system installation of Windows And use Windows version M9A and emulator
Android Users	M9A no longer provides Android version release packages If you are very familiar with mobile phone operations and wish to use Android physical devices, please go to MaaFramework to install it yourself You can refer to Usage Method, and MAA Documentation This method is complex and has certain risks, not recommended for beginner players

Users can skip this section and proceed to step 3, after downloading and extracting the file, to run the dependency installation script. If the script fails to install automatically, then refer to this section.

Launch Method	Windows		macOS		Linux
Launch Method	CLI (MaaPiCli)	GUI (MFAAvalonia)	CLI	GUI	CLI	GUI
Install VCRedist Required	Click vc_redist.x64 to download or install via winget (see below)		No
Install .NET 10 Required	No	Go to .NET official download page to download the corresponding version or install via winget (see below)	No	.NET official download page	No	Same as Mac
Install Python Required	Included in package, no other operations needed				3.10≤python<3.14

1. VCRedist x64

Windows users must install VCRedist x64: This is the basic requirement for running M9A (whether it is the command line version or the graphical interface version).

Detailed Installation Methods

Direct download: Click vc_redist.x64 to download and install
winget installation: Right-click the Windows Start button, select "Command Prompt" or "PowerShell (Administrator)", then paste the following command in the terminal and press Enter:
winget install Microsoft.VCRedist.2017.x64

2. .NET 10

All users using GUI need to download and install .NET 10 suitable for your system.

Detailed Installation Methods

Self-download: Click .NET official download page , select the version suitable for your system to download and install.
Windows macOS Linux
You need to download .NET Desktop Runtime .NET Runtime
Installer x64 dotnet-install.sh
(Windows users only) winget installation: Right-click the Windows Start button, select "Command Prompt" or "PowerShell (Administrator)", then paste the following command in the terminal and press Enter:
winget install Microsoft.DotNet.DesktopRuntime.10

	Windows	macOS	Linux
You need to download	.NET Desktop Runtime	.NET Runtime
Installer	x64	dotnet-install.sh

3. Python

Linux users need to install Python separately.

Details

Your system needs to have Python version ≥ 3.10 installed. This is required for M9A to start and manage its internal environment.
M9A will automatically create and use an independent virtual environment and install the required Python dependency packages (from requirements.txt) when it is run for the first time. You do not need to manually create a virtual environment or install these dependencies.

3. Download the Correct Version

M9A download (update) address: GitHub Releases page. Click the link, then select the latest version archive suitable for your system in the Assets section.

Chinese users can also download at high speed through MirrorChyan.

	Windows	macOS	Linux
You need to download	`M9A-win-x86_64-vXXX.zip`	`M9A-macos-x86_64-vXXX.tar.gz` or `M9A-macos-aarch64-vXXX.tar.gz` depending on your architecture	`M9A-linux-x86_64-vXXX.tar.gz` or `M9A-linux-aarch64-vXXX.tar.gz` depending on your architecture

Method for Mac users to check processor architecture

Click the Apple logo in the top-left corner of the screen.
Select "About This Mac".
In the window that appears, you can see the processor information.
If using Intel X86 processor, please download M9A-macos-x86_64-vXXX.tar.gz
If using Apple Silicon series such as M1, M2, etc. ARM architecture processors, please download M9A-macos-aarch64-vXXX.tar.gz

4. Confirm Emulator and Device Support

	Windows	macOS	Linux	Android
Emulator Support	Supports mainstream emulators	Supports mainstream emulators	Self-test	/
ADB Function Required	Yes	Yes	Yes	Yes
Notes		PlayCover is temporarily not supported

For emulator support details, please refer to MAA documentation. For reference only, please refer to MaaFramework actual support status.

MAA Emulator and Device Support Documentation

Windows macOS Linux Android
Reference Documentation Windows Emulators If your device has Apple Silicon, please refer to:
Mac emulators running on Apple Silicon platform
If your device has Intel chip:
1. Recommended to use Mac's built-in multi-system to install Windows
and refer to Windows section documentation
2. Refer to Mac emulators running on Intel platform Linux Emulators and Containers Android Physical Devices

	Windows	macOS	Linux	Android
Reference Documentation	Windows Emulators	If your device has Apple Silicon, please refer to: Mac emulators running on Apple Silicon platform If your device has Intel chip: 1. Recommended to use Mac's built-in multi-system to install Windows and refer to Windows section documentation 2. Refer to Mac emulators running on Intel platform	Linux Emulators and Containers	Android Physical Devices

5. Correctly Set the Resolution

M9A supports mainstream emulators and PC clients, but you need to set the resolution of the emulator and PC client to meet the operating requirements. The resolution for the emulator and PC client should be landscape 16:9 ratio, with a recommended (and minimum) resolution of 1280x720. Running errors caused by not meeting this requirement will not be resolved.

International Version PC client

Can't change to 16:9 ratio when using the International Version PC client? Use the PC client initialization script.

Details

Open the script
Locate ModifyPCRegistry.bat (Game PC registry modification) in the M9A root directory
Double-click to run
Step 1
After opening, enter 1 in the command line
As shown below
Step 2
Enter a/b/c/d according to the resolution you want to select
As shown below

Warning

Note that after changing the resolution, the emulator homepage should be horizontal (tablet version), don't select vertical (mobile version)!

6. Getting Started

M9A supports both command line (MaaPiCli) and graphical interface (MFAAvalonia), but before use, you need to extract the archive correctly and change the in-game display language to Simplified Chinese

Important

Don't run the program directly from the compression software!

For general users, it's recommended to use M9A through MFAAvalonia.

Windows

Confirm complete extraction and ensure M9A is extracted to an independent folder. Recommended extraction path like: D:\M9A. Except for closing the built-in administrator-approved Administrator account, please do not extract M9A to paths requiring UAC permissions such as C:\, C:\Program Files\, etc.

After extraction, run MaaPiCli.exe or MFAAvalonia.exe

macOS

Details

Open terminal, extract the distributed archive:
Option 1: Extract to system directory (requires administrator privileges)
sudo mkdir -p /usr/local/bin/M9A
sudo tar -xzf <downloaded M9A archive path> -C /usr/local/bin/M9A
Option 2: Extract to user directory (recommended, no sudo required)
mkdir -p ~/M9A
tar -xzf <downloaded M9A archive path> -C ~/M9A
Enter the extraction directory and run the program:
cd /usr/local/bin/M9A
./MaaPiCli
If you want to use the graphical interface, follow step 2 but execute MFAAvalonia instead of MaaPiCli.
⚠️Gatekeeper security prompt handling:
In macOS 10.15 (Catalina) and later, Gatekeeper may prevent unsigned applications from running.
If you encounter errors such as "Cannot open because the developer cannot be verified", please choose one of the following solutions:
# Solution 1: Take MaaPiCli as an example to remove the quarantine attribute (recommended, subject to the actual path)
sudo xattr -rd com.apple.quarantine /usr/local/bin/M9A/MaaPiCli
# Or user directory version: xattr -rd com.apple.quarantine ~/M9A/MaaPiCli

# Solution 2: Add to Gatekeeper whitelist
sudo spctl --add /usr/local/bin/M9A/MaaPiCli
# Or user directory version: spctl --add ~/M9A/MaaPiCli

# Solution 3: Process the entire directory at once
sudo xattr -rd com.apple.quarantine /usr/local/bin/M9A/*
# Or user directory version: xattr -rd com.apple.quarantine ~/M9A/*

Linux

Same as macOS, download the corresponding version archive, extract and run MaaPiCli or MFAAvalonia.

7. Configure M9A

You can configure M9A according to your needs for a better user experience.

Some configuration items may cause M9A to run abnormally when configured incorrectly or not configured, so it's recommended to read this section before starting to use.

This chapter will mainly introduce how to configure M9A through the graphical interface (MFAAvalonia). If you are using the command line version (MaaPiCli), please refer to MaaPiCli Operation Instructions.

The following demonstrations are for reference only, please refer to the actual software situation.

First Launch

MFA Main Interface Display

In the main interface, you can see six major sections: Resource Type Task List Task Settings Task Description Connection Log.

Caution

When starting MFA for the first time, M9A will initialize. After the Log section shows "AgentServer Started" until you see "All tasks completed", please do not click Stop Tasks.

When M9A is running tasks, some settings in the main interface cannot be modified, such as the Connection section. At this time, you can first enter the global settings interface to configure.

M9A Settings Interface

Click the gear button in the lower left corner of the main interface to enter the M9A settings interface.

Users using MFA update-related functions should configure Update Settings. Users with multi-instance and auto-start needs should configure Startup Settings.

Update Settings

Resource Download Source is used to specify the download source used for updates. CDK refers to MirrorChyan CDK, Token refers to GitHub Personal Access Token.
When configured incorrectly, M9A will not be able to use update-related functions normally.

Details

Resource Download Source
Uses MirrorChyan by default.
Users who haven't purchased MirrorChyan should change to GitHub.
CDK or Token
Users updating through MirrorChyan should fill in CDK. About MirrorChyan
Users updating through GitHub can fill in Token to improve GitHub API access rate limits. Token acquisition method 1 method 2

Github source rate limit causing update failure

Startup Settings

Software Path is used to specify the executable file path of the emulator. When configured incorrectly, M9A will not be able to start the emulator correctly.
Additional Commands is used to specify parameters when the emulator starts. Generally speaking, Additional Commands is only used to configure emulator multi-instance numbers.

Details

Software Path
MuMu 12 Emulator Reference
Path Format
MuMu 12 Emulator
Below 5.0 {Installation Directory}\shell\MuMuPlayer.exe
MuMu 12 Emulator
5.0 and above {Installation Directory}\nx_device\12.0\shell\MuMuNxDevice.exe
Additional Commands
X is the multi-instance number
Parameter Format Example
MuMu Emulator -v X -v 0
LDPlayer index=X index=0
MuMu Emulator Automatic Path Acquisition Method
Ensure there is a emulator shortcut with 1999 application installed on the desktop.
Click the icon to the right of the Software Path input box to enter the file selection interface, select the 1999 shortcut on the desktop, and the path will be automatically filled in.

	Path Format
MuMu 12 Emulator Below 5.0	`{Installation Directory}\shell\MuMuPlayer.exe`
MuMu 12 Emulator 5.0 and above	`{Installation Directory}\nx_device\12.0\shell\MuMuNxDevice.exe`

	Parameter Format	Example
MuMu Emulator	`-v X`	`-v 0`
LDPlayer	`index=X`	`index=0`

M9A Main Interface

At least configure Resource Type and Connection. When configured incorrectly, M9A cannot be used normally.

Resource Type

Details

You need to select the 1999 server installed in the emulator.
Currently supports: Official Server, Bilibili Server, International Server (EN), International Server (JP), OPPO Server, Xiaomi Server.

Connection

M9A requires correct ADB connection to execute tasks on the target emulator. In most cases, you only need to keep only the target emulator running and click "Refresh" to complete the connection. If you need to manually configure ADB parameters, please refer to Connection Settings.

Illustration

Details

Current Controller
Shows the currently connected ADB controller (emulator and ADB address).
Interface Button Descriptions
Click Custom: Modify ADB parameters (generally no manual modification required).
Click Refresh: Re-detect all running emulators.
Connection Status: Green indicates connected.

When using the International Server PC client, simply click the PC icon in the connection area to automatically detect and connect to any open PC client window.

Warning

When connecting to a PC, run M9A in administrator mode, and do not minimize the game window!

Illustration

Task List

Illustration

Details

The checkbox before the task name is used to enable/disable tasks
Right-clicking the checkbox will execute that task once
Click the add task button in the upper right corner to add tasks not visible in the current list or repeatedly add existing tasks
Click the button to the right of the task to view Task Settings and Task Description
Drag task names to adjust task order

Important

Most tasks need to be configured correctly before use, and some tasks also need to be executed in specific scenarios according to task descriptions. Before enabling tasks, please ensure you have read and understood the Task Description for that task, and configure Task Settings according to actual situations. For more information about tasks, please refer to Feature Introduction.

Settings

pip Settings

M9A supports configuring pip installation related settings through the config/pip_config.json file. Generally, you don't need to modify this file unless you have special requirements.

config/pip_config.json Example

{
  "enable_pip_install": true,  // Whether to enable pip installation, default true
  "mirror": "https://pypi.tuna.tsinghua.edu.cn/simple",  // Mirror source
  "backup_mirror": "https://mirrors.ustc.edu.cn/pypi/simple"  // Backup mirror sources
}

Resource Hot Update Configuration

M9A supports configuring hot update settings for certain resources (such as activity opening times) via the config/hot_update.json file.

config/hot_update.json Example

{
  "enable_hot_update": true  // Whether to enable hot update for certain resources, default is true
}

Getting Started

Getting Started

Prerequisites

1. Confirm System Version

2. Install Runtime Environment

1. VCRedist x64

2. .NET 10

3. Python

3. Download the Correct Version

4. Confirm Emulator and Device Support

5. Correctly Set the Resolution

International Version PC client

6. Getting Started

Windows

macOS

Linux

7. Configure M9A

First Launch

M9A Settings Interface

M9A Main Interface

Settings

pip Settings

Resource Hot Update Configuration