MaaPracticeBoilerplate Documentation

MaaFramework aims to build an ecosystem of diverse projects. If your project depends on MaaFramework, it is encouraged (but not required) to use naming conventions like MaaXXX, MXA, or MAX. You are free to choose any name you prefer.

Once your project is ready, you are welcome to add it to the Community Project List in the MaaFramework repository.

To start a new project, use the GitHub template feature. This creates a new repository based on the boilerplate structure.

1. Go to the MaaPracticeBoilerplate repository.
2. Click the Use this template button in the top right corner.
3. Select Create a new repository.
4. Clone your new repository to your local machine:

git clone https://github./<your-username>/<your-project-name>.git

git clone https://github.com/<你的用户名>/<你的项目名称>.git

MaaPracticeBoilerplate is a project template for MaaFramework. Developers can use this template to directly create their own MaaXXX projects.

CRITICAL: Do not clone this repository directly. You should create your own project using the template functionality provided by your Git hosting service (e.g., GitHub's 'Use this template' button) to ensure you have a clean starting point for your own development.

For an optimized development experience, the following VSCode extensions are recommended:

• Maa Pipeline Support: Provides MaaFramework specific features like debugging, screenshots, ROI (Region of Interest) acquisition, and color picking.
• markdownlint: Performs Markdown syntax checking.

The project requires OCR model files for text recognition. You must download and place these files manually in your local environment. Do not upload these files to your GitHub repository, as they are ignored by .gitignore and will be automatically configured by GitHub Actions during the release process.

1. Download the OCR resource files: ppocr_v6.zip.
2. Extract the contents into the assets/resource/model/ocr/ directory.

Your directory structure must look like this:

assets/resource/model/ocr/
├── det.onnx
├── keys.txt
└── rec.onnx

The project uses pre-commit to automatically format code (JSON, YAML, and Markdown) and compress images (PNG) during every commit.

Prerequisites:

• Python installed
• Node.js installed

Installation Steps:

1. Install the pre-commit package via pip.
2. Install the git hooks in your project root.

If pre-commit is not recognized after installation, ensure your pip installation directory is added to your system's PATH.

pip install pre-commit
pre-commit install

Before pushing your first set of changes, ensure your Git identity is configured. After that, you can use standard Git commands to commit and push your work.

Configure identity (only required once):

git config user.name "Your GitHub Nickname"
git config user.email "Your GitHub Email"

Commit and push changes:

git add .
git commit -m "Your commit message"
git push origin HEAD -u

# Configure git info (only needed once)
git config user.name "您的 GitHub 昵称"
git config user.email "您的 GitHub 邮箱"

# Commit changes
git add .
git commit -m "XX 新功能"
git push origin HEAD -u