425 lines
9.4 KiB
Markdown
425 lines
9.4 KiB
Markdown
```markdown
|
||
# 📦 ShiroginSDK Data System
|
||
|
||
ShiroginSDK’nin **Data** modülü, oyun içindeki tüm kalıcı verilerin yönetimi için profesyonel, modüler ve ölçeklenebilir bir mimari sunar.
|
||
Her veri tipi `BaseData`’dan türetilir ve yalnızca kendi alanından sorumludur. Böylece oyun büyüdükçe bakım kolaylaşır, test yazmak kolaylaşır ve veri yapısı değişiklikleri diğer sistemleri etkilemez.
|
||
|
||
---
|
||
|
||
## 🧠 Mimari Özeti
|
||
|
||
Tüm veri tipleri `BaseData` sınıfını kalıtım alır ve yalnızca kendi görevini yerine getirir:
|
||
|
||
```
|
||
|
||
BaseData
|
||
├─ PlayerData → Oyuncu profili ve XP/Level bilgisi
|
||
├─ EconomyData → Para birimleri ve satın alma işlemleri
|
||
├─ InventoryData → Eşyalar, kozmetikler, karakter kilitleri
|
||
├─ ProgressionData → Bölümler, skorlar, başarımlar
|
||
├─ SettingsData → Ses, dil, grafik, titreşim vb.
|
||
├─ StoreData → Mağaza/teklif görünümü ve satın alma geçmişi
|
||
├─ RewardData → Günlük giriş, reklam ödülleri, cooldown’lar
|
||
└─ DeviceData → Cihaz/uygulama bilgisi (telemetri)
|
||
|
||
```
|
||
|
||
> `BaseData` kaydetme/yükleme (`serialization`) davranışını soyutlar. Her alt sınıf yalnızca kendi state’ini yönetir.
|
||
|
||
---
|
||
|
||
## 📁 Klasör Yapısı Önerisi
|
||
|
||
```
|
||
|
||
Assets/
|
||
└─ ShiroginSDK/
|
||
└─ Runtime/
|
||
└─ Data/
|
||
├─ BaseData.cs
|
||
├─ PlayerData.cs
|
||
├─ EconomyData.cs
|
||
├─ InventoryData.cs
|
||
├─ ProgressionData.cs
|
||
├─ SettingsData.cs
|
||
├─ StoreData.cs
|
||
├─ RewardData.cs
|
||
├─ DeviceData.cs
|
||
├─ Enums/
|
||
│ ├─ CurrencyType.cs
|
||
│ └─ ItemType.cs
|
||
└─ Models/
|
||
└─ OwnedItem.cs
|
||
|
||
````
|
||
|
||
---
|
||
|
||
## 📘 Destekleyici Tipler
|
||
|
||
**CurrencyType.cs**
|
||
|
||
```csharp
|
||
namespace ShiroginSDK.Runtime.Data.Enums
|
||
{
|
||
public enum CurrencyType
|
||
{
|
||
Gems,
|
||
Gold
|
||
}
|
||
}
|
||
````
|
||
|
||
**ItemType.cs**
|
||
|
||
```csharp
|
||
namespace ShiroginSDK.Runtime.Data.Enums
|
||
{
|
||
public enum ItemType
|
||
{
|
||
Consumable,
|
||
Permanent,
|
||
Skin,
|
||
Character,
|
||
Booster,
|
||
Currency
|
||
}
|
||
}
|
||
```
|
||
|
||
**OwnedItem.cs**
|
||
|
||
```csharp
|
||
using System;
|
||
using ShiroginSDK.Runtime.Data.Enums;
|
||
|
||
namespace ShiroginSDK.Runtime.Data.Models
|
||
{
|
||
[Serializable]
|
||
public class OwnedItem
|
||
{
|
||
public string ItemId;
|
||
public ItemType ItemType;
|
||
public int Quantity;
|
||
|
||
public OwnedItem(string id, ItemType type, int quantity = 1)
|
||
{
|
||
ItemId = id;
|
||
ItemType = type;
|
||
Quantity = quantity;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧑🚀 PlayerData – Oyuncu Profili
|
||
|
||
Oyuncunun temel profil bilgilerini, seviye/XP durumunu ve öğretici adımlarını yönetir.
|
||
|
||
**Alanlar:**
|
||
|
||
* `PlayerId`, `Level`, `Xp`
|
||
* `BaseXpPerLevel`, `XpGrowth`
|
||
* `TutorialStep`
|
||
* `CompletedFlags`
|
||
|
||
**Fonksiyonlar:**
|
||
|
||
* `AddXp(amount)` – XP ekler, gerekirse level atlatır
|
||
* `GetRequiredXpForLevel(level)` – level başına gereken XP
|
||
* `AdvanceTutorial(step)` – öğretici adım ilerletir
|
||
* `SetFlag(flagId)` – özel olay tamamlandı işaretler
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var player = DataService.Load<PlayerData>();
|
||
player.AddXp(250);
|
||
if (!player.HasFlag("first_shop"))
|
||
player.SetFlag("first_shop");
|
||
```
|
||
|
||
---
|
||
|
||
## 💰 EconomyData – Para Sistemi
|
||
|
||
Soft/hard currency yönetimi, ödeme ve kontrol işlemlerini yapar.
|
||
|
||
**Alanlar:**
|
||
|
||
* `Gems`, `Gold`
|
||
|
||
**Fonksiyonlar:**
|
||
|
||
* `AddCurrency(type, amount)` – para ekle
|
||
* `SpendCurrency(type, amount)` – harca
|
||
* `HasEnough(type, amount)` – yeterli mi kontrol et
|
||
* `TryPurchase(price, type)` – satın alma işlemi yap
|
||
* `TryMultiPurchase(Dictionary<CurrencyType,int>)` – çoklu para ile satın alma
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var economy = DataService.Load<EconomyData>();
|
||
economy.AddCurrency(CurrencyType.Gold, 500);
|
||
if (economy.TryPurchase(50, CurrencyType.Gold)) {
|
||
Debug.Log("Satın alma başarılı!");
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎒 InventoryData – Envanter
|
||
|
||
Oyuncunun sahip olduğu eşyaları, kozmetikleri ve karakterleri yönetir.
|
||
|
||
**Alanlar:**
|
||
|
||
* `Items : List<OwnedItem>`
|
||
* `UnlockedCharacters : List<int>`
|
||
|
||
**Fonksiyonlar:**
|
||
|
||
* `AddItem(id, type, amount)` – eşya ekle
|
||
* `RemoveItem(id, amount)` – eşya sil
|
||
* `HasItem(id)` – eşya var mı
|
||
* `UnlockCharacter(id)` – karakter aç
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var inventory = DataService.Load<InventoryData>();
|
||
inventory.AddItem("potion_small", ItemType.Consumable, 3);
|
||
if (inventory.HasItem("potion_small"))
|
||
inventory.RemoveItem("potion_small", 1);
|
||
```
|
||
|
||
---
|
||
|
||
## 📈 ProgressionData – Bölüm ve Skor Takibi
|
||
|
||
Bölümler, skorlar ve başarımlar gibi ilerlemeleri saklar.
|
||
|
||
**Alanlar:**
|
||
|
||
* `Levels : List<LevelProgress>`
|
||
* `Achievements : List<string>`
|
||
|
||
**Fonksiyonlar:**
|
||
|
||
* `SetCompleted(levelId)` – bölüm tamamlandı
|
||
* `SubmitScore(levelId, score)` – skor gönder
|
||
* `SetStars(levelId, stars)` – yıldız puanı ayarla
|
||
* `UnlockAchievement(id)` – başarı aç
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var progress = DataService.Load<ProgressionData>();
|
||
progress.SubmitScore("Level_05", 12000);
|
||
progress.SetStars("Level_05", 3);
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ SettingsData – Kullanıcı Ayarları
|
||
|
||
Oyuncunun cihaz ayarlarını ve tercihlerini saklar.
|
||
|
||
**Alanlar:**
|
||
|
||
* `MusicVolume`, `SfxVolume`
|
||
* `Vibration`, `NotificationsEnabled`
|
||
* `LanguageCode`, `GraphicsQualityIndex`
|
||
|
||
**Fonksiyonlar:**
|
||
|
||
* `SetMusicVolume(v)`
|
||
* `SetLanguage(code)`
|
||
* `SetVibration(on)`
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var settings = DataService.Load<SettingsData>();
|
||
settings.SetLanguage("tr");
|
||
settings.SetMusicVolume(0.5f);
|
||
```
|
||
|
||
---
|
||
|
||
## 🛒 StoreData – Mağaza
|
||
|
||
Satın alma geçmişi, teklif durumu ve mağaza yenilenme zamanını yönetir.
|
||
|
||
**Alanlar:**
|
||
|
||
* `Purchases : List<ProductPurchase>`
|
||
* `LimitedOffers : List<LimitedOfferState>`
|
||
|
||
**Fonksiyonlar:**
|
||
|
||
* `MarkPurchased(productId)` – satın alma işlemini kaydet
|
||
* `UpsertOffer(offerId, expireUnix)` – teklif oluştur/güncelle
|
||
* `IsOfferActive(offerId)` – teklif aktif mi kontrol et
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var store = DataService.Load<StoreData>();
|
||
store.UpsertOffer("starter_pack", DateTimeOffset.UtcNow.AddDays(3).ToUnixTimeSeconds());
|
||
if (store.IsOfferActive("starter_pack")) { /* göster */ }
|
||
```
|
||
|
||
---
|
||
|
||
## 🎁 RewardData – Ödül Sistemi
|
||
|
||
Günlük giriş ödülleri, reklam ödülleri ve cooldown’ları yönetir.
|
||
|
||
**Alanlar:**
|
||
|
||
* `DailyStreak`, `LastDailyClaimUnix`
|
||
* `AdPlacements : List<AdPlacementState>`
|
||
|
||
**Fonksiyonlar:**
|
||
|
||
* `ClaimDaily()` – günlük ödül al
|
||
* `UpsertAdPlacement(id, cooldown)` – reklam tanımla
|
||
* `CanClaimAdReward(id)` – ödül alınabilir mi
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var rewards = DataService.Load<RewardData>();
|
||
if (rewards.ClaimDaily()) {
|
||
economy.AddCurrency(CurrencyType.Gems, 10);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 DeviceData – Cihaz Bilgileri
|
||
|
||
Analitik ve hata raporlama için cihaz bilgilerini saklar.
|
||
|
||
**Alanlar:**
|
||
|
||
* `DeviceModel`, `OperatingSystem`, `CpuType`
|
||
* `SystemMemoryMB`, `GpuName`, `ScreenWidth`, `ScreenHeight`
|
||
|
||
**Fonksiyonlar:**
|
||
|
||
* `RefreshFromSystem()` – cihaz bilgilerini güncelle
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var device = DataService.Load<DeviceData>();
|
||
device.RefreshFromSystem();
|
||
Debug.Log(device.DeviceModel);
|
||
```
|
||
|
||
---
|
||
|
||
## 📡 DataService ile Kullanım
|
||
|
||
Tüm data sınıfları tek satırla yüklenebilir:
|
||
|
||
```csharp
|
||
var player = DataService.Load<PlayerData>();
|
||
var economy = DataService.Load<EconomyData>();
|
||
var inventory = DataService.Load<InventoryData>();
|
||
var progression= DataService.Load<ProgressionData>();
|
||
var settings = DataService.Load<SettingsData>();
|
||
var store = DataService.Load<StoreData>();
|
||
var rewards = DataService.Load<RewardData>();
|
||
var device = DataService.Load<DeviceData>();
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 İyi Uygulama Önerileri
|
||
|
||
✅ Her sistemi ayrı `Data` sınıfında izole et.
|
||
✅ `Save()` işlemini yalnızca state değiştiğinde çağır.
|
||
✅ JSON yapısını sade ve düz tut.
|
||
✅ Versiyonlama kullanarak veri yapısını büyüt.
|
||
✅ Remote Config ile değerleri dışarıdan yönet.
|
||
|
||
---
|
||
|
||
## 🏁 Sonuç
|
||
|
||
Bu yapı, küçük bir prototipten milyon kullanıcıya sahip canlı servis oyunlara kadar sorunsuzca ölçeklenebilir.
|
||
Her veri sınıfı tek bir amaca odaklanır ve SDK’nız profesyonel bir oyun stüdyosu standardına ulaşır.
|
||
|
||
---
|
||
|
||
**ShiroginSDK – Build Once. Scale Forever.** 🚀
|
||
|
||
```
|
||
---
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Hızlı Kullanım Ornekleri
|
||
// Yükleme
|
||
var player = DataService.Load<PlayerData>();
|
||
var economy = DataService.Load<EconomyData>();
|
||
var inventory = DataService.Load<InventoryData>();
|
||
var progress = DataService.Load<ProgressionData>();
|
||
var settings = DataService.Load<SettingsData>();
|
||
var store = DataService.Load<StoreData>();
|
||
var rewards = DataService.Load<RewardData>();
|
||
var device = DataService.Load<DeviceData>();
|
||
|
||
// Ekonomi
|
||
economy.AddCurrency(Enums.CurrencyType.Gold, 500);
|
||
economy.TryPurchase(50, Enums.CurrencyType.Gold,
|
||
onSuccess: () => inventory.UnlockCharacter(2));
|
||
|
||
// Envanter
|
||
inventory.AddItem("health_potion_s", Enums.ItemType.Consumable, 3);
|
||
bool used = inventory.RemoveItem("health_potion_s", 1);
|
||
|
||
// Progress
|
||
progress.SubmitScore("Level_05", 12000);
|
||
progress.SetStars("Level_05", 3);
|
||
progress.SetCompleted("Level_05");
|
||
|
||
// Settings
|
||
settings.SetLanguage("tr");
|
||
settings.SetTargetFps(120);
|
||
|
||
// Store
|
||
store.UpsertOffer("starter_pack", expireUnix: DateTimeOffset.UtcNow.AddDays(3).ToUnixTimeSeconds());
|
||
if (store.IsOfferActive("starter_pack")) { /* UI'da göster */ }
|
||
|
||
// Rewards
|
||
if (rewards.ClaimDaily()) { economy.AddCurrency(Enums.CurrencyType.Gems, 5); }
|
||
rewards.UpsertAdPlacement("rv_double_gold", cooldownSeconds: 1800);
|
||
if (rewards.CanClaimAdReward("rv_double_gold")) { /* reklam göster */ }
|
||
|
||
// Device
|
||
device.RefreshFromSystem();
|