Code Mod Core Migration Guide - EverestAPI/Resources GitHub Wiki

This page will walk you through the process of updating your non-Core code mod to correctly build against a .NET Core Everest install. For instructions on how to set up a Core-only mod, please see the Code Mod Setup wiki page.

Setting up a legacyRef install

Non-Core mods can't directly build against the Core-ified game binaries themselves. Instead, they have to build against a minimal copy of the game files which have been modded by a non-Core version of Everest. This set of files is referred to as the "legacyRef Install", and .NET Core Everest comes with a built-in utility for setting it up.

Navigate to the main menu, and enter the mod options menu. Within the Everest-specific settings, you should find a button like this:

legacyref-button

Once pressed, Everest will set up the legacyRef install in the legacyRef folder within the game's files. Pressing it again later will update it to the latest non-Core Everest version currently available.

If you are creating a new mod, you are done now! You can continue with the Code Mod Setup wiki page from here.

The following sections are only relevant for existing mods, which might have to be updated to properly work with legacyRef installs.

Updating the template csproj

Note

The following section assumes that you used the CelesteMod.Templates dotnet template 🔗 created by Samah/swoolcock. If not, you will have to update the csproj on your own - see the later section for more details. Potentially consider switching to the template if you do not want to deal with the hassle of maintaining your own project structure.

Projects created with a recent version of the CelesteMod.Templates dotnet template will automatically recognize .NET Core Everest installs, and automatically use legacyRef installs when available. If your project has been created before this update, follow the following steps:

Update your local templates (so that future projects will use the updated template):

dotnet new update

Locate and open your mod's .csproj file in your favorite editor - it should simply be called YourModName.csproj, and be in the same directory as your everest.yaml
Locate the following lines in the csproj:

        <CelestePrefix Condition="'$(CelestePrefix)' == '' And Exists('..\..\Celeste.exe')">..\..</CelestePrefix>
        <CelestePrefix Condition="'$(CelestePrefix)' == '' And Exists('..\..\..\Celeste.exe')">..\..\..</CelestePrefix>
        <CelestePrefix Condition="'$(CelestePrefix)' == ''">lib-stripped</CelestePrefix>
        <CelesteType Condition="'$(CelesteType)' == '' And Exists('$(CelestePrefix)\BuildIsXNA.txt')">XNA</CelesteType>
        <CelesteType Condition="'$(CelesteType)' == ''">FNA</CelesteType>
        <XNAPath Condition="'$(XNAPath)' == ''">$(WINDIR)\Microsoft.NET\assembly\GAC_32\{0}\v4.0_4.0.0.0__842cf8be1de50553\{0}.dll</XNAPath>
    </PropertyGroup>

Replace them with the following lines:

        <CelestePrefix Condition="'$(CelestePrefix)' == '' And (Exists('..\..\Celeste.exe') Or Exists('..\..\Celeste.dll'))">..\..</CelestePrefix>
        <CelestePrefix Condition="'$(CelestePrefix)' == '' And (Exists('..\..\..\Celeste.exe') Or Exists('..\..\..\Celeste.dll'))">..\..\..</CelestePrefix>
        <CelestePrefix Condition="'$(CelestePrefix)' == ''">lib-stripped</CelestePrefix>

        <!-- Use the legacy reference dir for Core installs -->
        <CelesteIsCore>false</CelesteIsCore>
        <CelesteIsCore Condition="Exists('$(CelestePrefix)\Celeste.dll')">true</CelesteIsCore>
        <CelestePrefix Condition="$(CelesteIsCore)">$(CelestePrefix)\legacyRef</CelestePrefix>

        <CelesteType Condition="'$(CelesteType)' == '' And Exists('$(CelestePrefix)\BuildIsXNA.txt')">XNA</CelesteType>
        <CelesteType Condition="'$(CelesteType)' == ''">FNA</CelesteType>
        <XNAPath Condition="'$(XNAPath)' == ''">$(WINDIR)\Microsoft.NET\assembly\GAC_32\{0}\v4.0_4.0.0.0__842cf8be1de50553\{0}.dll</XNAPath>
    </PropertyGroup>

    <Target Name="CheckCoreInstall" BeforeTargets="PrepareForBuild" Condition="$(CelesteIsCore)">
        <Error Condition="!Exists('$(CelestePrefix)')" Text="Detected a .NET Core Everest install without the required legacyRef install needed to build .NET Framework mods - see the Everest wiki (https://github.com/EverestAPI/Resources/wiki/Code-Mod-Core-Migration-Guide) for info on how to set it up" />
        <Message Text="Building against .NET Core Everest legacyRef install" Importance="high" />
    </Target>

