Modlama:Mod Rehberi/Başlangıç Kılavuzu

SMAPI Modları Oluşturma

Başlangıç Kılavuzu
Oyunun Temelleri
Test ve Sorun Giderme
Yayınlama
API Referansı
Basit SMAPI API'leri:
Gelişmiş SMAPI API'leri:
Belirli Rehberler

İlk defa bir mod yapıyorsanız C# modları ve içerik paketleri arasındaki farklar için kısa bir açıklama için Modlama:İndeks#Mod Oluşturma bölümüne bir göz atın. Mod yapmak için C# bilmenize gerek yoktur.

C# ile Stardew Valley için SMAPI modları mı oluşturmak istiyorsunuz? Bu rehber sizin için!

Giriş

SMAPI Modu Nedir?

Bir SMAPI modu, SMAPI modlama API'sini kullanarak oyun mantığını genişletir. Mod, oyunda bir şey olduğunda yanıt verebilir (dünyada bir nesnenin yerleştirilmesi gibi), düzenli olarak bir kod yürütebilir (her saniye başına gibi), oyunun dosyalarını ve verilerini değiştirebilir. SMAPI modları .NET kullanarak C# dilinde yazılır ve Stardew Valley de oyun mantığı (ekrana gösterme, kullanıcı girişleri vs.) için MonoGame kullanır.

Modlar Neden SMAPI Kullanır?

SMAPI, sizin için çok şey yapar! Örneğin...

Oyuna modları yükler ve kullanabilecekleri API'leri sağlar. Çoğu tür mod, SMAPI olmadan mümkün olmazdı.
Normalde gerçekleştirilemeyen yollarla, API ve event kullanarak oyun ile etkileşime geçmeni sağlar. Bunlar; oyun dosyalarını/verilerini değiştirme, oyuncu ayarlama, çeviri vs. gibi şeyler için basitleştirilmiş API'lerdir. Bunları rehberin sonraki kısımlarında göreceksiniz.
Çapraz platform uyumluluğu için modları tekrar yazar, böylece herhangi bir modu herhangi bir platformda kullanabilirsiniz.
Güncellemek için modları tekrar yazar. SMAPI, çoğu durumda oyun güncellemesi yüzünden bozulmuş mod kodlarını tespit eder ve düzeltir.
Hataları yakalar. Bir mod çökerse veya bir hataya sebep olursa SMAPI hatayı tespit eder, konsol penceresine hata detaylarını gönderir ve çoğu durumda oyunu otomatik olarak kurtarır.
Güncelleme kontrolleri yapar. SMAPI, bir modun yeni bir sürümü yayınlandığında sizi haberdar eder.
Uyumluluk kontrolleri yapar. SMAPI, bir mod uyumsuz olduğunda tespit eder ve sorunlara yol açmadan önce devre dışı bırakır.

Mod Yapabilir Miyim?

Tabii! Bu mod ile birlikte adım adım basit bir mod oluşturabilirsiniz. Her adımı takip ederseniz bir mod oluşturmanız çok kolay olur! Sadece ne yapmak istediğinize karar vermeniz gerekir.

Programlamaya yeniyseniz zaten çoğu mod geliştiricisinin programlama deneyimi de oldukça azdır veya hiç yoktur. Sürece sadık kalırsanız zaten yol boyunca öğrenirsiniz ancak bu yolun dik bir yol olduğunu söylemekte fayda vardır. Hemen hırslanmayın, yolun başında küçük bir mod ile başlamanız daha iyi olacaktır. Başta kendinizi yorarsanız pes etmeniz daha kolay olur. Modlama topluluğu oldukça arkadaş canlısıdır, soru sormaktan çekinmeyin!

Programlama deneyiminiz varsa işiniz biraz daha kolaydır. C# veya Java dilinde programlama deneyiminiz varsa daha da kolaylaşır ancak kritik bir adım değildir. C# ile yabancıysanız boşluklarınızı doldurmak için C# Öğrenme bölümüne bir göz atabilirsiniz.

Programlamada terimleri ve kodu anlamanız için İngilizce bilgisine sahip olmanız gerekir. Takıldığınız durumlarda bu sayfanın İngilizce hâline bakabilirsiniz.

SMAPI Olmadan Mod Yapabilir Miyim?

