modio / modio-unity-legacy

Unity Plugin for integrating mod.io - a modding API for game developers
https://mod.io
MIT License
66 stars 16 forks source link
api engine mod modding plugin sdk unity

NOTE: This codebase is now deprecated.

The latest version of the mod.io Unreal Plugin can be found at https://github.com/modio/modio-unity.

mod.io

Legacy mod.io Unity Plugin

License Discord Master docs Unity 3D

Welcome to mod.io Unity Plugin. It allows game developers to easily control the browsing and installation of User-Generated Content in UGC-supported games. The C# interface built on the Unity Engine provides an easy way of connecting to the mod.io API. We have a test environment available which offers developers a private sandbox to try the Unity Plugin out.

Features

Installation

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

Asset Store or .unitypackage

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.

Alternatively, you can download an archive of the code using GitHub's download feature and place it in the Assets/Plugins directory within your Unity project.

Getting started

  1. Implement support for user-generated content in your project. Maps, skins, or game modes are often a good place to start.
  2. Set up your game profile on mod.io (or our private test environment) to get your game ID and API key.
  3. Add the plugin to your game using the installation instructions above.
  4. Drop the ModBrowser prefab into your menu scene, or adapt the Example Scene for your purposes.
  5. Input your ID and API key by selecting "Plugin Settings" on the ModBrowser component inspector, or under the Tools/mod.io/Edit Settings menu item
  6. In your code, make a call to ModManager.QueryInstalledModDirectories() to get a list of mod data your player has installed (read our wiki for detailed instructions)
  7. 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 --
APIClient.GetTermsOfUse(UserPortal.GOG,
                        (termsInfo) => DisplayTermsOfUse(termsInfo),
                        (e) => OnError(e));

bool hasUserConsentedToTermsOfUse = true;

UserAccountManagement.AuthenticateWithGOGEncryptedAppTicket(ticketData, ticketSize,
                                                            hasUserConsentedToTermsOfUse,
                                                            (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));

LocalUser.instance = new LocalUser();
LocalUser.OAuthToken = receivedOAuthToken;

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

LocalUser.Profile = userProfile;
LocalUser.Save();

Manage Subscriptions

// -- Sub/Unsubscribe --
UserAccountManagement.SubscribedToMod(modId);
UserAccountManagement.UnsubscribeFromMod(modId);

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

int[] modIds = Utility.MapProfileIds(subscribedMods);
LocalUser.SubscribedModIds = new List<int>(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));

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:

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: 

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.

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.