Unity Engine Plugin

Welcome to mod.io Unity Plugin. It allows game developers to easily control the browsing and installation of mod files in their games. It provides a C# interface built on the Unity Engine to connect to the mod.io API. We have a test environment available which offers developers a private sandbox to try the Unity Plugin out.

Features

• Platform agnostic (support 1 click mod installs on Steam, Epic Games Store, Discord, GOG, itch.io and even consoles in the future)
• Clientless (it has no other dependencies and works behind the scenes in your game)
• Powerful search, filtering and tagging of mods
• C# interface built on the Unity Engine for connecting to the mod.io API
• Players can activate / deactivate mods they are subscribed to
• Customizable mod browsing UI

Installation

Requires Unity 2017.3 or later. Tested on Windows, and MacOS.

There are several ways to install the mod.io Unity Plugin:

Package Manager

The best way is to install this library as a Git package using the Package Manager. First, make sure that you to have Git installed and available in your system's PATH. After that you need to add the following line to your project's manifest.json:

"com.modio.unityplugin": "https://github.com/modio/UnityPlugin.git",

It should look like this, notice the comma at the end of the line:

{
  "dependencies": {
    "com.modio.unityplugin": "https://github.com/modio/UnityPlugin.git",
    "com.unity.package-manager-ui": "1.0.0",
    "com.unity.modules.ai": "1.0.0",
    "com.unity.modules.animation": "1.0.0",
    ...
  }
}

If you don't want to use Git, you can download this library as an archive and install it as a local package.

Asset Store or .unitypackage

The other way is to import a package from the Asset Store or the Releases page. If you have any previous versions of the plugin installed, it is highly recommended to delete them before importing a newer version.

Getting started

If you are a game developer, first step is to add mod support to your Unity game. Once mod support is up and running, create your games profile on mod.io, to get an API key and access to all functionality mod.io offers. Next, download the latest UnityPackage release from Github or Unity Asset Store and unpack it into your project, then head over to the GitHub Wiki and follow the guides to get it running within your game.

1. Download the Unity package and import it into your project
2. Drop the _ModBrowser prefab into your menu scene, or adapt the ExampleScene for your purposes
3. Set up your game on mod.io (or our private test environment) to get your game ID and API key
4. Input your ID and API key by selecting "Plugin Settings" on the ModBrowser component inspector, or under the mod.io/Edit Settings menu item
5. In your code, make a call to ModManager.GetInstalledModDirectories() to get a list of mod data your player has installed (read our wiki for detailed instructions)
6. Setup complete! Join us on Discord if you have questions or need help.

All mods submitted to mod.io will be automatically fetched and managed by the plugin, and are instantly downloadable and testable.

Usage

Browse Mods

// -- Get as many mods as possible (unfiltered) --
APIClient.GetAllMods(RequestFilter.None,
                     null,
                     (r) => OnModsReceived(r.items),
                     (e) => OnError(e));


// -- Get a specified subset of filtered mods --
RequestFilter filter = new RequestFilter();
filter.sortFieldName = API.GetAllModsFilterFields.dateLive;
filter.isSortAscending = false;
filter.fieldFilters[API.GetAllModsFilterFields.name]
	= new StringLikeFilter() { likeValue = "mod" };

APIPaginationParameters pagination = new APIPaginationParameters()
{
	offset = 20,
	limit = 10,
};

APIClient.GetAllMods(filter
                     pagination
                     (r) => OnModsReceived(r.items),
                     (e) => OnError(e));

User Authentication

// -- Authenticate using external service using wrapper functions --
UserAccountManagement.AuthenticateWithGOGEncryptedAppTicket(ticketData, ticketSize,
                                                            (userProfile) => OnUserAuthenticated(userProfile),
                                                            (e) => OnError(e));



// -- Authenticate via email-flow manually using APIClient --
APIClient.SendSecurityCode("player@email_address.com",
                           (message) => OnSecurityCodeSent(),
                           (e) => OnError(e));

APIClient.GetOAuthToken(securityCodeFromEmail,
                        (token) => OnTokenReceived(token),
                        (e) => OnError(e));

UserAuthenticationData.instance = new UserAuthenticationData()
{
	token = receivedOAuthToken,
};

