العملات والمحافظ

العملات هي الوحدات التي يقوم عليها اقتصادك — قطع نقدية، أو جواهر، أو طاقة، أو أي شيء آخر. وتُعرّف كل لعبة عملاتها الخاصة، ولكل لاعب محفظة تحمل أرصدته.

النطاق: تُعرَّف العملات لكل إصدار لعبة؛ ولكل لاعب محفظة تضمّ أرصدته.

لوحة التحكم
Unity
Unreal

ثلاثة مصطلحات أولًا:

إعداد العملات (currency config) هو الإعداد الوحيد في إصدار اللعبة الذي يسرد عملاته. وGame Currencies عملات تُكتسب أو تُشترى داخل اللعبة، كالقطع النقدية أو الجواهر. وReal Currencies مال حقيقي، مثل USD أو SAR، يمكن تسعير العنصر به حين يبيعه متجر أو دفعٌ عبر صفحة ويب.
قالب اللاعب (player template) يصف سجلًّا واحدًا يحفظه Flock لكل لاعب: حقوله وقيمها الابتدائية. ويُنشئ حفظُ إعداد العملات قالبَ لاعب موسومًا currency نيابةً عنك.
المحفظة هي ذلك السجل للاعب واحد: رصيد لكل عملة، يُبنى من قالب currency.

اضبطها في Flock بهذا الترتيب (نذكر الأسماء كما تظهر في لوحة التحكم بالإنجليزية):

من القائمة أعلى الصفحة، اختر لعبتك وإصدار اللعبة الذي يشغّله بناؤك.
افتح Monetization → Currencies. وعنوان الصفحة Currency Configuration. أبقِ Config Name المقترح أو اكتب اسمًا من عندك.
في تبويب Game Currencies اضغط Add Game Currency واملأ Currency Name (ما يقرؤه اللاعبون، مثل Gold) والرمز (مثل GOLD) الذي تستخدمه لعبتك في استدعاءاتها. وتحتفظ الرموز بحالة أحرفها، ويجب ألّا يتكرر رمز بين عملات اللعبة والعملات الحقيقية.
لتبيع عناصر بمال حقيقي، افتح تبويب Real Currencies واضغط Add Real Currency، وأعطِ كل عملة رمز ISO 4217 بأحرف كبيرة، مثل USD أو EUR أو SAR.
اضغط Create Currency Config (وUpdate Currencies بعد وجوده). علامة النجاح: تقول الصفحة إن إعداد العملات أُنشئ.
افتح Player Management → Player Template. علامة النجاح: يظهر قالب موسوم currency للقراءة فقط: فهو لا يتغيّر إلا من Monetization → Currencies.
سجّل لاعب الاختبار الآن فقط. علامة النجاح: تسرد صفحة Monetization → Wallets اللاعب تحت Player Wallets، وكل أرصدته صفر.

تُنشأ المحفظة حين يسجّل اللاعب، من قالب currency في إصدار اللعبة الذي يرسله البناء. فاللاعب الذي سجّل قبل وجود ذلك القالب لا محفظة له، ولا يُنشئ تسجيل دخوله لاحقًا محفظة: سجّل لاعب اختبار جديدًا. أما اللاعب الذي أُنشئت محفظته تحت إصدار آخر فيحتفظ بها: إذ ينقلها الخادم عند تسجيل الدخول إلى قالب currency في الإصدار الجديد، مع بقاء الأرصدة وبدء العملات الجديدة من الصفر.ويُقفَل الإصدار المنشور إلى Production: فلا تتغيّر عملاته بعدها إلا عبر رقعة (patch).

صفحة Currency Configuration وفيها ثلاث عملات للعبة: Gold وCrystals وSouls — Monetization → Currencies: تبويب Game Currencies في إعداد العملات.

تُضيف AddGameFundsAsync رصيدًا إلى محفظة اللاعب المسجَّل دخوله. وتجد حزمة التطوير قالب اللاعب الموسوم currency نيابةً عنك. وبعد Sync Schemas (تبويب Code Generation في Flock → Settings) تأخذ نسخةٌ مُولَّدة FlockFundId وتحمل معرّف القالب، فيتخطّى الاستدعاء ذلك البحث. وتعمل الأمثلة في هذا التبويب داخل دالة async.

using Flock;
using Flock.Generated.Shops;
using Flock.Models;

// منح رصيد. يجد القالب الموسوم "currency" أثناء التشغيل. وتُطابَق الرموز بحالة أحرفها.
PlayerData walletRow = await FlockClient.Instance.Commands.AddGameFundsAsync("Gold", 500);

// بعد Sync Schemas، بعملة مُحدَّدة النوع:
walletRow = await FlockClient.Instance.Commands.AddGameFundsAsync(FlockFundId.Gold, 500);

