Getting Started with Eco Modding in Visual Studio

From Eco - English Wiki
Revision as of 16:55, 29 April 2026 by WugWugg (talk | contribs)

Introduction

This guide focuses on setting up a C# modding environment in Visual Studio.

It does not cover adding Unity assets (models, prefabs, UI) to the game. See: From 3D Asset to Working Worktable for that workflow.

This guide won’t teach you how to code or write a mod, but it will help you get everything set up so you’re ready to start learning. Helpful resources are listed at the bottom of this guide, including Helpful Examples for Modding for practical code examples.

Visual Studio 2026 has a completely free version called the Community Edition. This guide is written assuming that's the version used.

Have Ready

  • A copy of the Eco game installed
  • A file explorer and the file-path to Eco folder
    Tip: Within this folder there's folders like D3D12 and Eco_Data. Also, you'll find the Eco.exe file here. There are other files and folder here too, but this list is just to help you know what the folder looks like.
  • Tip: Steam users can find the install folder by right-clicking on the game in your Steam Library:
    Shows a Steam Library with a menu open over the Eco game. Highlighted in that menu is a "Manage" option, opening a sub-menu. The sub-menu has "Browse local files" highlighted.

Installing Visual Studio

  1. Go to https://visualstudio.microsoft.com/downloads/#visual-studio-community-2026 and look for the "Visual Studio Community 2026" download.
  2. Start the download by clicking on the Download button.
  3. Run the installer until it reaches the Workloads page
  4. Select these workloads...
    1. .NET desktop development -- Required for any mod development
    2. ASP.NET and web development -- Optional. If you want to interact with external websites or Eco's own web server (e.g. Discord's webhooks or extending the API)
  5. With those workloads selected the page should look something like this:
    Workloads screen during VS2022 installation. Options selected are "ASP.NET and web development" and ".NET desktop development".
  6. Click the Install button. It will take a few minutes to complete installation.
  7. Open Visual Studio after it installs.
  8. You may be prompted to sign in:
    1. Click Skip and add accounts later to continue.
    2. If you plan to use GitHub, sign in to make version control easier.
  9. Finally, it might ask what color theme you'd like. Select your preference and continue.
  10. Visual Studio is now installed and ready to be used.

Setting Up a New Mod

Once Eco and Visual Studio are installed, all of the tools needed to code, build, and run a mod are ready.

Creating a New Project

  1. Open Visual Studio. When it first opens it will show you a dashboard where you can quickly select what you want to do.
  2. On the right, under Get Started find the Create a new project button:
    VS2022's launch dashboard showing recent projects on the left and quick action buttons on the right. Highlighted is a button titled "Create a new project".
  3. A new window will pop-up.
  4. Select C# Class Library. To find the template, search C# library in the search bar. Select the C# option titled Class Library.
    Note: Make sure you select the C# option as there are other options similarly named Class Library.
    location=center
  5. Click the Next button.
  6. For Project Name type the name of the mod being created.
  7. The other options like the Location and the Solution Name do not need edited.
  8. Leave the box Place solution and project in the same directory unchecked.
  9. Click the Next button.
  10. In the Framework drop-down select the same version of .NET Eco uses (as described below). Tip: Eco currently targets .NET 10.0

.NET Version

To confirm the version of .NET that Eco uses:

  1. Go to the NuGet Gallery www.nuget.org/packages?q=Eco.ReferenceAssemblies
  2. Find the package with the name Eco.ReferenceAssemblies made by StrangeLoopGames.
  3. Notice the chip underneath of it with the .NET version it targets.
    Shows the search result of Eco.ReferenceAssemblies. In a blue chip the text ".NET 8.0" can be seen.
  4. Click on that search result (shown above).
  5. A more detailed page is shown. Again, there's chips showing what version of .NET to use:
    Show the package page for "Eco.ReferenceAssemblies" on NuGet Gallery. Circled in red are two chips with some version of the text ".NET 8.0" inside them.

