From a28d875eeb8f27704304f707c27288cfc412e3bc Mon Sep 17 00:00:00 2001 From: Piotr Siuszko Date: Wed, 16 Oct 2024 16:39:53 +0200 Subject: [PATCH] Stats and Inventory docs update --- Docs/docs/features/inventory.md | 19 +++++++++++++++---- Docs/docs/features/stats.md | 26 +++++++++++++++----------- Docs/docs/guides/runtime-concepts.md | 7 +++++++ 3 files changed, 37 insertions(+), 15 deletions(-) diff --git a/Docs/docs/features/inventory.md b/Docs/docs/features/inventory.md index 04b4820c..2c772e15 100644 --- a/Docs/docs/features/inventory.md +++ b/Docs/docs/features/inventory.md @@ -17,10 +17,21 @@ Beamable's Inventory system is built on the Content feature. This means that con ## Data Concepts -Inventory manages two types of data- items and virtual currencies. One thing that both have in common is that during creation of each of them it is up to game maker to decide how they can be added to player inventory by specifying `Write self` property: +Inventory manages two types of data- items and virtual currencies. One thing that both have in common is that during creation of each of them it is up to game maker to decide how they can be added to player inventory by specifying `clientPermission` field: -- **Client-Authoritative**- If your game does not include networked multiplayer and can tolerate cheating, allowing the client to read/write their own currencies is the simplest option. -- **Server-Authoritative**- A much more secure way to handle item/currency modifications is via a Microservice. In this scenario, the client is not able to modify their currencies directly, it is handled on the server. +- **Client-Authoritative**- If your game does not include networked multiplayer and can tolerate cheating, allowing the client to read and write their own currencies is the simplest option. +- **Server-Authoritative**- A much more secure way to handle item/currency modifications is via a Microservice. In this scenario, the client is not able to modify their currencies directly, it is handled on the server. It can still read it from Unreal. !!! note "Edit player Inventory via Portal" - Regardlesss of the value of the `Write self` property it is possible to view and modify players inventory through the Portal. More info [here](https://docs.beamable.com/docs/portal-inventory). \ No newline at end of file + Regardlesss of the value of the `clientPermission` field it is possible to view and modify players inventory through the Portal. More info [here](https://docs.beamable.com/docs/portal-inventory). + +### Virtual Currencies + +This feature is flexible enough to meet the currency needs of any game's design. Currencies are used to buy items (e.g., Gold) and to symbolize the player's progress through the game, such as experience points (XP). + +The Virtual Currency system in Beamable is built on top of the Content system. Currencies are available out of the box in the Beamable SDK as a content type. + +In Unreal SDK Currency is represented by `FBeamCurrencyContent` type. Besides decribed earlier `clientPermission` each Currency type contains `startingAmount` field specifying how many currency is player starting with. + +### Items + diff --git a/Docs/docs/features/stats.md b/Docs/docs/features/stats.md index 6f029673..c29bfff6 100644 --- a/Docs/docs/features/stats.md +++ b/Docs/docs/features/stats.md @@ -9,36 +9,40 @@ img[src*='#center'] { ## Overview The Beamable SDK Stats feature allows player to track a variety of built-in and custom player stat variables with configurable visibility levels. Two main use cases are: -- Data Store- a simple place to read/write info about player -- Targeting- Stats can be the vector for player segmentation (Ex. A/B testing, targeted offer, focused message campaign, announcement for subset of player-base) + +- **Data Store**- can hold key/value pairs associated with a particular user. +- **Targeting**- These key/value pairs can be used by other Beamable systems for various things (Announcement Campaings, Matchmaking and others). ## Types of stats There are two important specifiers of each stat. First one is `visibility`, in Unreal represented by enum `EBeamStatsVisibility`, it describes who can see stat: -- `private`- this one is visible to owning Player and Backend. -- `public`- Public client stats can be retrieved by anyone who knows ID of the user. +- `private`- Visible only to owning User and Backend. +- `public`- Visible to any User. Second one is stat `domain`, in Unreal represented by enum `EBeamStatsDomain`, it describes if stat can be retrieved from game itself or does it require using microservices: -- `client`- this one can be accessed from both the game and microservices. -- `game`- this one cannot be accessed from Unreal directly, it can still be accessed and/or updated from microservice. + +- `client`- Can be accessed from both the **Unreal** and **Microservices**. +- `game`- Cannot be accessed from **Unreal** directly, it can still be accessed via **Microservice** using `ClientCallable` calls. ## Getting started In order to create first Stats commit with Blueprints we will use `BeamStatsSubsystem` created for that purpose. -!!! note "C++ version" - In order to achieve same effect as in this blueprint example in C++ it is possible to follow guide below. In order to achieve that replace calls to `BeamStatSubsystem` commands with the same ones with `CPP_` prefix if that version exists and use same ones if version without it does not exists. That means using `CPP_CommitStatsOperation` instead of `CommitStatsOperation`, but `TryCreateUpdateCommand` in both Blueprint and C++ version. - !!! note "Subsystem assumptions" - Make sure that user account is created, logged in and blueprint is not performed before `OnReady` call from `UBeamRuntimeSubsystem`. + Make sure that user is logged in. See [Runtime Concepts](../guides/runtime-concepts.md) First there should be created a update command with `Try Create Update Command` with new stats values. Then we need to commit that stats update operation using `Commit Stats Operation` in order to send them to Beamable backend. That is it! ![unreal-beamable-stats-create](./images/stats-create-stats.png) -Then if we open Beamable portal, go to `Engage->Players`, find used player and go to Stats and search for `NewStatKey` there should be visible that it exists with correct value: +Then if we grab the User Id from the Unreal Engine logs, click `Open Portal` in Beamable settings, go to `Engage->Players`, find used player and go to `Stats` and search for `NewStatKey` there should be visible that it exists with correct value: ![unreal-beamable-stats-portal](./images/stats-portal.png) + + +## Performance Guidelines + +In this example there is created a new `UpdateCommand` and commited right away. In order to achieve better performance and reduce amount of calls to backend it is encouraged to create `UpdateCommand`, attach as many changes as needed and commit then instead of commiting each change separately. \ No newline at end of file diff --git a/Docs/docs/guides/runtime-concepts.md b/Docs/docs/guides/runtime-concepts.md index 7d7234d5..5312005e 100644 --- a/Docs/docs/guides/runtime-concepts.md +++ b/Docs/docs/guides/runtime-concepts.md @@ -46,6 +46,7 @@ The next image show a high-level description of the authentication flows support ![](./images/runtime-concept-authflow.png#center) Now that you have a high-level understanding of the SDK's initialization flows, read up on how to achieve the two most common Sign Up and Login flows among the ones we provide. + ## Player Sign Up and Login Flows with Beamable The Beamable SDK comes with a set of pre-implemented operations for common sign-up use-cases. Here are how to set up a few of the common login/signup flows using Beamable. @@ -82,6 +83,7 @@ Next, in your `BeginPlay` implementation, register a function to run when the SD Remember that these are part of the initialization flow. As such, try to have a single function bound to these points in order to provide guarantees to the rest of your game code about the state of Beamable. At any point during or after that callback has triggered, make a call to one of the `UBeamRuntime::SignUp____` or `UBeamRuntime::Login____` Operations with the appropriate parameters. We treat these operations as atomic inside the SDK and will clear any invalid partial state in case of any failure during their internal multi-step process; triggering `UBeamRuntime::OnUserReady` only in the case that the user is fully ready for use. + ### Understanding BeamRuntimeSubsystems `BeamRuntimeSubsystem` implementations are stateful subsystems that provide some specific Beamable functionality. They are built on top of our Auto Generated `UBeam____Api` classses to make it simpler to leverage our APIs; that way: @@ -99,6 +101,11 @@ These are hand-written and, currently, are comprised of: These systems make use of the various `UBeamRuntime::____` callbacks to keep their state correct and expose callbacks and configuration options for **Game-Maker Code** to run with semantically relevant guarantees. If the exposed hooks on these are not enough for your use case and constraints, as a user you can create your own `UBeamRuntimeSubsystem`. The SDK tries not to hide things from you so you can use the provided `UBeamRuntimeSubsystems` to understand how they are set up when creating your own. The documentation in [Lower-Level SDK Subsystems][#lower-level-sdk-subsystems] can also be useful when implementing your own `UBeamRuntimeSubsystems`. + +#### C++ version of Blueprint examples + +Most of the docs contains examples only using Blueprints. Unless described otherwise there is option to achieve same results in C++ while folowing Blueprint sample. In order to achieve that replace calls to `BeamStatSubsystem` commands with the same ones with `CPP_` prefix if that version exists and use same ones if version without it does not exists. That means using `CPP_CommitStatsOperation` instead of `CommitStatsOperation`, but `TryCreateUpdateCommand` in both Blueprint and C++ version. + ### Lower-Level SDK Subsystems This section talks about lower-level details of how requests to Beamable get made. ***You don't need to read this***, but... you might want to anyway.