اقرأ الأرصدة. تقرأ Player.GetWalletAsync محفظة اللاعب المسجَّل دخوله في صورة FlockWallet، وكل رصيد فيها تحت رمز عملته. وفي هذا المثال item عنصر ShopItem مقروء من متجره (انظر المتاجر والمخزون).

using System.Collections.Generic;
using Flock;
using Flock.Models;
using UnityEngine;

FlockWallet balances = await FlockClient.Instance.Player.GetWalletAsync();

long gold = balances.BalanceOf("Gold");        // ‏0 حين لا يكون في المحفظة Gold
bool hasGems = balances.Holds("Gems");         // هل في المحفظة رصيد Gems أصلًا
bool canBuy = balances.CanAfford(item);        // ما يكفي من عملة العنصر لسعره

foreach (KeyValuePair<string, long> currency in balances.GameCurrencies)
    Debug.Log($"{currency.Value} {currency.Key}");

وتُقرأ المحفظة عبر ذاكرة بيانات اللاعب المؤقتة، التي تُبقيها عمليات الشراء والمنح محدَّثة. وتكون CanAfford خاطئة لعنصر بمال حقيقي، يبيعه متجر أو دفع عبر الويب. ويحمل ردّ عملية الشراء المحفظةَ بعدها حين تتحرّك عملة: bought.Balances?.BalanceOf("Gold")، وBalances فارغة (null) حين لا تتحرّك أي عملة.تُنشأ المحفظة حين يسجّل اللاعب. يبني الخادم محفظة كل لاعب من قالب العملات في إصدار اللعبة عند التسجيل، وكل عملة تبدأ من الصفر (ويُنشأ سجلّ إنجازات اللاعب بالطريقة نفسها، من القالب الموسوم achievement). فاللاعب الذي سجّل وإصدار لعبته بلا قالب عملات لا محفظة له، ولا يصنعها له تسجيل دخول لاحق: ترمي GetWalletAsync الاستثناء FlockValidationException، ويفشل الشراء بـShopWalletNotFound. أنشئ قالب العملات أولًا، ثم سجّل اللاعب تحت إصدار اللعبة الذي تعمل به هذه النسخة.لاعب اختبار جديد. لاعب الاختبار الذي صنعته في البداية السريعة قبل وجود قالب العملات لا محفظة له. ولصنع لاعب جديد، استدعِ FlockClient.Instance.Authentication.Logout() مرة واحدة (فتنسى الحزمة تسجيل الدخول المحفوظ، لكنها تُبقي معرّف الجهاز)، ثم إمّا أن تحذف معرّف الجهاز المحفوظ، أي الملف Flock/device_id.txt تحت Application.persistentDataPath (اطبع Application.persistentDataPath في السجل لترى مكانه؛ والحزمة تنسى المعرّف الذي قرأته عند كل ضغطة Play، فتصنع الضغطة التالية معرّفًا جديدًا)، وإمّا أن تمرّر معرّف جهاز جديدًا خاصًا بك، مثل Guid.NewGuid().ToString()، إلى استدعاءات الدخول بالجهاز. ثم اضغط Play مجددًا: فيسجّل التشغيل التالي لاعبًا جديدًا له محفظة. وتبدأ أرصدته من الصفر؛ فامنحه عملة ينفقها بـAddGameFundsAsync كما سبق.منح الأرصدة آمن ماليًا. فالمنح يفشل بدل أن يُصفّ في طابور حين يتعذّر الوصول إلى الخادم، ولا يُعاد إرساله أبدًا بعد فشل غامض — إذ قد يعني انتهاء المهلة أن الرصيد أُضيف فعلًا، ولن تخاطر حزمة التطوير بإضافته مرتين. ولا يُعاد إلا ما لم يعالجه الخادم قطعًا (408/429)، لذا غلِّف الاستدعاء بـtry/catch. وحين لا يقول أي ردّ هل أُضيف الرصيد أم لا، تكون OutcomeUnknown في الاستثناء صحيحة: اقرأ المحفظة قبل المنح مجددًا.

using Flock;
using Flock.Exceptions;
using Flock.Models;
using UnityEngine;

try
{
    await FlockClient.Instance.Commands.AddGameFundsAsync("Gold", 500);
}
catch (FlockException e) when (e.OutcomeUnknown)
{
    FlockWallet now = await FlockClient.Instance.Player.GetWalletAsync();   // هل أُضيف؟
    Debug.Log($"Gold is now {now.BalanceOf("Gold")}");
}

في FlockFundId عضو لكل عملة تُسعَّر بها عناصر متاجرك، باسم رمز العملة كما هو مكتوب: تبقى الأحرف الكبيرة والصغيرة على حالها، ويصير كل حرف ليس حرفًا أو رقمًا شرطةً سفلية، وتُضاف شرطة سفلية في البداية حين يبدأ الرمز برقم (GOLD يعطي FlockFundId.GOLD). وFlockFundId.Gold أعلاه يمثّل عملةً رمزها Gold. زامِن مجددًا بعد إضافة عملة.