Your csproj should now look something like this:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net452</TargetFramework>
        <AssemblyName>CelesteMod</AssemblyName>
        <RootNamespace>Celeste.Mod.CelesteMod</RootNamespace>
        <LangVersion>latest</LangVersion>
        <CelestePrefix Condition="'$(CelestePrefix)' == '' And (Exists('..\..\Celeste.exe') Or Exists('..\..\Celeste.dll'))">..\..</CelestePrefix>
        <CelestePrefix Condition="'$(CelestePrefix)' == '' And (Exists('..\..\..\Celeste.exe') Or Exists('..\..\..\Celeste.dll'))">..\..\..</CelestePrefix>
        <CelestePrefix Condition="'$(CelestePrefix)' == ''">lib-stripped</CelestePrefix>

        <!-- Use the legacy reference dir for Core installs -->
        <CelesteIsCore>false</CelesteIsCore>
        <CelesteIsCore Condition="Exists('$(CelestePrefix)\Celeste.dll')">true</CelesteIsCore>
        <CelestePrefix Condition="$(CelesteIsCore)">$(CelestePrefix)\legacyRef</CelestePrefix>

        <CelesteType Condition="'$(CelesteType)' == '' And Exists('$(CelestePrefix)\BuildIsXNA.txt')">XNA</CelesteType>
        <CelesteType Condition="'$(CelesteType)' == ''">FNA</CelesteType>
        <XNAPath Condition="'$(XNAPath)' == ''">$(WINDIR)\Microsoft.NET\assembly\GAC_32\{0}\v4.0_4.0.0.0__842cf8be1de50553\{0}.dll</XNAPath>
    </PropertyGroup>

    <Target Name="CheckCoreInstall" BeforeTargets="PrepareForBuild" Condition="$(CelesteIsCore)">
        <Error Condition="!Exists('$(CelestePrefix)')" Text="Detected a .NET Core Everest install without the required legacyRef install needed to build .NET Framework mods - see the Everest wiki (https://github.com/EverestAPI/Resources/wiki/Code-Mod-Core-Migration-Guide) for info on how to set it up" />
        <Message Text="Building against .NET Core Everest legacyRef install" Importance="high" />
    </Target>

    <!--Disable "Copy Local" for all references-->
    <ItemDefinitionGroup>
        <PackageReference PrivateAssets="all" ExcludeAssets="runtime" />
        <Reference Private="false" />
    </ItemDefinitionGroup>

    ...

</Project>

You're done! You should now be able to continue work on and build your mod as usual.

Updating arbitrary csprojs

In case you are not using the template (and as such are unable to follow the above instructions), you will have to add in the legacyRef handling logic yourself (you can use the template's csproj as a reference for how to do this):

Check if you are building against a .NET Core install: .NET Core installs can be detected by the existence of a Celeste.dll file in the game's folder
Optional: If you are building against a .NET Core install, throw an error if a legacyRef folder doesn't exist within the game's files
Change the variable you use to keep track of the game's install folder to <OLD PATH>/legacyRef (this means that your reference paths must not be hardcoded in the csproj!)
If you have XNA/FNA specific handling logic: ensure that it is evaluated using this new game path and not the original Core install path, as Core installs always use FNA.