Getting Started

Getting started with BP

Create Shard

• Construct a key
  • Keys can either be saved or reconstructed.
  • By default, the owner is 'self' — in this case, the player Pawn.
• Call the 'Create Shard' node
• Connect the initial data for the shard.
  • You can also connect a literal value.
  • You must connect something so the data type for the shard can be determined.

Now you have created a key pointing to the new shard. This key now points to a float shard where the value from 'Player Init Health' is entered.

Note

Keep in mind that the variable 'Player Init Health' is not connected to the shard. If the shard changes, 'Player Init Health' is not affected — and vice versa.

Get Shard Data

• Construct a key or use one saved in a variable.
  • In this case, we use the static 'Get Player Pawn' node to retrieve our Pawn.
  • We use the same key name as the one created in the previous step.
• Call the 'Get Shard Data' node.
• Connect the 'Out Data' pin to where it is needed.
  • Keep in mind that the pin’s data type must exactly match the shard’s data type.

Note

You can reconstruct keys. For this, the 'Owner' and the 'Name' must be exactly the same as the ones used when creating the shard.

Warning

In this example, we use the 'Get Player Pawn' node. In other situations, you must ensure that you retrieve the correct Actor as the Owner.

Set Shard Data

In this example, we retrieve the data before setting it. For this, we use the previously saved 'Player Health Key' variable, where the key was stored.

After calculating the correct value, we call 'Set Shard Data' and assign the new value to the 'In Data' input.

Warning

With 'Set Shard Data', it is also possible to change the data type inside the shard. However, I highly recommend not doing this to avoid confusion.

Binding

Binding is one of the core features of this plugin. We get a new key, which provides access to an existing shard. To do this, we need:

• A key (either as a variable or newly constructed) that has access to an existing shard.
• The new Owner
• A new Name

With the 'Create Bound Key' node, we create a new key that has access to the same shard as the 'parent'.

Now we can access the same shard data with both keys at any time, without needing additional data forwarding.

Advanced

You can add events that will be executed when specific shard data changes.

In this example, we modify the 'Create Shard' part by adding the 'Bind Event on Shard Data Change' node. We use the same key that was used to create the shard. Now, every time the shard data changes, the 'On Shard Data Changed' event will be triggered, which will then call the 'Update Player UI Health' function.

---

Getting started with C++

Most of the functions we need are located inside the DataShardSubsystem

Create Shard

.h
UPROPERTY(EditAnywhere, BlueprintReadWrite)
float FloatValue = 875.4f;
 
.cpp
const FDataShardKey Key = {this, "Test Float Key"};
UDataShardSubsystem* Sub = GetGameInstance()->GetSubsystem<UDataShardSubsystem>();
Sub->CreateShard(Key, this, GET_MEMBER_NAME_CHECKED(ThisClass, FloatValue));

The DataShardSubsystem::CreateShard function has two overloads. The version that includes a Container and PropertyName is more user-friendly.

Note

Instead of creating the variable Key, you can directly use the uniform initialization {Owner, "Name"} in the function.

Get Shard Data with DataShardSubsystem

.cpp
const FDataShardKey Key = {this, "Test Float Key"};
const float* Value = Sub->GetShardData<float>(Key);

Get Shard Data with Key

.cpp
const float* Value = Key.GetValue<float>(Sub);

Get Shard Data with helper macros

.cpp
const float* Value = RETURN_SHARD_DATA(float, Key)

or

.cpp
GET_SHARD_DATA(float, Value, Key);

RETURN macros return you a pointer.

GET macros create for you the pointer variable

There are also other macros that may be useful. Take a look at Helper Macros.

Note

The raw pointers you get with these functions are not copies. These raw pointers point to the current value inside the shard. If the value inside the shard changes, the pointer will automatically point to the updated value. Keep in mind that this behavior is different from the COPY macros.

Set Shard Data with DataShardSubsystem

.h
UPROPERTY(EditAnywhere, BlueprintReadWrite)
float FloatValue = 875.4f;
 
.cpp
Sub->SetShardData(Key, this, GET_MEMBER_NAME_CHECKED(ThisClass, FloatValue));

Set Shard Data with Key

.h
UPROPERTY(EditAnywhere, BlueprintReadWrite)
float FloatValue = 875.4f;
 
.cpp
Key.SetValue(Sub, this, GET_MEMBER_NAME_CHECKED(ThisClass, FloatValue));

More information

Currently, there is no way around using members to create and set the shard data. We use the Unreal Reflection System (FProperty), which are created by the UHT (Unreal Header Tool) at compile time. For more complex or nested data types, such as structs that contain other structs, it is too complex to build them at runtime.

---

Global Keys and Global Shards

You can create global keys, which means there is no owner. They work the same way as normal keys, but you can use them anywhere, and they are not bound to a specific owner.

const FDataShardKey GlobalKey = {"Global Float Key"};

Set Self Data

To set self in a shard you need to cast the self node or create a variable. Otherwise you will get an error.

---

Debugging

Commands and functions

Command	Function	Description
DumpAllShards	DataShardSubsystem::GetShardDump	Use this command to get all shards displayed in the output log
DumpAllKeys	DataShardSubsystem::GetKeyDump	Use this command to get all keys displayed in the output log
DumpAllReferences	DataShardSubsystem::GetRefDump	Use this command to get all references displayed in the output log
DumpAllShardsString	DataShardSubsystem::GetShardStringDump	Use this command to get all shards displayed in the output log
DumpShardPoolSize	DataShardSubsystem::GetPoolSize	Use this command to get shard pool size displayed in the output log
DumpShardPoolActiveAmount	DataShardSubsystem::GetActiveShardCount	Use this command to get shard pool active amount displayed in the output log
DumpShardPoolAvailableAmount	DataShardSubsystem::GetAvailableShardCount	Use this command to get shard pool available amount displayed in the output log

Visual Logger

You can use the built-in Unreal Engine Visual Logger. I recommend taking a look at the Unreal Engine Documentation

Data Shard Debugger

Under Tools → Debug → DataShard Debug, you can find the Data Shard Debugger. This tool allows you to view all keys, shards, and the data inside the shards.

You can double-click on the owner nodes (on the left side) to jump to the actor.
When selecting a shard node, you can see the data inside in the Details panel.
With the 'Pause' button at the top left, you can pause changes. This will freeze the debugger, allowing you to inspect everything for as long as you need.
You can filter by Actors (Key Owners). You can select one or multiple actors. When selecting one or more actors, only the affected shards, keys, and actors will be shown.
By default, the debugger doesn't clear when you end the PIE session. You can enable this by checking the 'Clear on PIE End' checkbox in the top right.
You can move the nodes as you like. If you want to reset their location, you can click the 'Refresh' button.