Submission Guidelines

Mod Submission Guidelines

These guidelines define what is expected when submitting new mods to the manifest.

General Requirements

Submissions

• New submissions must be submitted as a pull request to the mod-manifest
• Submit only the latest version of a mod, including every past version isn't necessary and will take longer to review.
  • The reviewer may remove additional versions being added that aren't the latest version.
• Submissions preferably are one mod per PR
  • Faster feedback and review
  • Issues with one mod won't hold up others from being approved and added
  • Simpler and smaller task for the reviewer
  • Updates to information such as the description, category, author info and similar are fine to be grouped together

Schema Correctness

• Submissions must follow both the schemas defined in author-schema.json for author entries and mod-schema.json for each mod entry.

• Mod entries must have correct sha256 hashes for each artifact.

Author and Mod ids

• Ids should follow reverse domain name such as com.example for an author and com.example.ExampleModName for a mod
  • If you don't own a domain, you can use your github username here as well: ExampleUser and ExampleUser.ExampleModName
• Mod ids and harmony ids must match if the mod is using harmony.
  • Using harmony isn't a requirement, if you don't use harmony, specifying a harmony id in the mod is not required.

Versioning

• Mod versions must follow Semantic Versioning and must match the ResoniteMod.Version defined in the mod itself.
• Additionally [assembly: AssemblyVersion("1.0.0")] and [assembly: AssemblyFileVersion("1.0.0")] should match the version defined in the mod exactly.
  • Some build configurations may generate 4-part versions despite being provided 3, similar to [assembly: AssemblyVersion("1.1.1.0")]. These are acceptable when equivalent to the 3-part version with 3-part versions preferred.

Libraries

• Mods must not repackage third-party libraries into their mod dll. Instead they should be added as an external dependency in the manifest or as an additional artifact in the mod entry.

Privacy and Security

Obfuscation

• Mods must not be obfuscated. Mods are audited by inspecting their binaries.

Transparency

• Mods should be clear about what they do. Accurate descriptions, screenshots and documentation are encouraged.
• Mods should be open-source. While not required, it is encouraged to allow for easier auditing. Additionally allows others to contribute or report issues with your mod.

Remote Code and External Assets

• Mods must not download or execute any code from a remote source.
• Mods must not download assets from any non-resonite source.
• Mods may use assets provided by resonite.com and assets in the form of resdb:/// urls.
• Mods may provide settings that enable usage of external assets.
  • An example of this would be a setting for an image uri. The default value still must follow the above (or default to being blank) but allows the user to set their own images.

Resonite Policies and Guidelines

Mods must follow the Resonite Policies and Guidelines. Some significant points from this:

• Do not bypass protections and security, including but not limited to permissions, avatar protections, moderation actions, and bans
• Do not enable asset theft/ripping
• Do not enable harassment
• Do not track users without their explicit consent

This is not an exhaustive list, please read the full policies and guidelines.

Recommended Practices

Performance

• Mods should avoid negatively impacting performance where possible. While not a primary concern, if we notice any potential performance issues or unnecessarily inefficient code, we may ask you to improve it.

Release builds

• Mods should be built in release mode. This can be done by using the Release configuration in Visual Studio or passing -c Release to dotnet build
  • Release builds are smaller in size and allow the compiler to apply more optimizations to your code allowing them to run faster

Logging

• Mods should use the modloader provided logging methods (ResoniteMod.Msg(), ResoniteMod.Warn(), ResoniteMod.Debug(), ResoniteMod.Error()) instead of using Unilog.
  • Using provided logging methods will include the name of the mod [INFO] [ResoniteModLoader/ResoniteTestMod] Example Log so it isn't necessary to include it in your log messages.
• Useful log messages and reasonable log level usage
  • Clean up temporary logging, especially on code that runs frequently to avoid bloat in end user logs.

Mod metadata

• Mods should define their Name/Author/Version directly as strings or by constant values [See Example Mod] instead of referencing their assembly or attributes with reflection.
  • Helps ensure builds using different IDE/compiler versions stay consistent with varied build configurations
  • Easier to verify output directly with more readable code
  • Assembly attributes can be set by constants defined in code without using reflection