Evet. Çoğu SMAPI modu, 'içerik paketlerini' destekler. Burada da JSON metin dosyalarını, görsellerini ve her ne kullanılmışsa düzenlemenize yarar. Örneğin Content Patcher kullanarak oyunun görsellerini ve verilerini sıfır programlama ihtiyacı ile düzenleyebilirsiniz. Bu rehberin geri kalanı yeni bir SMAPI modu oluşturma ile ilgilidir. Diğer mevcut framework'ler hakkında bigilendirmeler için Modlama:Content Patcher veya İçerik Paketi Framework'leri sayfalarını (veya başka bir mod için bir içerik paketi oluşturuyorsanız mod dokümantasyonunu) inceleyin.

Nereden Yardım Alabilirim?

Stardew Valley modlama topluluğu oldukça arkadaş canlısıdır. Stardew Valley Discord'unda #making-mods kanalında veya Stardew Valley Türkiye Discord'unda #modlu-çiftçi kanalında soru sormaktan çekinmeyin.

Başlarken

C# Öğrenme

Modlar, C# dilinde yazıldığından bu dille bir tanışmak iyi bir fikir olabilir. Her şeyi hatırlamak zorunda değilsiniz ancak temelini (alanlar, methodlar, değerler, classlar) kavrarsanız her şey çok daha kolay olacaktır.

Bazı kullanışlı kaynaklar:

C# diline giriş ile interaktif örnekler ile C#'ın temellerini öğrenebilirsiniz.
Yeni Başlayanlar için C# Temelleri video rehberi ile temel konseptlerden olay bazlı programlamaya (ki SMAPI de bunu kullanır) kadar C#'ı öğrenebilirsiniz.
Zaten biliyor musunuz? LearnXinYMinutes sayfasından C# dizinlemelerini ve konseptlerine hızlı bir göz atabilirsiniz.

SMAPI'nin sıkla kullandığı birkaç konsept şunlardır:

Genel sınıflar
Olaylar
Serileştirme için SMAPI genelde NewtonSoft kullanır

Gereksinimler

Başlamadan önce:

