Plugin loading - Raytwo/Cobalt GitHub Wiki

Very early support for plugins has been implemented into Cobalt.

What is a "plugin"?

Also known as "code modding", it is an advanced way of modifying the game's logic by writing code in the form of plugins (think DLL files on Windows) to be loaded by Cobalt.

As an example, Cobalt itself can be seen as a more advanced form of plugin, known as a "mod loader". It is the plugin that loads other plugins and help them interact with each other.

How do I make one?

[!IMPORTANT] While efforts have been made to make it accessible to beginners, please keep in mind that this is an advanced topic.
You will be required to know or learn some programming, specifically the Rust language.

Since the topic is fairly complex and requires some guidance, a separate repository exists to provide setup, learning and usage instructions.

[!NOTE] Please keep in mind that everything provided was initially made for Cobalt exclusively.
This means you might run into small quirks when trying to use the Unity or Engage libraries.

If you run into an issue, consider opening an issue or a Pull request on the relevant repository.

How should I distribute them?

Plugins are to be distributed in a regular Cobalt mod by placing the .nro file at the root of the mod's directory.

There are certain conditions tied to the use of our work:

Public plugins

Due to the rapidly changing nature of code modding and the fact that incompatibilities can and WILL arise, you are asked to provide a link to a PUBLIC GitHub/GitLab/... repository alongside your mod and to make it open-source by including an open source license.

This link to your code repository is to be distributed visibly either in the mod's description on the hosting platform and/or in a README file in the downloadable archive (or, if shared outside of hosting platforms, as a separate file if you choose to only upload the .nro file).

Assuming you take from another public codebase, remember to give credits to the original author if needed.

We reserve the right to ask for the takedown of a plugin if it is discovered that they do not abide by these rules after being asked to comply.

The reasons for these rules are as follow:

  • Having a way to maintain your plugin in your stead should you move on from Engage modding.
  • Fix compatibility issues with recent Cobalt/library changes if needed and you cannot/will not do it yourself.
  • Make the community a place for sharing and learning, we do not appreciate hoarding and withholding information for brownie points.
  • If your plugin takes over a key function in Engage to achieve something that multiple people might want to also use, the code can be improved to make it possible.

Private plugins

We are aware that some people might prefer to not distribute their code because they commissioned a plugin for their own use, consider their code "too bad to be seen" or potential other reasons.

[!IMPORTANT] Considering every Engage plugin will make use of Cobalt code in some way, you are granted permission to use the Unity, Engage and CobAPI crates without our explicit consent.
Please be aware that we might still ask to see the code privately if we witness your plugin and consider some features to be useful for the community.

For any such case, the rules are as follow:

  • You are allowed to keep your code private as long as the plugin is not publicly distributed, in which case you'll have to abide by the rules for public plugins.
  • It is also acceptable to not distribute code for a future update publicly until that update is released.
  • Assuming you reused someone else's public code in your private plugin, please ask for their consent beforehand and provide a private access to the code if asked by the original author.

Last changes to these conditions: 12/30/2024