Linking to Eco Assemblies

  1. Find the Solution Explorer on the right side of Visual Studio. It should look something like this:
    Note: If the solution explorer isn't there, open the View menu (top toolbar) and select Solution Explorer.
    A picture of a basic layout in Visual Studio 2022 with the Solution Explorer open on the right-hand side. The solution explorer is circled in red.
  2. In the Solution Explorer, find and right-click on the Dependencies item.
  3. Select Manage NuGet Packages...
    Shows VS2022's Solution Explorer with project expanded. The References line is highlighted and a menu is open. On that menu the "Manage NuGet Packages" line is highlighted.
  4. A NuGet tab will have opened in the editor window...
    1. Right above the search bar on this tab there's sub-tabs.
    2. Select the Browse sub-tab.
    3. Type Eco.ReferenceAssemblies into the search bar.
    4. Check the Include prerelease check-box.
    5. Find the option with the name Eco.ReferenceAssemblies made by StrangeLoopGames.
    6. Click on that.
    7. A details panel will show up to the right. It will show the version of the reference assemblies being targeted. By default it chooses the latest and can be left at its default.
    8. Click the Install button.
      1. Click the Apply button on the popup to finish adding the references.
        VS2022 is open to the NuGet tab and is searching with the text Eco.ReferenceAssemblies. The checkbox to the right of the search is checked -- include prerelease. The only search result is selected. There is yellow highlights over part of the photo.
  5. The reference assemblies have now been added. That means when coding Visual Studio will provide IntelliSense popups.
  6. Try it out by going back to the Class1.cs file and typing Eco. and suggestions will pop up.

Dynamic Link Library (DLL)

Building the mod creates the .dll file that can be dropped into the Mods/UserCode folder of any server and run.

Building for Development

  1. Open the project in Visual Studio.
  2. Open the Build menu from the top toolbar.
  3. Select Build Solution. This will produce a non-optimized DLL used for testing and development.
    VS2022 top menu "Build" is open with "build solution" highlighted (ctrl + shift + b).
  4. To find the file Visual Studio just built, right click on the project in the Solution Explorer.
  5. Select Open Folder in File Explorer.
    VS2022's solution explorer is shown with the projects right-click menu open. Highlighted is "Open folder in File Explorer"
  6. From here, the mod's DLL will be in the bin/Debug/net10.0/ folder. The file will be named with mod's name, like TheMod.dll.
  7. Copy the mod's DLL file.
  8. Paste it into the folder Eco/Eco_Data/Server/Mods/UserCode.

Checkpoint

  1. Start Eco and create a local world to see if the mod is being loaded.
  2. Check the logs at Eco/Eco_Data/Server/Logs/ to verify...
    1. Open the most recent log file here.
    2. If the mod was loaded it there will be a line mentioning the file-name of the DLL. If the DLL was named TheMod.dll, line 5 is what to look for in the log file:
[13:55:54.815] [4] [ Info] [Eco] Starting ModKitPlugin                             ...  
[13:56:27.399] [4] [ Info] [Eco] Starting ModKitPlugin                             ... Finished in 32.584 sec
 
[13:56:27.439] [4] [ Info] [Eco] Loading mods                                      ...  
[13:56:27.439] [9] [ Info] [Eco] Loading TheMod...

Tip: Setup File Explorer to Sort By Date

  1. Setup the file view to Details in this folder because it will show the Date Modified for each file.
    Show Window's File Explorer's view setting menu with the "details" option highlighted.
  2. Click on the Date Modified header to sort all files. This will sort it so the most recent is on top. Now, every time the server starts the log file is easily found -- it's the one on top!
    Show's window's File Explorer with the date modified header highlighted.

Building for Release

Release builds are optimized and intended for sharing. Unlike Debug builds, they exclude extra debugging overhead and produce a cleaner, final version of your mod.

  1. Open the project in Visual Studio.
  2. Click on the mod's project in the Solution Explorer to highlight it.
    Shows VS2022's solution explorer with the project highlighted.
  3. Open the Build menu from the top toolbar.
  4. Select Publish Selection.
  5. A new Publish window will pop-up.
  6. Set the target as Folder.
  7. Click the Next button.
    VS2022's publish wizard showing the target selection screen. The Folder option is highlighted.
  8. Leave the folder location as it is.
  9. Click the Finish button.
  10. Click the Close button.
  11. Click the Publish button to start the build. This may take a minute.
  12. A green alert will pop up when the build is completed:
    Show's VS2022 publish screen. There's publish button at the top of this screen.
  13. Inside the alert there will be a blue Navigate link. Click it.
  14. A file explorer should have opened to where the .dll file is.
  15. The mod file will be named with the mod project's name. For example, TheMod.dll.
  16. To share this mod, the only file needed is the mod's .dll. Do not copy any of the .dll files starting with Eco or StrangeCloud. Additionally, do not copy the TheMod.deps.json or the TheMod.pdb files.