Oyuncu rehberini okuyun. Bu sayfanın geri kalanında mod kullanmayı bildiğiniz varsayılacak.
Stardew Valley indirin.
SMAPI indirin.
.NET 6 SDK indirin.
Oyunun kullandığı sürüm olduğundan .NET 6'ya ihtiyacınız var. Windows'ta muhtemelen 64x'e sahipsinizdir. macOS'ta "x64" Intel çipli ve "Arm64" de Apple Silicon çipli cihazlar içindir.
IDE (entegre geliştirme ortamı) indirin, mod kodunuzu düzenlemek ve derlemek için kullanacaksınız:
- Windows: Visual Studio Community (bedava) veya JetBrains Rider (ücretli).
- Linux: Visual Studio Code (bedava), MonoDevelop (bedava) veya JetBrains Rider (ücretli).
- macOS: Visual Studio Code (bedava), Mac için Visual Studio (31 Ağustos 2024'te kullanımdan kaldırılacak) veya JetBrains Rider (ücretli).

(Windows'ta/Mac'te) Visual Studio veya (Linux'ta) MonoDevelop'a aşina değilseniz Modlama:IDE Referansı sayfasında bu rehber için önemli şeyler anlatılır.

Basit Bir Mod Oluşturma

Başlangıç

Başlangıç rehberini atlayacak kadar deneyimliyseniz işte bu bölümdeki talimatların hızlı bir özeti:

Talimatların özeti

Boş bir Sınıf Kitaplığı projesi oluşturun. (Sınıf Kitaplığı (.NET Framework)'ü seçmeyin!)
.NET 6'yı hedef alın.
Modun derlendiği platforma bağlı olarak doğru referansları otomatik olarak eklemek için Pathoschild.Stardew.ModBuildConfig NuGet package'i referans gösterin.
StardewModdingAPI.Mod'un alt sınıfı olacak bir ModEntry sınıfı oluşturun.
Entry yöntemini geçersiz kılın ve SMAPI olayları ve API'leri kullanarak kodunuzu yazın.
SMAPI için modunu açıklayan bir manifest.json dosyası oluşturun.
Yayınlamak için mod dosyalarını barındıran bir zip dosyası oluşturun.

Projeyi Oluşturma

Bir SMAPI modu, SMAPI tarafından aranan giriş yöntemi ile bir derlenmiş kitaplıktır (DLL), bu yüzden ilk önce bunu kurmak gerekir.

Visual Studio veya MonoDevelop'u açın.
.NET 6'yı hedefleyin (bkz. hedef framework nasıl değiştirilir). SDK indirmeniz gerekebilir.
Oyun tarafından indirilen ve kullanılan sürüm budur. Oyuncular için yeni sürümleri indirilmemiş olabilir ve SMAPI onları yükleyemiyor olabilir. Evet, kullanım ömrü bitmiş bir şey olduğunu biliyoruz.
Pathoschild.Stardew.ModBuildConfig NuGet package'i referans gösterin (bkz. package nasıl eklenir).
- "StardewModdingAPI" türü veya ad alanı bulunamadı hatası alıyorsanız oyununuzun tespit edilmemesinden olabilir. GamePath değerini oyunun exe dosyasına giden dosya yolu olarak ayarlamanız gerekir. .csproj ayarlarınızda PRopertyGroup kısmına GamePath alanı ekleyerek yapılabilir.
Package yükledikten sonra Visual Studio/MonoDevelop uygulamasını tekrar başlatın.

Kod Ekleme

Şimdi SMAPI'nin yürüteceği bazı kodlar ekleyelim.

Class1.cs veya MyClass.cs dosyasını silin (bkz. dosya nasıl silinir).
Projenize ModEntry.cs adında C# sınıfı bir dosya ekleyin(bkz. dosya nasıl eklenir).

Dosyaya bu kodu yerleştirin (Projenizinİsmi kısmını projenizin ismi ile değiştirin):

using System;
using Microsoft.Xna.Framework;
using StardewModdingAPI;
using StardewModdingAPI.Events;
using StardewModdingAPI.Utilities;
using StardewValley;

namespace Projenizin İsmi
{
    /// <summary>Mod giriş noktası.</summary>
    internal sealed class ModEntry : Mod
    {
        /*********
        ** Herkese açık yöntemler
        *********/
        /// <summary>Mod giriş noktası, mod ilk yüklendikten sonra çağrılır.</summary>
        /// <param name="helper">Mod yazımı için basitleştirilmiş API'ler sağlar.</param>
        public override void Entry(IModHelper helper)
        {
            helper.Events.Input.ButtonPressed += this.OnButtonPressed;
        }


        /*********
        ** Özel yöntemler
        *********/
        /// <summary>Oyuncu klavyede, konsolda veya farede bir şeye bastığında çalışır.</summary>
        /// <param name="sender">Olay gönderici.</param>
        /// <param name="e">Olay verisi.</param>
        private void OnButtonPressed(object? sender, ButtonPressedEventArgs e)
        {
            // oyuncu bir oyunu açmadıysa yoksay
            if (!Context.IsWorldReady)
                return;

            // konsol penceresine tuş basmalarını girer
            this.Monitor.Log($"{Game1.player.Name} pressed {e.Button}.", LogLevel.Debug);
        }
    }
}

Kodun yaptığı şeyler şunlardır:

using X; (bkz. using yönergesi) ile kodunuzdaki mevcut ad alanında sınıflar ekler.
namespace Projenizinİsmi (bkz. ad alanı anahtar sözcüğü) ile mod kodunuz için bir alan belirlenir. Başlarken buna çok dikkat etmeniz gerekmez. Visual Studio veya MonoDevelop, bir dosya eklediğinizde otomatik olarak ekleyecektir.
public class ModEntry : Mod (bkz. class anahtar sözcüğü) ile modunuzun ana sınıfı oluşturulur ve SMAPI'nin Mod sınıfının altına girer. SMAPI, otomatik olarak Mod alt sınıfınızı tespit eder ve Mod da size SMAPI'nin API'lerine erişim sağlar.
public override void Entry(IModHelper helper) ise modunuz oyuna yüklendiğinde SMAPI'nin çağıracağı yöntemdir. helper da SMAPI'nin çokça API'lerine uygun erişim sağlar.
helper.Events.Input.ButtonPressed += this.OnButtonPressed; ile bir buton tıklama olayı gerçekleştiğinde bir 'olay yöneticisi' ekler (başka bir deyişle, çağırmak için bir yöntem). Başka bir deyişle, bir butona basıldığında (helper.Events.Input.ButtonPressed olayı) SMAPI de this.OnButtonPressed yöntemini çağırır. Daha fazla bilgi için SMAPI refernasında olayları inceleyin.

Not: "XX özelliği C# <nubmer> için uygun değil. Lütfen dil sürümü <number> veya daha fazlasını kullanın" gibi derleme hataları alıyorsanız .csproj kısmına <LangVersion>Latest</LangVersion> ekleyin.

Manifest Ekleme

Mod manifest'i ile SMAPI'ye moddan bahsetmiş olursunuz.

Projenize manifest.json adında bir dosya ekleyin.

Dosyanıza bu kodu kopyalayın:

{
  "Name": "<projenizin ismi>",
  "Author": "<isminiz>",
  "Version": "1.0.0",
  "Description": "<mod hakkında bir iki adet açıklama cümlesi>",
  "UniqueID": "<isminiz>.<projenizin ismi>",
  "EntryDll": "<projenizin ismi>.dll",
  "MinimumApiVersion": "4.0.0",
  "UpdateKeys": []
}

<...> sembollerinin arasındaki değerleri doğru bilgilerle doldurun. <> sembollerini silin!

Böylece oyun yüklendiğinde konsol çıktısında gözükeceklerdir. Daha fazla bilgi için manifest dokümanlarını inceleyin.

Modunuzu Deneyin

Projeyi yapılandırın.
Projeyi Oluşturma talimatlarını doğru takip ettiyseniz otomatik olarak modunuzu oyununuzun Mods klasörüne ekleyecektir.
SMAPI ile oyunu çalıştırın.

Mod da böylece oyunda her bir tuşa bastığınızda konsol penceresine bir mesaj gönderir.

Konsol yazı rengini değiştirme

Konsoldaki varsayılan yazı rengi ile yazılar okunamıyor olabilir. Yazı rengini değiştirmek için:

Steam: Steam'i açın ve kütüphanenizde oyuna sağ tıklayın. "Yönet"in altındaki "Yerel dosyalara göz at"a tıklayın ve "/Stardew Valley/smapi-internal/" klasörünüzde config.json dosyasını açın. "ConsoleColors" değerini arayın ve "Trace" ve "Debug" renklerini düzenleyin.

Linux: Oyunu başka bir depolamada veya standart Steam kütüphanesi klasörünün dışında indirmediyseniz Linux için varsayılan dosya yolu ~/.local/share/Steam/steamapps/common/Stardew Valley/smapi-internal/config.json şeklindedir.

Windows: Oyunu başka bir depolamada veya standart Steam kütüphanesi klasörünün dışında indirmediyseniz Linux için varsayılan dosya yolu "C:\Program files (x86)\Steam\steamapps\common\Stardew Valley\smapi-internal\config.json" şeklindedir.

Sorun Giderme

Modunuz çalışmamışsa...

Yukarıdaki adımları tekrar gözden geçirerek bir şey atlamadığınızdan emin olun.
Çalışmadığını anlatan hata mesajlarını bir kontrol edin:
- Visual Studio'da Yapılandır > Tekrar Yapılandır Çözümüne tıklayın ve Output panelini veya Error listesini seçin.
- MonoDevelop'ta Yapılandır > Hepsini Tekrar Yapılandıra tıklayın ve yapana kadar bekleyin. Ardından üstteki "Yapı: XX hata, XX uyarı" çubuğuna tıklayın ve XX Hata ve Yapılandırma Çıktısı sekmelerini seçin.
Hatalardan birinde (ilki olmak zorunda değil) package'in oyun klasörünü bulamadığı söyleniyorsa Visual Studio Oyun/SMAPI/MonoGame DLL'lerini Bulamıyor bölümüne göz atın.
Sorun giderme rehberine göz atın.
Diğer her şey de çalışmıyorsa Stardew Valley Discord'unda #making-mods kanalında yardım isteyebilirsiniz.

Sıkça Sorulan Sorular

SMAPI Dokümantasyonu Nedir?

Bu yalnızca "başlangıç kılavuzu" rehberidir. Daha fazla dokümantasyon için SMAPI referansı veya indeks sayfasında listelenmiş konular incelenebilir.

Diğer Modların Kodlarına Bakabilir Miyim?

Evet, SMAPI modlarının neredeyse %70'i herkese açık bir kaynak koduna sahiptir. Kodlarını bulmak için:

Mod uyumluluğu sayfasını açın.
Arama kutucuğunun altındaki "show advanced info" seçeneğine tıklayın.
Linkler için "code" sütunundaki bilgilere bakın.

Modumun Çapraz Platformda Çalışmasını Nasıl Sağlarım?

SMAPI, otomatik olarak modunuzu Linux, macOS ve Windows'ta çalışması için ayarlar. Ancak sorunlardan kaçınmak için yapmanız gereken birkaç şey vardır:

crossplatform build config package'ini kullanarak otomatik olarak proje referanslarınızı kurun. Böylece çapraz platform uyumluluğunu kolaylaştırır ve kodunuzun herhangi bir platformda derlenmesini sağlarsınız. (Yukarıdaki rehberi takip ettiyseniz bunu zaten yapmışsınızdır.)

System.IO.Path.Combine kullanarak dosya yollarını yapılandırın. Her platformda çalışmadığından yol ayrıştırıcıları gömülmüş kod ile oluşturmayın.

// ✘ Bunu yapmayın! Linux/Mac'te çalışmaz.
string path = this.Helper.DirectoryPath + "\assets\image.png";

// ✓ Bunu yapabilirsiniz.
string path = Path.Combine(this.Helper.DirectoryPath, "assets", "image.png");

this.Helper.DirectoryPath kullanın, mod yoluna kendiniz karar vermeyin.

// ✘ Bunu yapmayın! SMAPI çökebilir (''örn.'' güncellerken veya çapraz platform yaparken).
string modFolder = Assembly.GetCallingAssembly().Location;

// ✓ Bunu yapabilirsiniz.
string modFolder = this.Helper.DirectoryPath;

Bir asset ismi ile Game1.content.Load<T>("asset ismi") şeklinde bir içerik API'si ile yükleyebileceğiniz bir asset tanınır. Bu bir dosya yolu değildir ve asset ismi formatı her zaman dosya yolu formatı ile eşleşmeyebilir. Asset isimlerini karşılaştırırken yol yardımcıları yerine PathUtilities.NormalizeAssetName("some/path") kullandığınızdan emin olun.
```
// ✘ Bunu yapmayın! Windows'ta çalışmaz.
bool isAbigail = (asset.Name == Path.Combine("Characters", "Abigail"));
bool isAbigail2 = (asset.Name == PathUtilities.NormalizePath("Characters", "Abigail"));

// ✓ Bunu yapabilirsiniz.
bool isAbigail = (asset.Name == PathUtilities.NormalizeAssetName("Characters", "Abigail"));
```
Not edilmelidir ki SMAPI API'lerine geçirdiğiniz asset isimlerini normalleştirmeye gerek yoktur çünkü otomatik olarak normalleştirilirler (ama yapmanız da bir soruna yol açmaz):
```
// ✓ Bunu yapabilirsiniz.
helper.Content.Load<Texture2D>("Characters/Abigail");
helper.Content.Load<Texture2D>(@"Characters\Abigail");
```

Oyun Kodunu Nasıl Geri Derlerim?

Oyun kodunun nasıl çalıştığını görmek genelde kullanışlıdır. Oyun kodu StardewValley.dll'e derlenir (yani makine tarafından okunulabilir bir formata dönüştürülür) ancak orijinal kodun çoğunlukla okunabilir bir yaklaşımını oluşturmak için geri derleyebilirsiniz. (Geri derleme kısıtlamaları sebebiyle tam işlevsel olmayabilir ancak ne yaptığını görebilirsiniz.)

Oyun kodunu geri derlemek için...

Kurulum:
1. Windows için ILSpy ("Assets" kısmının altındaki "ILSpy_binaries" dosyasını alın) veya Linux ve macOS için Avalonia ILSpy indirin.
2. ILSpy'ı çalıştırın.
3. View > Optionsa tıklayın, alttaki "Other" bölümüne gelin ve "Always qualify member references" seçeneğini açın.
ILSpy'da Stardew Valley.dll'i açın.
Açılır dil kutucuğunda C# seçildiğinden emin lun (IL, IL with C# veya ReadyToRun değil).
Stardew Valleye sağ tıklayın ve Save Codea tıklayarak Visual Studio'da açabileceğiniz geri derlenmiş bir proje oluşturun.
1. Avalonia ILSpy kullanıyorsanız kayıt diyaloğunda dosya adına .csproj dosya uzantısını eklemeyi unutmayın. Şöyle: Stardew-Valley.csproj (aksi taktirde geri derleme düzgün yapılamaz).

XNB veri/görsel/harita dosyalarını çıkarmak için Modlama:XNB Dosyaları Düzenleme'yi inceleyin.

"NET 6.0 Hedeflemek" Nedir?

Burada birden fazla şey vardır.

target version (hedef sürümü): İkili değerlerinizin derlendiği .NET sürümüdür. Stardew için NET 6.0'ı hedeflemeniz gerekir.
sdk version (sdk sürümü): Bu, indirdiğiniz .NET sürümüdür. SDK sürümünüzden az olan herhangi bir sürümü hedefleyebilirsiniz. VS 2022 ile NET 7.0'a sahip olan biri NET 6.0'ı hedefleyebilir.
C# version (C# sürümü) - Küçük bir sürpriz! Dilin sürümü, .NET sürümünden ayrı belirlenir (uyuşma olmasına rağmen) ve .csproj'daki <langversion> ile dilinizin sürümünü seçebilirsiniz.