Playvoi/Assets/ShiroginSDK/Runtime/Modules/Data/Scripts/README.md at 080b594bc6ee47be3105d7ff29d99a14da6a8333

EmirHanMamak 080b594bc6 chore(sdk): add SDK to project

2026-01-16 23:14:13 +03:00

9.4 KiB

Raw Blame History

# 📦 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

namespace ShiroginSDK.Runtime.Data.Enums
{
    public enum ItemType
    {
        Consumable,
        Permanent,
        Skin,
        Character,
        Booster,
        Currency
    }
}

OwnedItem.cs

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:

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:

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:

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:

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:

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:

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:

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:

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:

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();

9.4 KiB Raw Blame History Unescape Escape

🧑‍🚀 PlayerData – Oyuncu Profili

💰 EconomyData – Para Sistemi

🎒 InventoryData – Envanter

📈 ProgressionData – Bölüm ve Skor Takibi

⚙️ SettingsData – Kullanıcı Ayarları

🛒 StoreData – Mağaza

🎁 RewardData – Ödül Sistemi

📱 DeviceData – Cihaz Bilgileri

📡 DataService ile Kullanım

🧪 İyi Uygulama Önerileri

🏁 Sonuç

9.4 KiB

Raw Blame History