Post-Build Scripts

With a post-build script Visual Studio will automatically copy the files into the Eco Mods/UserCode folder every time it builds. It's a very nice feature to have when developing and rebuilding to test something new.

  1. Open the project in Visual Studio.
  2. Right-click on the project in the Solution Explorer.
  3. Select ↱ Edit Project File option.
  4. Add the properties EcoServerExe and EcoServerDir inside of the PropertyGroup tag.
    Tip: By holding shift and right-clicking on a file in the file explorer an old-school menu pops up. Midway down this menu is an option to Copy As Path. Neat!
  5. The project file should look something like this (lines 8-9):
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    
    <!-- Point this at your Eco source server Mods/UserCode -->
    <EcoModsDir>C:\Program Files (x86)\Steam\steamapps\common\Eco\Eco_Data\Server\Mods\UserCode</EcoModsDir>
    
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Eco.ReferenceAssemblies" Version="0.11.1.13-beta-release-887" />
  </ItemGroup>

</Project>
  1. Add the PostBuild property inside the Project tag.
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    ... SNIP ...
  </PropertyGroup>

  <ItemGroup>
    ... SNIP ...
  </ItemGroup>

<Target Name="CopyModToEco" AfterTargets="Build">
	<Copy SourceFiles="$(TargetPath)" DestinationFolder="$(EcoModsDir)" SkipUnchangedFiles="true" />
	<Copy SourceFiles="$(TargetDir)$(TargetName).pdb" DestinationFolder="$(EcoModsDir)" SkipUnchangedFiles="true" Condition="Exists('$(TargetDir)$(TargetName).pdb')" />
</Target>
</Project>
  1. Build the project.
  2. Look in the Mods/UserCode folder.
  3. There should be TheMod.dll file.

Setting up Debugging

To set up debugging, make sure the project is configured with the post-build script described above.

Debugging is a powerful tool that allows you to set breakpoints anywhere in your code to pause execution. While paused, you can inspect variable values and step through the code line by line. This is invaluable when tracking down bugs or understanding complex behavior.

When running the server in debug mode, code changes can be hot-reloaded. This allows you to modify code and apply changes without rebuilding and restarting Eco, significantly speeding up development.

  1. Open the Debug menu from the top toolbar.
  2. Select YourModName Debug Properties from the bottom of the menu.
    VS2022's debug menu is open from the top of the application. Highlighted is the last option "Debug Properties".
  3. Click the Create a new profile button in the top-left of this new window (see image below).
  4. Select Executable from the drop-down menu.
    VS2022's launch profile window is open. Underlined and pointed to by a red mark is the "Create a new profile" button, located in the top-left of the window. Highlighted from the menu under it is the option reading "Executable".
  5. Set the Executable field to the full path to the EcoServer.exe file.
    Example: C:\Program Files (x86)\Steam\steamapps\common\Eco\Eco_Data\Server\EcoServer.exe.
  6. Set the Working Directory field to the full path to the folder containing the EcoServer.exe file.
    Example: C:\Program Files (x86)\Steam\steamapps\common\Eco\Eco_Data\Server.
    A fully configured profile ready to debug Eco on VS2022's launch profile page.
  7. Switch to this newly configured profile by clicking the small arrow to the right of the play icon (see image).
    VS2022's debugger profile selection menu is open with the newly created "Profile 1" highlighted.
  8. Select the newly created profile -- Profile 1.

Checkpoint

  1. Put the following in Class1.cs file:
using Eco.Core.Plugins.Interfaces;
using Eco.Core.Utils;
using Eco.ModKit;

namespace Test
{
    public class Class1 : IModKitPlugin, IInitializablePlugin
    {
        public string GetCategory() => "Tutorial";

        public string GetStatus() => this._status;
        string _status = string.Empty;

