Getting Started

About 3439 wordsAbout 11 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 (MFAA)	GUI (MXU)	CLI	GUI (MFAA)	GUI (MXU)	CLI	GUI (MFAA)	GUI (MXU)
Requires VCRedist	Download from vc_redist.x64 or install via winget (see below)			No
Requires .NET 10	No	Go to the official .NET download page to download the appropriate version or install via winget (see below)	No	No	Official .NET download page	No	No	Same as Mac	No
Requires Python	The archive comes with it, no additional steps required						Requires Python 3.10 ≤ version < 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 of the MFA graphical interface 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

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/MXU), 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 is recommended to use M9A via MFAAvalonia or MXU.

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 M9A.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
./M9A
If you want to use the graphical interface, follow step 2 and run the M9A program.
⚠️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 M9A as an example to remove the quarantine attribute (recommended, subject to the actual path)
sudo xattr -rd com.apple.quarantine /usr/local/bin/M9A/M9A
# Or user directory version: xattr -rd com.apple.quarantine ~/M9A/M9A

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

# 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 of the archive, extract it, and then run M9A.

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/MXU). 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

Main Interface Display

MFA main interface:
MXU main interface:

In the MFA main interface, you can see seven major sections: Resource Type Task List Task Settings Task Description Connection Log Live View. In the MXU main interface, you can see five main sections: Task List Task Management Connection Settings Live View Run 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), International Server (KR), Hong Kong, Macau, and Taiwan Server, OPPO Server, Xiaomi Server, Huawei 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.

Schematic Diagram

MFA diagram:
MXU diagram:

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 Reconnect: Reconnect to the selected emulator.
Click Refresh: Re-detect all running emulators.
Connection Status: Green indicates connected.

When using the International Server PC client, select PC in the Controller Type section of the connection area to automatically detect and connect to an open PC client window.

Schematic Diagram

MFA connection diagram:
MXU connection diagram:

Warning

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

For Mac users using PlayCover, select PlayCover in the Controller Type section of the connection area. For details, please refer to PlayCover Usage.

Illustration

Task List

Schematic Diagram

MFA task list diagram:
MXU task list diagram:

Details

How to Use the MFA Task List
The checkbox before the task name enables/disables the task.
Right-click the checkbox to run the task once.
Click the Add Task button in the top right corner to add tasks not currently visible in the list or to duplicate existing tasks.
Click the button on the right side of a task to view Task Settings and Task Description.
Drag the task name to reorder tasks.
How to Use the MXU Task List
The checkbox before the task name enables/disables the task.
Click the Add Task button in the bottom left corner to add tasks not currently visible in the list or to duplicate existing tasks.
Right-click a task to open the management menu.
Left-click a task to expand task options and view Task Settings and Task Description.
Press and hold the button on the left side of a task to drag and reorder tasks.

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