Data-binding

The data binding feature allows you to modify the UI based on the current state of the game. To better understand how the data binding works, please refer to the corresponding content creation docs. This document only describes how to use it in Unreal Engine.

Overview of the process

Let’s say that you want to display the player’s health somewhere in the UI. On the game side, this feature requires you to do 3 things.

Step 1 - Create a model

You need to tell Prysm what game objects you’d like to expose. Any such exposed object we call a data model.

  • Blueprint Editor

    • Call the UCohtmlBaseComponent::CreateDataModelFromStruct / UCohtmlBaseComponent::CreateDataModelFromObject depending on whether you want to expose a UObject instance, or a USTRUCT.
  • C++

    • The same can be achieved with cohtml::View::CreateModel:
    ACharacter* Player = GetPlayerCharacter();
    CohtmlComponent->GetView()->CreateModel("player", Player);

Get(a copy) vs Get(a ref) when using Blueprint struct objects

If you use a Get(a copy) node when iterating a collection of Blueprint struct objects and attempt to create a data model for them, Prysm will prevent you from doing that by ignoring the CreateModel call, because internally Unreal Engine copies each object data over to the same memory address “buffer”, which would cause incorrect data-binding behavior.

Step 2 - Update the model

Next, when something in your model has changed in the game, you need to tell Prysm that it needs to be updated in the UI.

  • Blueprint Editor
    • Use UCohtmlBaseComponent::UpdateWholeDataModelFromStruct / UCohtmlBaseComponent::UpdateWholeDataModelFromObject.
  • C++
    • Use cohtml::View::UpdateWholeModel:
    ACharacter* Player = GetPlayerCharacter();
    CohtmlComponent->GetView()->UpdateWholeModel(Player);

Step 3 - Tell the UI you are ready for the frame

Calling the update methods from the previous step does not actually update the UI - these methods only mark certain pieces of it as dirty (the models). To avoid constant UI updates, this is done in another method that walks through all elements (models) that need updates and syncs them with the game - SynchronizeModels.

  • Blueprint Editor
    • Use UCohtmlBaseComponent::SynchronizeModels.
  • C++
    • Use CohtmlComponent->GetView()->SynchronizeModels(); which internally calls cohtml::View::SynchronizeModels.

A complete Blueprint script may look like this: