MaaFramework.Binding.CSharp

✨ C# Binding for MaaFramework ✨

💫 A universal interop API wrapper 💫

English | 简体中文

Articles

• Overview of Wrapper and Api

Quick Start

System Requirements

Your system must meet minimum requirements to use MaaFramework.Binding.CSharp. The framework may work on other platforms not listed here.

OS Version	Minimum Requirement / Limitation
Windows 10+	Limited by .NET 7.0
macOS 12+	Limited by MaaFramework
Linux Ubuntu 23.10+	libc6 2.38+ required and more
Android	Untested

• Architecture: x64, arm64

Dependencies

Required dependencies for MaaFramework.Binding.CSharp:

Platform	Package ID	Dependency Link
Windows	Maa.Framework Maa.Framework.Runtimes Maa.Framework.Runtime.win-arm64 Maa.Framework.Runtime.win-x64	Visual C++ Redistributable

Resource Setup

Refer to MaaFramework docs: English | 简体中文

See SampleResource for implementation.

Package Installation

Package ID	Description
Maa.Framework	Meta package (Native + Runtimes)
Maa.Framework.Native	Meta package (Binding.Native + AgentBinary)
Maa.Framework.Binding	Abstraction layer
Maa.Framework.Binding.Native	Native API wrapper
Maa.Framework.Runtimes Platform-specific packages	Prebuilt MaaFramework binaries. Android packages excluded by default.
Maa.AgentBinary	Prebuilt Agent binaries

Stable Releases

dotnet add package Maa.Framework --prerelease

Nightly Builds

• Add package

  dotnet add package Maa.Framework --prerelease -s https://maaxyz.github.io/pkg/nuget/index.json

• Configure NuGet sources

  • .csproj

    <PropertyGroup>
    <RestoreSources>$(RestoreSources);https://api.nuget.org/v3/index.json;https://maaxyz.github.io/pkg/nuget/index.json</RestoreSources>
    </PropertyGroup>

  • NuGet.config

    See sample configuration for implementation examples; Refer to nightly builds guide for full details.

RID Specification

Supported Runtime IDs are listed here.

For example, on the Windows platform, you need to manually reference the following packages:

• Maa.Framework.Native
• Maa.Framework.Runtime.win-arm64
• Maa.Framework.Runtime.win-x64

Code Example

Pre-work: adb connect HOST[:PORT]

Start quickly from the powershell or bash script in the sample folder.

// using MaaFramework.Binding;

MaaToolkit.Shared.Config.InitOption(".cache");

var devices = MaaToolkit.Shared.AdbDevice.Find();
if (devices.IsEmpty)
    throw new InvalidOperationException();

using var maa = new MaaTasker
{
    Controller = devices[0].ToAdbController(),
    Resource = new MaaResource("../../src/MaaFramework.Binding.UnitTests/SampleResource"),
    DisposeOptions = DisposeOptions.All,
};

if (!maa.IsInitialized)
    throw new InvalidOperationException();

maa.AppendTask("EmptyNode")
   .Wait()
   .ThrowIfNot(MaaJobStatus.Succeeded);

Console.WriteLine("EmptyNode Completed");

Custom

// using MaaFramework.Binding.Buffers;
// using MaaFramework.Binding.Custom;

var nodeName = "MyCustomTask";
var param = $$"""
{
  "{{nodeName}}": {
      "recognition": "Custom",
      "custom_recognition": "MyRec",
      "custom_recognition_param": {
          "my_rec_key": "my_rec_value"
      },
      "action": "Custom",
      "custom_action": "MyAct",
      "custom_action_param": {
          "my_act_key": "my_act_value"
      }
  }
}
""";

// Register custom components
maa.Resource.Register(new MyRec());
maa.Resource.Register(new MyAct());
maa.AppendTask(nodeName, param)
    .Wait()
    .ThrowIfNot(MaaJobStatus.Succeeded);

internal sealed class MyRec : IMaaCustomRecognition
{
    public string Name { get; set; } = nameof(MyRec);
    public bool Analyze(in IMaaContext context, in AnalyzeArgs args, in AnalyzeResults results)
    {
        Console.WriteLine($"Enter {Name}");
        return results.Box.TrySetValues(0, 0, 100, 100)
            && results.Detail.TrySetValue("Hello World!");
    }
}
internal sealed class MyAct : IMaaCustomAction
{
    public string Name { get; set; } = nameof(MyAct);
    public bool Run(in IMaaContext context, in RunArgs args, in RunResults results)
    {
        Console.WriteLine($"Enter {Name}");
        return true;
    }
}

Additional Resources

• To view implementation examples with identical functionality to the main MaaFramework repository, visit the Sample Directory.
• For code examples covering the vast majority of framework features, explore the Unit Test Suite.

Best Practices

• MFAWPF MFA Task Manager A Universal GUI based on MAA's new architecture. Powered by MaaFramework.

Documentation

We have written detailed documentation comments in source code files.

You can also visit API Reference and Unit Tests for more information.

If you still intend to use a API Reference specific to your preferred version of MaaFramework.Binding.CSharp, you may refer to the releases page of the project and download the attached docs.zip file.

Contributing

We welcome contributions to the MaaFramework.Binding.CSharp. If you find a bug or have a feature request, please open an issue on the GitHub repository. If you want to contribute code, feel free to fork the repository and submit a pull request.

License

MaaFramework is open-sourced under the LGPL-3.0 license.

Discussion

• QQ Group: 595990173