Stardew Farmhand is the new in-development tool intended to replace SMAPI

Stardew-Farmhand on discord

Current Build Status

Branch Windows CI Static Analysis
Master Build status
Development Build status Static Analysis

Project Details

Stardew Farmhand is the new in-development API intended to replace SMAPI


SMAPI Compatibility Layer: LGPL

Farmhand: MIT

xml2json: Not Specified (

Branching Policy

The master branch is marked as protected and it's what all release builds will be compiled against. Make your pull requests against the development or feature branches, pull requests directly into master probably will not be accepted.

My First Build

Building the project for the first time can seem a little daunting given the number of projects and no doubt countless missing references you'll see but be unable to resolve. Follow these steps in order and it should build first time!

1) Before opening the solution, run "PopulateSubmodules.bat", this will pull the correct version of the SMAPI submodule.

2) Copy the contents of your Stardew Valley game folder(Stardew Valley.exe, xtile.dll, Content folder, and other dlls alongside it) to a /Staging folder. Visual Studio should now have recognised these references.

3) Build the project "BuildTasks/BuildFarmhandFinal" in Debug mode, this should have fixed all reference errors and built the API in /WorkingDirectory. Intermediate build binaries will be in /Bin. See below for potential issues:

  • If you get Newtonsoft.Json errors: It's been known to incorrectly download the 4.5 version when we need to 4.0 version. To fix this, right click the Farmhand project, Manage NuGet Packages, uninstall Newtonsoft.Json and readd it.
  • If you get warnings like " There was a mismatch between the processor architecture of the project being built "MSIL" and the processor architecture of the reference ", right click the project causing it, click properties, and in the Build tab set Platform Target to "x86".

4) To ease your workflow, copy the Stardew Valley Contents folder into /WorkingDirectory, and the same with Stardew Valley's DLLs (i.e. xTile.dll and Steamworks.NET.dll). You are now ready to start working on the API! :)

5) For your reference, Stardew Farmhand.int1.dll is generated by BuildFarmhandIntermediate. This bundles together the Farmhand core code into Stardew Valley. This is then used by second pass build libraries such as Farmhand UI so it can take advantage of methods injected into Stardew during the first pass.

Working on the core API

The core API is located inside Libraries/Farmhand. For changes to this library to be reflected, you'll need to manually trigger BuildFarmhandFinal. Alternatively you can add BuildFarmhandFinal as a build dependency to Tools/FarmhandDebugger. This is not done as default as it would lower iteration times for developers working on mods - who do not need to constantly rebuild the API.

Note, that if you are working on both Farmhand and a second-pass API library (Farmhand UI), you will need to manually build BuildFarmhandIntermediate to fix intellisence reference warnings. However, these warnings can just be ignored and will do away upon trigging a final build if the code is correct.

Build Tasks

These projects are responsible for handling build flow.

  • BuildFarmhandIntermediate packages Farmhand Core into Stardew and applies the appropriate hooks. This is the project you should click "Rebuild" on when altering the engine, as it will force all builds to trigger in the correct order.

  • BuildFarmhandFinal packages the projects dependent on the results of BuildFarmhandIntermediate into Stardew and produces the final Stardew Farmhand.exe


  • Farmhand Installer - Console (EXE). This runs FarmhandPatcher, expecting the Stardew Valley and Stardew Farmhand files to be adjacent to it.

  • Farmhand Installer - UI (EXE). This runs FarmhandPatcher too. Once it's complete, this will be the file we actually distribute out. It should automatically bundle the required binaries (Farmhand, FarmhandUI, FarmhandPatcherCommon, FarmhandPatcherFirstPass, FarmhandPatcherSecondPass) and extract them at runtime. At the final stages, this should allow for updated binaries to be fetched from the internet.

  • FarmhandPatcherCommon/FirstPass/SecondPass. These are used by the installer.They are separated into their own libraries to prevent conflicts due to the missing (not yet built) Stardew Farmhand intermediate


  • Farmhand (DLL). The core code which is injected into Stardew


  • Farmhand Debugger (EXE). Just serves as an entry point for me to step through and debug StardewR code in the event I inject something incorrectly. This should be set as your startup project when not debugging the build process.