LethalCompany.Plugin.Sdk 1.1.0-rc.10

LethalCompany.Plugin.Sdk

An MSBuild Sdk for creating Lethal Company mods that:

• Optimizes Build Defaults
• Enables Modern Language Features with PolySharp
• References Publicized Binaries from LethalAPI.GameLibs
• Restores & Resolves References to Thunderstore Dependencies
• Creates Thunderstore Packages with dotnet publish
• Stages Directly to a Thunderstore/r2modman Profile
• And More...

Prerequisites

• MSBuild 17.8.3+
• .NET 8.0+
• VSCode/VS2022+
• Thunderstore/r2modman

Getting Started

Create a Class Library

Create a new Class Library for the plugin:

$ dotnet new classlib -n {NAME}

In the new .csproj, update the Sdk="Microsoft.NET.Sdk" attribute at the top of the file to Sdk="LethalCompany.Plugin.Sdk/{VERSION}", and replace any existing content with metadata about the plugin:

<Project Sdk="LethalCompany.Plugin.Sdk/{VERSION}">
  
  <PropertyGroup>
    <Title>Plugin Example</Title>
    <Description>My example plugin!</Description>
    <PluginId>example.plugin</PluginId>
    <Version>1.0.0</Version>
  </PropertyGroup>

</Project>

Or (recommended)

Create a global.json file in the root of your solution, and specify the LethalCompany.Plugin.Sdk:

{
  "sdk": {
    "allowPrerelease": false,
    "rollForward": "latestMajor",
    "version": "8.0.100"
  },
  "msbuild-sdk": {
    "LethalCompany.Plugin.Sdk": "{VERSION}"
  }
}

In your project file, update the Sdk attribute:

<Project Sdk="LethalCompany.Plugin.Sdk">
  
</Project>

For more information on using MSBuild Sdks, see "How project SDKs are resolved"

Define Plugin

In your project, add a new .cs file to define the BepInEx plugin:

[BepInPlugin(GeneratedPluginInfo.Identifier, GeneratedPluginInfo.Name, GeneratedPluginInfo.Version)]
public sealed class SamplePlugin : BaseUnityPlugin
{
    // ...
}

The Sdk generates a GeneratedPluginInfo class from the metadata provided in your project for usage in code.

The name of the generated class can be changed using the <PluginInfoTypeName /> MSBuild property.

By default, the generated class is internal static, this can be changed using the <PluginInfoTypeModifiers /> MSBuild property.

Publish to Thunderstore

In order to create a Thunderstore Package, the Sdk requires that icon.png and README.md files exist at the project root.

The location of the CHANGELOG.md and README.md files can be changed using the <PluginChangeLogFile /> and <PluginReadMeFile /> MSBuild properties.

In the .csproj of the plugin, provide the metadata used to generate a manifest.json for publishing:

<Project Sdk="LethalCompany.Plugin.Sdk">
  
  <PropertyGroup>
    

    <Description>My example plugin!</Description>
    <ThunderId>ExamplePlugin</ThunderId>
    <ThunderWebsiteUrl>https://example.com</ThunderWebsiteUrl>
    <Version>1.0.0</Version>
  </PropertyGroup>

  <ItemGroup>
    <ThunderDependency Include="ExampleTeam-OtherPlugin" Version="1.0.0" />
  </ItemGroup>

</Project>

The following manifest.json would be generated for the example metadata:

{
  "name": "ExamplePlugin",
  "dependencies": ["BepInEx-BepInExPack-5.4.2100", "ExampleTeam-OtherPlugin-1.0.0"],
  "description": "My example plugin!",
  "version_number": "1.0.0",
  "website_url": "https://example.com"
}

To create a Thunderstore package, use dotnet publish:

$ dotnet publish -c Release
MSBuild version 17.8.3+195e7f5a3 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  ExamplePlugin -> .\bin\Debug\netstandard2.1\ExamplePlugin.dll
  ExamplePlugin -> .\bin\Debug\netstandard2.1\publish\
  Zipping directory ".\bin\Debug\netstandard2.1\publish\" to ".\bin\Debug\netstandard2.1\ExamplePlugin-1.0.0.zi
  p".

Staging Plugins

"Staging" a plugin refers to the process of publishing a plugin directly to a local Thunderstore profile, and is performed by specifiying the PluginStagingProfile MSBuild property when publishing:

dotnet publish -p:PluginStagingProfile="..."

It is recommended to set the <PluginStagingProfile /> MSBuild property in a .csproj.user file.

Specify Thunderstore Dependencies

To specify a dependency on another Thunderstore plugin, use the ThunderDependency item:

<ItemGroup>
  <ThunderDependency Include="ExampleTeam-ExamplePlugin" Version="1.0.0" />
</ItemGroup>

Configure Referenced Assemblies

When a ThunderDependency is specified, the Sdk will restore & resolve assemblies for the dependency.

Assembly resolution can be configured by specifying glob patterns for the ExcludeAssets/IncludeAssets metadata:

<ItemGroup>
  <ThunderDependency Include="ExampleTeam-ExamplePlugin" Version="1.0.0">
    <ExludeAssets>path-to-ignore\*.dll</ExcludeAssets>
  </ThunderDependency>
</ItemGroup>

The Sdk specifies a default ThunderDependency on BepInExPack, specifying one yourself is unnecessary.

When publishing a plugin, the Sdk will use the specified ThunderDependency items to produce a value for the dependencies key of the generated manifest.json.

Restore Plugins During Solution Restore

Due to limitiations in how MSBuild handles solution files, the Sdk is unable restore Thunderstore dependencies when directly restoring a solution (e.g. via dotnet restore example-plugin.sln).

To workaround this, create a Directory.Solution.targets file adjacent to the .sln file, that directly imports Solution.targets from the Sdk:

<Project>

  <Import Project="Solution.targets" Sdk="LethalCompany.Plugin.Sdk" />

<Project>

It is recommended to use global.json when using Directory.Solution.targets to centralize the versioning of LethalCompany.Plugin.Sdk.