MTGOSDK 0.0.5-preview-20241124.5

MTGOSDK

<a href="#overview">Overview</a> | <a href="#documentation">Documentation</a> | <a href="#installation">Installation</a> | <a href="#building-this-project">Building</a> | <a href="#license">License</a> | <a href="#disclaimer">Disclaimer</a>

Package	Latest Version	About
MTGOSDK		Provides high-level APIs for interacting with the MTGO client.
MTGOSDK.MSBuild		MSBuild library for design/compile-time code generation.
MTGOSDK.Win32		Contains native Win32 API definitions used by the SDK.

What is MTGOSDK?

MTGOSDK is a collection of C# libraries for interfacing with the Magic: The Gathering Online (MTGO) client. It provides common APIs for reading from and interacting with the MTGO client in real-time, enabling developers to build tools and applications that can interact with any running instance of MTGO.

These APIs cover a wide range of functionality of the MTGO client, including:

• Chat: Stream and read chat messages and game logs from any channel.
• Collection: Query the MTGO collection for cards, decks, binders, etc.
• Events: Subscribe to and read state changes and events from the MTGO client.
• Interface: Interact with and mock MTGO client's user interface elements.
• Play: Query events and read the current game state, including from replays.
• Settings: Read, export, and import user preferences and settings.
• Trade: Query trade offers, trade history, and any current trade sessions.
• Users: Query user profiles, including friends and other players.
• and more...

You can also check out the FAQ for common questions about the SDK, and the project's examples for demo applications built with the SDK.

Overview

This SDK contains several lightweight packages (with minimal dependencies outside of the .NET runtime) designed to be easy to use and integrate into existing applications. They are built entirely in C# on top of the .NET Core runtime and are compatible with .NET 5.0 and later.

Below is a brief overview of the packages included in the SDK:

MTGOSDK — provides an API that exposes high-level abstractions of MTGO functions to read and manage the state of the client. This works by injecting the Microsoft.Diagnostics.Runtime (ClrMD) assembly into the MTGO process and bootstrapping a debugger interface to inspect objects from process memory. These objects are compiled by the .NET runtime to enable reflection on heap objects as if they were live objects.

MTGOSDK.MSBuild — a MSBuild library that manages the code-generation of the SDK. This is used to generate the SDK's API bindings and reference assemblies for the latest builds of MTGO. At design-time, this builds reference assemblies containing only the public types and members from the MTGO client. These assemblies can be regenerated as the MTGO client is updated to provide the latest API definitions for use in the SDK.

MTGOSDK.Win32 — a library containing Win32 API definitions and helper functions used by the SDK. These are used to provide a more idiomatic C# API for Win32 functions and to ensure consistent API behavior across different Windows versions. Additionally, this library serves as a reference for using Win32 APIs that are not yet implemented as part of the .NET Framework. This library is not intended to be used directly by consumers of the SDK.

Documentation

Refer to the SDK documentation for more in-depth information about the SDK's APIs.

The documentation is organized into the following sections:

• Getting Started — a quick guide to getting started with the SDK.
• API Reference — a detailed reference of the SDK's APIs and classes.
• Examples — a collection of example applications built with the SDK.
• FAQ — frequently asked questions about the SDK.

For more information on the SDK's design and architecture, see the architecture docs.

Installation

[!NOTE] MTGOSDK follows the Abseil Live at Head philosophy.

While regular releases are tagged and published on GitHub and NuGet, we recommend building the SDK from source to ensure you have the latest features and bug fixes, and so that newer versions of MTGO can be targeted and validated by the SDK at build-time. This helps catch and fix any Hyrum's Law dependency problems on an incremental basis between different versions of MTGO and the SDK.

Follow the local package feed instructions to reference local builds of MTGOSDK in your project.

The MTGOSDK is available as a NuGet package on the NuGet Gallery, and on GitHub Packages. You can install the package using the NuGet Package Manager in Visual Studio, or with the .NET Core CLI.

To install the MTGOSDK package, you can use any of the below methods:

With Visual Studio

From within Visual Studio, you can use the NuGet Package Manager GUI to search for and install the MTGOSDK NuGet package. Alternatively, you can use the Package Manager Console to install the package:

Install-Package MTGOSDK

With the .NET Core CLI

If you are building with .NET Core command line tools, you can use the below command to add the MTGOSDK package to your project:

dotnet add package MTGOSDK

Local Package Feed

When building the project locally, you can use the SDK's local package feed to reference the development build. This feed is created by the SDK build process and is created under the packages directory.

To reference the local package feed created by the SDK, you can add the following to the NuGet.config file in the root of your project:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    
    <add key="SDK Feed" value="MTGOSDK/packages" />
  </packageSources>
  <packageSourceMapping>
    
    <packageSource key="SDK Feed">
      <package pattern="MTGOSDK" />
      <package pattern="MTGOSDK.MSBuild" />
      <package pattern="MTGOSDK.Win32" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

To reference these packages, you can use the * wildcard specifier in your project file:

<PackageReference Include="MTGOSDK"
                  Version="*" />
<PackageReference Include="MTGOSDK.MSBuild"
                  Version="*"
                  PrivateAssets="All" />
<PackageReference Include="MTGOSDK.Win32"
                  Version="*" />

Building this Project

[!NOTE] This project requires the .NET 8 SDK to be installed with Visual Studio 2017 or newer. This can also be installed in Visual Studio using the Visual Studio Installer.

To build this project, run either of the below commands from the root of the repository:

# Build using the .NET Core CLI
dotnet build -c Release

# Build using MSBuild in Visual Studio
msbuild /t:Build /p:Configuration=Release

The MTGOSDK project will automatically build reference assemblies for the latest version of MTGO, even if no existing MTGO installation exists. This helps ensure that the SDK is always up-to-date with the latest versions of MTGO.

To build the project in watch-mode (and rebuild the solution as it picks up changes), you can use the dotnet watch command targeting the MTGOSDK project instead of the solution file:

# Automatically rebuild MTGOSDK when file changes are detected
$ dotnet watch --project MTGOSDK/MTGOSDK.csproj build -c Release

This will also pick up changes to dependent MTGOSDK.MSBuild and MTGOSDK.Win32 projects as well. As build evaluation is rooted from the MTGOSDK .csproj file, all logs from the build will be stored under the MTGOSDK/logs directory.

Acknowledgements

MTGOSDK's snapshot runtime uses the Microsoft.Diagnostics.Runtime (ClrMD) library under the hood. We're grateful to the ClrMD maintainers for their support and their work in providing a powerful library for inspecting and debugging .NET applications.

MTGOSDK's remoting API is also based on an early version of RemoteNET, which forms the backbone of the SDK's client-server architecture.

License

This project is licensed under the Apache-2.0 License.

Disclaimer

This project is protected under U.S., Section 103(f) of the Digital Millennium Copyright Act (DMCA) (17 USC § 1201 (f)) protections for reverse-engineering for the purpose of enabling ‘interoperability’.

Section 12.1(b) of MTGO's End User License Agreement (EULA) prohibits any modification, reverse engineering, or decompilation of the client 'except to the extent that such restriction is expressly prohibited by applicable law'.

However, for such purposes protected under Section 103(f) of the DMCA, this EULA clause is statutorily preempted and rendered null and void; see also ML Genius Holdings LLC v. Google LLC, No. 20-3113 (2d Cir. Mar. 10, 2022). All other provisions of the EULA remain in full force and effect unless otherwise prohibited by law.

This is not legal advice. Consult with a legal professional on your specific situation.