SMAPI C# Starter Template
เทมเพลตเริ่มต้นสำหรับเขียนมอด Stardew Valley ด้วย C# และ SMAPI 4 ตั้งค่า net6.0 กับ ModBuildConfig ไว้แล้ว พร้อม manifest.json, ModEntry.cs และ README ภาษาไทย
ความสามารถ
- ตั้งค่า TargetFramework เป็น net6.0 ตามที่ SMAPI 4 ใช้
- ใช้แพ็กเกจทางการ Pathoschild.Stardew.ModBuildConfig 4.4.0
- ModEntry.cs พร้อมตัวอย่าง event ButtonPressed และคอมเมนต์ภาษาไทย
- manifest.json ที่ผ่าน Manifest Validator
- README ภาษาไทยอธิบายวิธี build และทดสอบ
- .gitignore สำหรับโปรเจกต์ .NET
ความเข้ากันได้
| SMAPI | 4.0.0 ขึ้นไป (ตรวจเอกสารกับ 4.5.2) |
|---|---|
| Stardew Valley | 1.6.14 ขึ้นไป (ตามที่ SMAPI 4.5.2 ต้องการ) |
| .NET | TargetFramework net6.0 (build ด้วย .NET SDK 6 ขึ้นไป) |
| ระบบปฏิบัติการ | Windows, macOS, Linux (ตามที่ SMAPI และ .NET SDK รองรับ) |
ข้อมูลนี้มาจากเอกสารทางการ ไม่ได้รับประกันการทำงานกับทุกเวอร์ชันของเกมหรือมอดอื่น
โครงสร้างไฟล์
- MyFirstMod/
- .gitignore
- manifest.json
- ModEntry.cs
- MyFirstMod.csproj
- README.md
ตัวอย่างไฟล์สำคัญ
MyFirstMod.csprojไฟล์ตั้งค่าโปรเจกต์ .NET และ ModBuildConfig
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<AssemblyName>MyFirstMod</AssemblyName>
<RootNamespace>YourName.MyFirstMod</RootNamespace>
<Version>1.0.0</Version>
<!-- SMAPI 4.x และ Stardew Valley 1.6 ใช้ .NET 6 -->
<TargetFramework>net6.0</TargetFramework>
<LangVersion>latest</LangVersion>
<Nullable>enable</Nullable>
<!-- ถ้า build หาเกมไม่เจอ ให้ระบุตำแหน่งเกมเอง เช่น:
<GamePath>C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley</GamePath>
-->
</PropertyGroup>
<ItemGroup>
<!-- แพ็กเกจทางการสำหรับ build มอด: อ้างอิง DLL ของเกม/SMAPI, คัดลอกมอดไปโฟลเดอร์ Mods และสร้างไฟล์ zip ให้อัตโนมัติ -->
<PackageReference Include="Pathoschild.Stardew.ModBuildConfig" Version="4.4.0" />
</ItemGroup>
</Project>ModEntry.csโค้ดหลักของมอด (จุดเริ่มต้น)
using StardewModdingAPI;
using StardewModdingAPI.Events;
using StardewValley;
namespace YourName.MyFirstMod
{
/// <summary>จุดเริ่มต้นของมอด SMAPI จะสร้าง class นี้และเรียก Entry() หนึ่งครั้งตอนโหลดมอด</summary>
internal sealed class ModEntry : Mod
{
/// <summary>เมธอดแรกที่ SMAPI เรียกหลังโหลดมอด</summary>
/// <param name="helper">ตัวช่วยของ SMAPI สำหรับเข้าถึง event, config, content และ API อื่นของ SMAPI</param>
public override void Entry(IModHelper helper)
{
// ข้อความนี้จะแสดงในหน้าต่าง SMAPI console เมื่อมอดถูกโหลด
this.Monitor.Log($"{this.ModManifest.Name} {this.ModManifest.Version} loaded!", LogLevel.Info);
// สมัครรับ event จาก SMAPI
helper.Events.Input.ButtonPressed += this.OnButtonPressed;
}
/// <summary>ทำงานทุกครั้งที่ผู้เล่นกดปุ่ม (คีย์บอร์ด เมาส์ หรือคอนโทรลเลอร์)</summary>
private void OnButtonPressed(object? sender, ButtonPressedEventArgs e)
{
// ยังไม่ได้โหลดเซฟ (อยู่หน้าเมนูหลัก) ให้ข้ามไปก่อน
if (!Context.IsWorldReady)
return;
// แสดงปุ่มที่กดในหน้าต่าง SMAPI console
this.Monitor.Log($"{Game1.player.Name} pressed {e.Button}.", LogLevel.Debug);
}
}
}manifest.jsonข้อมูลมอดสำหรับ SMAPI
{
"Name": "My First Mod",
"Author": "YourName",
"Version": "1.0.0",
"Description": "My first SMAPI mod.",
"UniqueID": "YourName.MyFirstMod",
"EntryDll": "MyFirstMod.dll",
"MinimumApiVersion": "4.0.0",
"UpdateKeys": []
}README.mdวิธี build และทดสอบ
My First Mod
My first SMAPI mod.
- UniqueID:
YourName.MyFirstMod - เวอร์ชัน: 1.0.0
- ผู้สร้าง: YourName
คำเตือน: ไฟล์นี้เป็นซอร์สโค้ด ยังไม่ใช่มอดที่พร้อมติดตั้ง ต้อง build (คอมไพล์) ให้ได้ไฟล์
MyFirstMod.dllก่อน จึงจะนำไปใช้ในเกมได้ อย่าคัดลอกโฟลเดอร์นี้ไปไว้ในModsโดยตรง
สิ่งที่ต้องมี
- Stardew Valley 1.6.14 ขึ้นไป บน PC
- SMAPI (ทดสอบรูปแบบไฟล์กับ SMAPI 4.5.2)
- .NET 6 SDK หรือใหม่กว่า: https://dotnet.microsoft.com/download
- IDE เช่น Visual Studio 2022, JetBrains Rider หรือ Visual Studio Code (ติดตั้ง C# Dev Kit)
วิธี build
cd MyFirstMod
dotnet build
แพ็กเกจ Pathoschild.Stardew.ModBuildConfig จะ:
- หาตำแหน่งเกมและอ้างอิง DLL ของเกม/SMAPI ให้อัตโนมัติ
- คัดลอกมอดที่ build แล้วไปไว้ที่
Stardew Valley/Mods/MyFirstMod - สร้างไฟล์ zip สำหรับแจกจ่ายไว้ในโฟลเดอร์
binของโปรเจกต์
ถ้า build แล้วขึ้นว่าหาเกมไม่เจอ ให้เปิดไฟล์ MyFirstMod.csproj แล้วใส่ <GamePath> ตามตัวอย่างในคอมเมนต์
ทดสอบ
- เปิดเกมผ่าน SMAPI
- ในหน้าต่าง console ควรเห็นข้อความ
MyFirstMod...loaded! - ถ้ามีปัญหา ให้นำ log ไปตรวจที่ https://svmoddingth.dev/tools/log-analyzer/
ไฟล์ในโปรเจกต์
| ไฟล์ | หน้าที่ |
|---|---|
manifest.json |
ข้อมูลมอดที่ SMAPI ใช้ (ชื่อ, UniqueID, เวอร์ชัน, EntryDll) |
ModEntry.cs |
โค้ดหลักของมอด |
MyFirstMod.csproj |
การตั้งค่าโปรเจกต์ .NET |
เอกสารอ้างอิง
- คู่มือภาษาไทย: https://svmoddingth.dev/learn/smapi-hello-world/
- Modder Guide (ทางการ): https://stardewvalleywiki.com/Modding:Modder_Guide/Get_Started
- Manifest: https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest
- Events: https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Events
สร้างด้วย SVMT Mod Generator (https://svmoddingth.dev/tools/mod-generator/) เทมเพลตอยู่ภายใต้ MIT License คุณเป็นเจ้าของโค้ดที่สร้างขึ้นและเลือก license ของมอดเองได้
วิธีใช้งาน
- ดาวน์โหลดไฟล์ ZIP แล้วแตกไฟล์ไว้ในโฟลเดอร์สำหรับเก็บโปรเจกต์ (ไม่ใช่โฟลเดอร์
Mods) - เปิดโฟลเดอร์
MyFirstModด้วย Visual Studio, Rider หรือ VS Code - แก้
manifest.jsonให้เป็นชื่อและ UniqueID ของคุณ และแก้RootNamespaceใน.csprojกับnamespaceในModEntry.csให้ตรงกัน - รันคำสั่ง
dotnet build - เปิดเกมผ่าน SMAPI แล้วดูข้อความของมอดใน console
ถ้าต้องการตั้งชื่อ UniqueID และ namespace ให้ถูกต้องตั้งแต่แรก ใช้ Mod Generator สร้างโปรเจกต์แบบเดียวกันด้วยข้อมูลของคุณเอง
แก้ปัญหา
build ไม่ผ่านเพราะหาเกมไม่เจอ
เปิด MyFirstMod.csproj แล้วใส่ <GamePath> เป็นตำแหน่งโฟลเดอร์เกมของคุณ (มีตัวอย่างในคอมเมนต์ของไฟล์)
คำเตือน NETSDK1138
เกิดเมื่อ build ด้วย .NET SDK ที่ใหม่กว่า 6 เพราะ net6.0 หมดระยะการสนับสนุนของ Microsoft แล้ว ไม่กระทบการทำงานของมอด เพราะเกมยังใช้ .NET 6
SMAPI แจ้งว่า DLL doesn’t exist
ตรวจว่า EntryDll ใน manifest.json ตรงกับ AssemblyName ใน .csproj และ build สำเร็จแล้ว
อ่านขั้นตอนละเอียดได้ในบท SMAPI Hello World
Changelog
v1.0.0 ·
- เผยแพร่ครั้งแรก