251 lines
6.5 KiB
Markdown
251 lines
6.5 KiB
Markdown
# 🎨 ShiroginSDK Theme System (v1.0.0)
|
||
|
||
**Dynamic UI Skin Management • ServiceLocator Architecture • Scriptable Themes**
|
||
|
||
ShiroginSDK’nin **Theme System**’i, oyun içi UI öğelerinin (ikonlar, arka planlar, butonlar vb.) görünümünü merkezi ve modüler bir şekilde yönetmeni sağlar.
|
||
Tüm temalar **enum tabanlı**, **ScriptableObject destekli**, **event-driven** bir yapıda çalışır.
|
||
|
||
---
|
||
|
||
## 🚀 1. Amaç
|
||
|
||
Bu sistemin hedefi, farklı temalar arasında **anında geçiş** sağlamak ve
|
||
UI öğelerinin görünümünü **kod değiştirmeden** yönetmektir.
|
||
|
||
**Temel Hedefler:**
|
||
- 🎨 Farklı temalar arasında runtime geçiş
|
||
- 🔁 Tema değiştiğinde tüm UI’nın otomatik yenilenmesi
|
||
- 💾 Oyuncunun seçtiği temanın kaydedilmesi (`ThemeData`)
|
||
- 🧩 Enum tabanlı erişim (string hatalarına karşı güvenli)
|
||
- ⚡ `ScriptableObject` tabanlı profil yapısı
|
||
|
||
---
|
||
|
||
## 🧱 2. Sistem Bileşenleri
|
||
|
||
| Bileşen | Açıklama |
|
||
|----------|-----------|
|
||
| **ThemeAssetType** | Görsel tiplerini (ikon, arka plan, vb.) enum olarak listeler |
|
||
| **ThemeProfile** | Tek bir temaya ait sprite eşlemelerini tutar |
|
||
| **ThemeRepository** | Tüm `ThemeProfile` varlıklarını barındırır |
|
||
| **ThemeService** | Aktif temayı yönetir, `ServiceLocator` ile erişilir |
|
||
| **ThemeImage** | UI `Image` bileşenlerine otomatik sprite ataması yapar |
|
||
| **ThemeData** | Oyuncunun aktif temasını ve açılmış temaları saklar |
|
||
|
||
---
|
||
|
||
## 🧩 3. ThemeAssetType.cs
|
||
|
||
UI görsellerinin türlerini `enum` olarak tanımlar.
|
||
Kod içinde string kullanmadan, **type-safe** erişim sağlar.
|
||
|
||
```csharp
|
||
public enum ThemeAssetType
|
||
{
|
||
None = 0,
|
||
|
||
// ICONS
|
||
Icon_SettingsButton,
|
||
Icon_VibrationButton,
|
||
|
||
// BACKGROUNDS
|
||
Background_MainMenu,
|
||
Background_PopupSuccess,
|
||
|
||
// CURRENCIES
|
||
Icon_Currency_Gold,
|
||
Icon_Currency_Gem,
|
||
}
|
||
````
|
||
---
|
||
|
||
## 🗂️ 5. ThemeRepository
|
||
|
||
Tüm temaları tek bir ScriptableObject altında toplar.
|
||
|
||
Örneğin:
|
||
|
||
* `Default`
|
||
* `Dark`
|
||
* `Snow`
|
||
* `Halloween`
|
||
|
||
Unity’de oluşturmak için:
|
||
|
||
> **Right Click → Create → ShiroginSDK → Theme → Theme Repository**
|
||
|
||
Ardından `ThemeProfile` varlıklarını listeye ekle.
|
||
|
||
---
|
||
|
||
## 🧠 6. ThemeService (Yeni Sistem)
|
||
|
||
`ThemeService`, artık `ServiceBase`’ten türetilir ve `ServiceLocator` aracılığıyla erişilir.
|
||
Tüm bağımlılıklarını (`IDataService`, `IEventService`) otomatik çözer.
|
||
|
||
### Başlatma
|
||
|
||
`ShiroginServiceRegistry.InitializeAll();` çağrısı ile otomatik olarak başlatılır.
|
||
`SDKConfig.themeRepository` üzerinden `ThemeRepository` referansını yükler.
|
||
|
||
```csharp
|
||
var themeService = ServiceLocator.Get<IThemeService>();
|
||
themeService.SetTheme("Snow");
|
||
```
|
||
|
||
---
|
||
|
||
### 🎨 Aktif Tema Değiştirme
|
||
|
||
```csharp
|
||
var themeService = ServiceLocator.Get<IThemeService>();
|
||
themeService.SetTheme("Dark");
|
||
```
|
||
|
||
Bu işlem:
|
||
|
||
1. `_repository` içinden “Dark” temasını bulur
|
||
2. `ThemeChanged` event’ini yayınlar
|
||
3. `ThemeData.ActiveTheme`’i kaydeder
|
||
4. Tüm `ThemeImage` bileşenlerini otomatik yeniler
|
||
|
||
---
|
||
|
||
### 🧩 Sprite Alma
|
||
|
||
```csharp
|
||
var themeService = ServiceLocator.Get<IThemeService>();
|
||
var icon = themeService.GetSprite(ThemeAssetType.Icon_SettingsButton);
|
||
myButton.image.sprite = icon;
|
||
```
|
||
|
||
---
|
||
|
||
### 💾 Kaydetme & Yükleme
|
||
|
||
Aktif tema `ThemeData` aracılığıyla otomatik olarak saklanır ve oyun açılışında geri yüklenir.
|
||
|
||
```csharp
|
||
var dataService = ServiceLocator.Get<IDataService>();
|
||
var themeData = dataService.Get<ThemeData>();
|
||
|
||
Debug.Log($"Active Theme: {themeData.ActiveTheme}");
|
||
```
|
||
|
||
---
|
||
|
||
## 🧰 7. ThemeImage.cs
|
||
|
||
Herhangi bir `Image` bileşenine eklenir.
|
||
Seçilen `ThemeAssetType`’a göre sprite’ı otomatik günceller.
|
||
Tema değiştiğinde event’ler aracılığıyla yeniden sprite ataması yapılır.
|
||
|
||
**Kullanım:**
|
||
|
||
1. UI objene `ThemeImage` component’i ekle
|
||
2. `assetType` alanında örneğin `Icon_SettingsButton` seç
|
||
3. Tema değiştiğinde sprite otomatik değişir
|
||
|
||
---
|
||
|
||
## 💾 8. ThemeData.cs
|
||
|
||
Oyuncunun aktif temasını ve açılmış temalarını saklar.
|
||
Oyun açılışında `DataService` tarafından otomatik yüklenir.
|
||
|
||
```csharp
|
||
public class ThemeData : BaseData
|
||
{
|
||
protected override string PrefsKey => "THEME_DATA";
|
||
|
||
public string ActiveTheme = "Default";
|
||
public List<string> UnlockedThemes = new() { "Default" };
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 9. Akış Mantığı
|
||
|
||
```
|
||
[SDKInitializer]
|
||
↓
|
||
ThemeService → Load from ThemeRepository
|
||
↓
|
||
ThemeData.ActiveTheme → Set Active
|
||
↓
|
||
ThemeChanged Event
|
||
↓
|
||
ThemeImage components update automatically
|
||
```
|
||
|
||
---
|
||
|
||
## 🌈 10. Tema Geçişi Örneği
|
||
|
||
```csharp
|
||
using ShiroginSDK.Runtime.Services.Interfaces;
|
||
using UnityEngine;
|
||
|
||
public class ThemeSwitcher : MonoBehaviour
|
||
{
|
||
public void OnClick_SnowTheme()
|
||
{
|
||
ServiceLocator.Get<IThemeService>().SetTheme("Snow");
|
||
}
|
||
|
||
public void OnClick_DefaultTheme()
|
||
{
|
||
ServiceLocator.Get<IThemeService>().SetTheme("Default");
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🌟 11. Özellikler
|
||
|
||
| Özellik | Açıklama |
|
||
| ---------------------------- | -------------------------------------------- |
|
||
| 💾 Kalıcı Kayıt | `ThemeData` aracılığıyla otomatik kaydedilir |
|
||
| 🔄 Gerçek Zamanlı Güncelleme | Tema değişince tüm UI otomatik yenilenir |
|
||
| 🧩 Modüler | Yeni tema eklemek yalnızca 1 dakika sürer |
|
||
| 🎨 Editor Dostu | ScriptableObject tabanlı sistem |
|
||
| ⚡ Optimize | Sadece aktif tema bellekte tutulur |
|
||
| 🧱 Tip Güvenli | Enum tabanlı erişim ile string hatası yok |
|
||
|
||
---
|
||
|
||
## 💡 12. Geliştirici Tavsiyeleri
|
||
|
||
* Her temaya kısa, net bir isim ver (`Default`, `Dark`, `Snow`)
|
||
* Sprite atlaslarını kullanarak performansı artır
|
||
* `ThemeImage` ile manuel sprite değişiminden kaçın
|
||
* Tema varlıklarını düzenli tut (`Assets/ShiroginSDK/Themes/`)
|
||
* `ThemeRepository` içine tüm temaları dahil etmeyi unutma
|
||
|
||
---
|
||
|
||
## ✅ 13. Özet
|
||
|
||
ShiroginSDK Theme System v1.0.0:
|
||
|
||
* UI görsellerini tek yerden yönetmeni sağlar
|
||
* Oyuncu seçimini kaydeder ve yeniden yükler
|
||
* Enum tabanlı tip güvenli sistemle çalışır
|
||
* `ServiceLocator` mimarisiyle SDK’nın diğer servisleriyle uyumludur
|
||
|
||
---
|
||
|
||
**Prepared by:** Emir Han MAMAK
|
||
|
||
**Version:** 1.1.0 (2025.12)
|
||
|
||
**Module:** ShiroginSDK.Runtime.Services.Implementations.UI.ThemeService
|
||
|
||
---
|
||
**Scriptable Objects :**
|
||
|
||
|
||
|
||
|