stardew-mod-development

name	stardew-mod-development
description	Develop, inspect, debug, migrate, test, and package Stardew Valley mods with SMAPI, C#/.NET 6, Content Patcher, game data, Harmony, local game assemblies, and decompiled game references. Use for Stardew Valley mod projects, ModEntry.cs, manifest.json, SMAPI APIs/events/logs, content packs, game internals, version migrations, build/deploy failures, or offline modding-documentation research.

Stardew Mod Development

Use this game-local skill as the handoff point for all Stardew Valley mod work. Prefer its offline references and scripts, then verify live sources only when the installed game or SMAPI version has changed.

Start every task

1. Run scripts/check-environment.ps1 -WriteSnapshot when versions or installation state matter.
2. Read references/generated/environment.md, references/generated/versions.lock.json when present, and the target project's .csproj, manifest.json, entry class, assets, and latest SMAPI log.
3. Classify the task before coding:
   • Use a content pack or Content Patcher for data, dialogue, maps, images, shops, NPC data, and other declarative edits.
   • Use a C# SMAPI mod for runtime behavior, events, custom logic, integrations, or UI.
   • Use Harmony only when SMAPI events, content/data APIs, public game APIs, or integrations cannot solve the requirement.
4. Load only the relevant local reference listed in references/reference-map.md.
5. Build and verify against the installed game and SMAPI, then record versions, commands, output, logs, changed files, and remaining risks for the next agent.

Source priority

Use evidence in this order:

1. The user's current mod source and its manifest/config/logs.
2. Installed game XML docs and assemblies in the game root.
3. Installed SMAPI XML docs, binaries, config, and logs.
4. The matching SMAPI Git tag in references/upstream/smapi.
5. Decompiled local game source in references/generated/game-source.
6. Offline Wiki snapshots in references/wiki.
7. The SMAPI develop source snapshot.
8. Live official Wiki, SMAPI.io, NuGet, and GitHub sources for current-version confirmation.

Never assume the versions recorded in this skill are still current. The initial snapshot is Stardew Valley 1.6.15, SMAPI 4.5.2, .NET 6 SDK 6.0.428, and .NET 8 SDK 8.0.423.

Route common work

• Environment or installation: run scripts/check-environment.ps1; verify StardewModdingAPI.exe, Mods, .NET 6 SDK, launch option, and logs.
• Research an API or game concept: run scripts/search-reference.ps1 -Query '<term>'; then open the narrowest matching local file.
• Create a C# mod: run scripts/new-mod.ps1 -Name <Name> -Author <Author> -Build; inspect the generated project before extending it.
• Create a content pack: read the offline Content packs and framework-specific Wiki pages; do not create a DLL unless runtime code is required.
• Inspect game behavior: search game XML docs first, then run scripts/decompile-game.ps1 and search the generated source.
• Diagnose a failure: inspect the first relevant error in %AppData%\StardewValley\ErrorLogs\SMAPI-latest.txt, not only the final repeated error.
• Migrate or release: read references/workflows.md, the matching Wiki migration snapshot, SMAPI release notes, and the project's dependencies/update keys.

C# defaults

• Target net6.0; Stardew Valley 1.6 uses .NET 6 even though the framework is EOL.
• Build with the installed .NET 8 SDK when possible. It can target net6.0 and supplies a compiler new enough for ModBuildConfig 4.4.0 analyzers; keep the .NET 6 SDK/runtime installed for compatibility.
• Reference Pathoschild.Stardew.ModBuildConfig and set GamePath when automatic detection is unreliable.
• Use nullable reference types and keep the entry class small.
• Prefer SMAPI events and helper APIs over polling, reflection, or patches.
• Use Path.Combine, Helper.DirectoryPath, Helper.ModContent, Helper.GameContent, and normalized asset names.
• Keep manifest.json beside the built DLL and make EntryDll, UniqueID, dependencies, MinimumApiVersion, and update keys accurate.
• Treat multiplayer ownership, save migration, content invalidation, localization, and config compatibility explicitly.
• Do not bundle game, SMAPI, MonoGame, or framework DLLs in a release unless an upstream requirement explicitly says to.

Build and test

Run dotnet build from the mod project. ModBuildConfig should deploy a successful build into the game's Mods folder and can generate a release zip.

Launch StardewModdingAPI.exe directly for development, or configure Steam with:

"<game path>\StardewModdingAPI.exe" %command%

Confirm all of the following before calling work complete:

• The project restores and builds with zero errors.
• The deployed folder contains manifest.json, the entry DLL, and required assets/i18n.
• SMAPI loads the mod without skipped-mod or dependency errors.
• The tested scenario works in a disposable/test save where appropriate.
• The latest log contains no new relevant errors.

Local research and decompilation

Run scripts/search-reference.ps1 before broad web research. Search examples and paths are in references/reference-map.md.

Use scripts/decompile-game.ps1 only for local compatibility and implementation research. Read references/decompilation.md first. Keep generated game source local; do not publish or package it with a mod or shared skill.

Refresh official snapshots with scripts/update-docs.ps1. The script keeps local changes to the SMAPI clone safe by using fast-forward updates only.

Handoff standard

Leave the next agent a concise record containing:

• Game, SMAPI, .NET SDK, and important dependency versions.
• Exact project and deployed-mod paths.
• Design choice: content pack, SMAPI API, integration, reflection, or Harmony, with rationale.
• Commands run and build/test result.
• Latest relevant log path and unresolved warnings.
• Any save compatibility, multiplayer, platform, or version-migration risk.

Use references/workflows.md for detailed implementation, debugging, migration, and release checklists.