Data Driven Gameplay Elements

Data Driven Gameplay helps mitigate the amount of work and complexity involved for games that have an extended lifetime. For example, some games may offer updates to users through an online service model. This model may adjust certain data parameters within that game to balance or add content based on user feedback.

Data Driven gameplay provides you with an interface to visualize and parameterize data creation and progression. You can move data to Microsoft Excel or other spreadsheet document that can be maintained and then imported to automatically take effect in the game.

DataTables and CurveTables can be imported into Unreal Engine through Excel documents. These Excel documents are .xlsm (macro enabled Excel documents) that have macro based export buttons to enable easily exporting to the intermediate data format, comma separated variables (.csv).

These documents eside in a single location to help make data easier to find and modify. You can download a sample .xlsm file by Right-clicking > Save as to download:

• https://d1iv7db44yhgxn.cloudfront.net/documentation/attachments/7ee40227-210d-4481-8420-508daaac5df5/example.xlsm

Data Tables

Data Tables are a table of miscellaneous but related data grouped in a meaningful and useful way, where the data fields can be any valid UObject property, including asset references. Before a designer can import a CSV file into a DataTable, a programmer has to create the row container telling the engine how to interpret the data.

These tables consist of column names that have a 1:1 mapping to a given code based UStruct and its variables, which must inherit from FTableRowBase to be recognized by the importer.

The first column is expected to be named Name and contains the names by which each row is accessed for use in game. Subsequent columns have a variable name for a heading and below, in the same column, the data for that row/column intersection. Given this format, a single row maps 1:1 directly to the structure inherited from FTableRowBase.

We created the following CSV document to showcase a Gameplay Data example where a character may gain experience points in order to attain a "level up":

	
		/** Structure that defines a level up table entry */
		USTRUCT(BlueprintType)
		struct FLevelUpData : public FTableRowBase
		{
			GENERATED_USTRUCT_BODY()
	
		public:
	
			FLevelUpData()
			: XPtoLvl(0)
			, AdditionalHP(0)
			{}
	
			/** The 'Name' column is the same as the XP Level */
	
			/** XP to get to the given level from the previous level */
			UPROPERTY(EditAnywhere, BlueprintReadWrite, Category=LevelUp)
			int32 XPtoLvl;
	
			/** Extra HitPoints gained at this level */
			UPROPERTY(EditAnywhere, BlueprintReadWrite, Category=LevelUp)
			int32 AdditionalHP;
	
			/** Icon to use for Achivement */
			UPROPERTY(EditAnywhere, BlueprintReadWrite, Category=LevelUp)
			TSoftObjectPtr<UTexture> AchievementIcon;
		};
	
Copy full snippet

/** Structure that defines a level up table entry */ USTRUCT(BlueprintType) struct FLevelUpData : public FTableRowBase { GENERATED_USTRUCT_BODY() public: FLevelUpData() : XPtoLvl(0) , AdditionalHP(0) {} /** The 'Name' column is the same as the XP Level */ /** XP to get to the given level from the previous level */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category=LevelUp) int32 XPtoLvl; /** Extra HitPoints gained at this level */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category=LevelUp) int32 AdditionalHP; /** Icon to use for Achivement */ UPROPERTY(EditAnywhere, BlueprintReadWrite, Category=LevelUp) TSoftObjectPtr<UTexture> AchievementIcon; };

CSV Document:

		Name,XPtoLvl,AdditionalHP,AchievementIcon
		1,0,0,"Texture2d'/Game/Textures/AchievementIcon1'"
		2,1000,9,"Texture2d'/Game/Textures/AchievementIcon2'"
		3,1000,10,"Texture2D'/Game/Textures/AchievementIcon3'"
		4,1500,12,"Texture2D'/Game/Textures/AchievementIcon4'"
		5,2000,14,"Texture2D'/Game/Textures/AchievementIcon5'"
Copy full snippet