تُضيف AddGameFunds (العقدة Flock Add Game Funds) رصيدًا إلى محفظة اللاعب المسجَّل دخوله. وتتكفّل حزمة التطوير بإيجاد القالب الموسوم بـ currency، ومزامنة المخطّط تُضمِّن معرّفه فيتخطّى الاستدعاء هذا البحث. ويسرد FlockCurrencyId الذي تولّده المزامنة عملات اللعبة التي تسعّر بها متاجرك العناصر، أي الأرصدة التي يمكن أن يمنحها المنح؛ ولا تكون عملة عنصر بأموال حقيقية منها أبدًا (أما العنصر نفسه فيبقى في FlockShopItemId).

#include "FlockSubsystem.h"
#include "Providers/FlockCommandProvider.h"
#include "Providers/FlockPlayerProvider.h"

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);   // this: any object in the game's world

// Grant. Resolves the "currency"-tagged template at runtime.
Sdk->GetCommandProvider()->AddGameFunds(TEXT("coins"), 250, [](TFlockResult<FFlockPlayerData> Credited)
{
    if (!Credited.bSuccess && Credited.Error.bOutcomeUnknown)
    {
        // No answer said whether the grant landed: read the wallet before granting again.
    }
});

// After Code Generation's sync, with a typed currency:
FFlockGenerated::AddFunds(this, EFlockCurrencyId::Gold, 100, [](TFlockResult<FFlockPlayerData> Credited) {});

اقرأ الأرصدة. تقرأ GetWallet محفظة اللاعب المسجَّل دخوله حسب رمز العملة.

// Item: an FFlockShopItem read from its shop.
Sdk->GetPlayerProvider()->GetWallet([Item](TFlockResult<FFlockWallet> Read)
{
    if (!Read.bSuccess)
    {
        UE_LOG(LogTemp, Warning, TEXT("%s"), *Read.Error.ToDisplayText());   // e.g. no wallet in this Game Version
        return;
    }
    const FFlockWallet& Wallet = Read.Value;

    const int64 Gold = Wallet.BalanceOf(TEXT("Gold"));   // 0 when the wallet has no Gold
    const bool bHasGems = Wallet.Holds(TEXT("Gems"));    // whether the wallet has a Gems balance at all
    const bool bCanBuy = Wallet.CanAfford(Item);         // enough of the item's currency for its price

    for (const FFlockCurrencyBalance& Currency : Wallet.GameCurrencies)
    {
        UE_LOG(LogTemp, Display, TEXT("%lld %s"), Currency.Amount, *Currency.Code);
    }
});

تُقرأ المحفظة عبر ذاكرة بيانات اللاعب المؤقتة، التي تُبقيها عمليات الشراء والمنح محدَّثة. ويفشل اللاعب الذي لا صفّ محفظة له في إصدار اللعبة هذا (Validation). وتُطابَق رموز العملات بحالة أحرفها. وتكون CanAfford خاطئة للعنصر المدفوع بمال حقيقي، الذي يبيعه متجر. ولا يحمل ردّ عملية الشراء المحفظةَ بعدها إلا حين تتحرك عملة: تحقّق من Bought.Value.HasWallet() أولًا، ثم اقرأ FFlockWallet::From(Bought.Value.Wallet). أما عملية الشراء بمال حقيقي عبر الدفع بصفحة ويب، والعملية التي لا تزال معلّقة، فلا تحملان محفظة: استدعِ GetWallet بعدهما (وبعد دفع ناجح عبر صفحة ويب تسأل الخادم).وفي Blueprint تقرؤها Flock Get Wallet (تحت Flock | Player)؛ واسأل Wallet Balance Of وWallet Holds وCan Afford عن Wallet الخاصة بها، وPurchase Balances عن نتيجة عملية شراء متى كانت Has Wallet صحيحة لها.عمليات المنح آمنة ماليًا. فالمنح يفشل بدل أن يُصفّ في طابور حين يتعذّر الوصول إلى الخادم، ولا يُعاد إرساله أبدًا بعد فشل غامض — إذ قد يعني انتهاء المهلة أن الرصيد أُضيف فعلًا، ولن تخاطر حزمة التطوير بإضافته مرتين. وحين لا يقول أي ردّ هل وصل المنح، تكون bOutcomeUnknown في الخطأ صحيحة: اقرأ المحفظة قبل أن تمنح من جديد.

تخصم عمليات الشراء من المتجر من المحفظة المعنية تلقائيًا كجزء من المعاملة — فلا داعي لتعديل الأرصدة بيدك في أي عملية شراء اعتيادية.

بدء الاستخدام

المفاهيم

الميزات

المرجع

العملات والمحافظ