APIClient.GetAuthenticatedUser((userProfile) => OnProfileReceived(userProfile),
                               (e) => OnError(e));

UserAuthenticationData userData = UserAuthenticationData.instance;
userData.userId = userProfile.id;
UserAuthenticationData.instance = userData;

CacheClient.SaveUserProfile(userProfile);

Manage Subscriptions

// -- Sub/Unsubscribe --
APIClient.SubscribedToMod(modId,
                          (modProfile) => OnSubscribed(modProfile),
                          (e) => OnError(e));
APIClient.UnsubscribeFromMod(modId,
                             () => OnUnsubscribed(),
                             (e) => OnError(e));

// -- Fetch and Store ---
APIClient.GetUserSubscriptions(RequestFilter.None,
                               null,
                               (subscribedMods) => OnSubscriptionsReceived(subscribedMods),
                               (e) => OnError(e));

int[] modIds = Utility.MapProfileIds(subscribedMods);
ModManager.SetSubscribedModIds(modIds);

// -- Download, Update, and Install Subscribed Mods --
activeSceneComponent.StartCoroutine(ModManager.DownloadAndUpdateMods_Coroutine(modIds,
                                                                               () => OnCompleted()));

Submit Mods

// -- Changes to a Mod Profile --
EditableModProfile modEdits = EditableModProfile.CreateFromProfile(existingModProfile);
modEdits.name.value = "Updated Mod Name";
modEdits.name.isDirty = true;
modEdits.tags.value = new string[] { "campaign" };
modEdits.tags.isDirty = true;

ModManager.SubmitModChanges(modId,
                            modEdits,
                            (updatedProfile) => OnChangesSubmitted(updatedProfile),
                            (e) => OnError(e));

// -- Upload a new build --
EditableModfile modBuildInformation = new EditableModfile();
modBuildInformation.version.value = "1.2.0";
modBuildInformation.version.isDirty = true;
modBuildInformation.version.changelog = "Changes were made!";
modBuildInformation.version.isDirty = true;
modBuildInformation.version.metadatBlob = "Some game-specific metadata";
modBuildInformation.version.isDirty = true;

ModManager.UploadModBinaryDirectory(modId,
                                    modBuildInformation,
                                    true, // set as the current build
                                    (modfile) => OnUploaded(modfile),
                                    (e) => OnError(e));

Benefits

mod.io offers the same core functionality as Steamworks Workshop (1 click mod installs in-game), plus mod hosting, moderation and all of the critical pieces needed. Where we differ is our approach to modding and the flexibility a REST API offers. For example: 

• Our API is not dependent on a client or SDK, allowing you to run mod.io in many places such as your homepage and launchers
• Designing a good mod browsing UI is hard, our plugin ships with a UI built in to save you a lot of effort and help your mods stand out
• We don’t apply rules globally, so if you want to enable patronage, sales or other experimental features, reach out to discuss
• Our platform is built by the super experienced ModDB.com team and is continually improving for your benefit
• Your community can consume the mod.io API to build modding fan sites or discord bots if they want
• Communicate and interact with your players, using our built-in emailer

Large studios and Publishers

A private white label option is available to license, if you want a fully featured mod-platform that you can control and host in-house. Contact us to discuss.

Dependencies

The mod.io Unity Plugin requires the functionality of two other open-source Unity plugins to run. These are included as libraries in the UnityPackage in the Plugins directory, or in the repository under third_party:

• Json.Net for improved Json serialization. (GitHub Repo || Unity Asset Store Page)
• DotNetZip for Unity to zip and unzip transmitted files. (GitHub Repo)

Contributions Welcome

Our Unity plugin is public and open source. Game developers are welcome to utilize it directly, to add support for mods in their games, or fork it for their games customized use. Want to make changes to our plugin? Submit a pull request with your recommended changes to be reviewed.

Other Repositories

Our aim with mod.io, is to provide an open modding API. You are welcome to view, fork and contribute to our other codebases in use:

• Design is public and open source, the repository can be found here.
• API documentation is public and open source, the repository can be found here.
• Browse engine tools, plugins and wrappers created by the community, or share your own.
• Unreal Engine 4 plugin, easily manage the browsing and install of mods in Unreal Engine 4 games
• Python wrapper, a python wrapper for the mod.io API
• Rust wrapper, rust interface for mod.io
• And more...