Name,XPtoLvl,AdditionalHP,AchievementIcon 1,0,0,"Texture2d'/Game/Textures/AchievementIcon1'" 2,1000,9,"Texture2d'/Game/Textures/AchievementIcon2'" 3,1000,10,"Texture2D'/Game/Textures/AchievementIcon3'" 4,1500,12,"Texture2D'/Game/Textures/AchievementIcon4'" 5,2000,14,"Texture2D'/Game/Textures/AchievementIcon5'"

The double quotes around the asset type are important for the property importing pipeline. Without them, the text is imported as Texture2d.

Data Table Importing Process

Follow the steps below to Import a CSV file:

1. Save your file out of Excel or another spreadsheet software with the .csv extension.

2. Open Unreal Editor, and click on Import in the Content Browser.

3. Navigate and select the CSV file you want to import as a DataTable. You can choose from the following Import As options:

   • DataTable
   • CurveTable
   • Float Curve
   • Vector Curve
   • Linear Color Curve
   

4. You can choose the DataTable Row Type from the drop down list.

   

5. Additional Import Options are available to use:

   

   Import Option	Description
   Ignore Extra fields	Set to true to ignore extra fiels in the import data, if false it will warn about them
   Ignore Missing Fields	Set to true to ignore any fields that are expected but missing, if false it will warn about them
   Import Key Field	Explicit field in import data to use as key. If this is empty it uses Name for .JSON and the field field found for .CSV

6. This creates a DataTable object in the current directory of the Content Browser.

   

7. You can view the contents of the DataTable in the editor by Double-clicking on the object. You can update the object by Right-clicking on the object and selecting Reimport from the menu.

The original file path is used when reimporting the object.

Data Curves

Data Curves work in a similar manner to DataTables, however they only support floating point types. As with DataTables, the first column is named "Name" and contains the names by which each row is accessed for use in game.

Each column heading after the first stores the X-axis variable for a curve to be plotted. The data under this heading is the Y-axis value for the given row. Given this format, a single row corresponds to a curve that code can access and interpolate data along.

Below is an example table for damage progression:

Curve Tables

Curve Tables are useful for defining two dimensional numeric data. You can edit Simple Curves and Rich Curves in the Curve Data Table Editor.

When creating a Curve Table, you can open the editor to edit curves in the table or curve view without needing to go back to the external program you created them with.

You can create Curve Tables in the Content Browser by navigating to the Miscellaneous section.

Curve Table Importing Process

Follow the steps below to Import a CSV file:

1. Save your file out of Excel or another spreadsheet software with the .csv extension.
2. Open Unreal Editor, and click on Import in the Content Browser.

3. Navigate and select the CSV file you want to import as a Curve Table. You can choose from the following Import As options:

   • DataTable
   • CurveTable
   • Float Curve
   • Vector Curve
   • Linear Color Curve
   
4. Choose the Curve Table Type from the drop down list. Once selected, you will be prompted to choose your interpolation type between Constant, Linear, or Cubic.

1. This creates a Curve Table object in the current directory of the Content Browser.

   

2. You can double-click your Curve Table to open the Curve Table editor.

   

3. To see your Curve Table data in graph form, click the graph button.

   

4. The Curve Table View allows multiple curves to be displayed.

   

5. You can Rename and Delete curves by right-clicking on a curve.

Data Hookup

To use data from these tables is you must do place a Blueprint-exposed variable of either FDataTableRowHandle or FCurveTableRowHandle, depending on if you want a DataTable or CurveTable.

From a content provider's point of view, this will expose a data field with two subfields:

Data Usage (C++)

Once you have the data hooked up, the handle structures provide the helper functions FindRow() and GetCurve() that provide you a way to retrieve either a struct or curve filled with data.

In the case of a FCurveTableRowHandle, an FRichCurve pointer is returned. The FDataTableRowHandle, however, allows you to specify a structure in the template function call. This structure can be the final structure or any of its parents in the inheritance hierarchy.

All structures and curves returned should not be cached further than the local scope of a function. This is to ensure that if the table is refreshed from re-import, the data changes take effect immediately and that no invalid pointers are accessed.

In the above DataTable example, the asset that is referenced is a lazy loaded asset (TSoftObjectPtr handles this). If the Asset field type was set to UTexture, all of the assets would be loaded whenever the DataTable was loaded.