        public void Initialize(TimedTask timer)
        {
            this._status = "Ok";
            bool yes = true;
            return;
        }
    }
    
    [ChatCommandHandler]
    [SupportedOSPlatform("windows7.0")]
    public static class CommonCentsCommands
    {
        [ChatCommand("wikiTest", ChatAuthorizationLevel.Moderator)]
        public static void wikiTest(IChatClient chat)
        {
            chat.MsgLoc($"Hello, World.");
        }
    }
}


This code creates a basic plugin, called Class1, that Eco will load and initialize on startup. Eco knows to do this because this class inherits the IModKitPlugin interface (causes it to be loaded) and the IInitializablePlugin interface (causes it to be initialized).

  1. Add a breakpoint to the code by right-clicking on the line bool yes = true;
    A boilerplate example of a mod is shown in the VS2022 text editor. A line has a menu open above it with the option "Breakpoint" expanded and the option "Insert Breakpoint" highlighted on the sub-menu.
  2. Click the green ⏵ button to start the server with the mod. The server will start and Visual Studio will flash back on screen once Eco tries to initialize the mod's plugin.
    Highlighted is the play button for VS2022's debugger. The "Profile 1" is still selected from before.
  3. When Visual Studio hits the breakpoint it will keep startup from continuing and allow detailed inspection to happen. In the bottom left (circled in red) is a table of all of the variables within scope. Use this to see what is happening (especially useful in loops!). At the middle-top (circled in red) are some of the debugger controls. Clicking the highlighted Continue button resumes normal operation. Using the buttons to the right that are highlighted will allow the developer to step through the codes execution to see exactly how each line is performing. Debugging is a deep and rich topic that this guide will not explain further, but there's a great video by Microsoft Visual Studio on YouTube called Basics of Debugging. In that 45 minute video (don't worry there's annotations to jump to just what is interesting) a whole gamut of information about how to use debugging is covered.
    Shows a simple plugin's code in the editor of VS2022. In the bottom-left is a table of all variables used in the function. It is circled in red. On the top of the image also circled in red is the debugger controls. Highlighted within is the continue button and the "step over" button.
  4. Hit the green⏵ Continue button.
  5. Let the server finish loading.
  6. Open Eco to play.
  7. Connect to the LAN world by named something like Eco World.
  8. Type /wikiDemo in chat.
  9. See that the mod replies with Hello, World.
  10. Change line 29 in Class1.cs to chat.MsgLoc($"Hello, Modder!");
  11. Hit the hot reload button. It's just to the right of the green ⏵ Continue button and vaguely looks like the 🔥 icon.
  12. Type /wikiDemo in chat.
  13. See that the mod now replies with Hello, Modder!

Releasing a Mod

Mod.io

mod.io is where creators share their mods with players and others. To share a new mod there all that is necessary is an account:

  1. Goto https://mod.io/g/eco and click "Login" in the top-right corner.
  2. Sign up with whatever account type you prefer.
  3. Click the "Add Mod" button in the top-right.
  4. Follow the upload wizard as directed.
  5. Once on the "File Manager" section, a zip file is needed...
    1. Zip the mod's release/ dll and any other assets necessary (e.g. Unity bundles) by putting all the files into a folder.
    2. Right-click on that folder
    3. Hover "Compress To..."
    4. Select "ZIP file".
    5. Use and upload that zip file.
      Tip: Considering naming it with a version number to help stay organized (e.g. "v1"). Next release, increase that number by 1 (e.g. "v2")

Sharing on Discord

Consider posting an ad on the official Eco Discord server. There's a channel for mods called mod-ads. Please read the rules before posting.

Helpful Resources

  • Consider learning source control (Git). Completely optional, but can help you keep things organized as development continues.
  • Explore Eco’s open-source mod projects for ideas (search on GitHub "Eco Mods" to find some real-life examples)
    • Eco Discord serverhas a channel for mod developers to help one another called mod-dev. Note: Make under the Channel & Roles settings you have the 🛠Yes, I want to see the channels about modding role selected.
Retrieved from "https://wiki.play.eco/en/index.php?title=Getting_Started_with_Eco_Modding_in_Visual_Studio&oldid=16750"
CC BY-NC-SA 4.0
Powered by MediaWiki