Introduction

CSVs are a common way to define game data in FlatRedBall games. Examples of game data include the cost, damage, and rarity of weapons or stats of enemies like Orc, Dragon, and Elf. Usually this information is used in game logic to determine information like the maximum speed of a car or how much damage an attack deals. Fortunately Glue provides a flexible, powerful way to use CSV data in your game. This article provides an example of loading a CSV into an entity to control its movement speed.

What kind of information can exist in CSVs?

The type of information can be categorized into three groups:

1. Simple coefficients like HP or AttackDamage for enemies in an RPG, or like Horsepower and Weight for cars in a racing game

2. Content information such as which .PNG to use for a enemy, or which .scnx to load for a level

3. Behavioral classes such as ability classes. Usually this feature requires usage of advanced CSV functionality such as lists and inheritance.

Creating a new Project

You will need a Glue project to follow along this tutorial. For information on how to create Glue projects, see this page.

Creating an Entity

In this tutorial we'll use an Entity called Animal. To create the Animal Entity:

1. Right-click on the Entities item in Glue

2. Select Add Entity

3. Enter the name Animal and click OK

Adding a Sprite to the Entity

Next we'll add a Sprite to the Animal Entity so that it can be seen in our game. To do this:

1. Expand the Animal Entity

2. Right-click on Objects

3. Select Add Object

4. Select the Sprite type

5. Enter the name MainSprite and click OK

Making the Sprite visible

The default Sprite will not have a Texture associated with it, therefore it won't be visible. To make the Sprite visible:

1. Select the MainSprite object

2. Set the ColorOperation value to "Color"

3. Set the Red value to 1

4. Set ScaleX to 64

5. Set ScaleY to 64

Creating a Screen with an Animal

Next we'll create a Screen to verify that our Animal is working properly. To do this:

1. Right-click on the Screens item in Glue

2. Select "Add Screen"

3. Enter the name "GameScreen" and click OK

4. Move the mouse over the Animal Entity and push/hold the mouse button

5. Drag the mouse down to the newly-created GameScreen and release the button

6. Click "Yes" when prompted if you want to add an Animal to GameScreen

We will also want to set up our camera to be 2D. To do this:

1. Click on the Settings menu item

2. Select "Camera Settings"

3. Change "Is 2D" to "True"

Now you can run the game and you should see your Animal appear as a red square:

Creating a CSV

At this point we have a basic project up and running: We can see our Animal Entity in our screen, although at this point the Animal Entity is simply a red square that doesn't do anything. Next we'll define a few animal types. To do this:

1. Right-click on the "Global Content Files" item

2. Select "Add File"->"New File"

3. Select the "Spreadsheet (.csv)" file type

4. Enter the name AnimalInfo for the file type

Once the file is created, double-click the file to open it in a spreadsheet editor. Modify the file so it contains the following information:

Save the file to cause Glue to update the AnimalInfo class to match the new data entered in the CSV file.

Making AnimalInfo a Dictionary

Next we'll make the AnimalInfo file create a Dictionary - this will make working with the AnimalInfo easier. To do this:

1. Select the AnimalInfo.csv file in "Global Content Files"

2. Change the "CreatesDictionary" property to "True"

Including the AnimalInfo in the Animal Entity

If you have used Glue before, you may expect the next step to be adding a variable called "Speed" to the Animal Entity which can be assigned from the CSV. Instead of creating a new variable for Speed, we'll instead add a reference to the entire AnimalInfo inside the Animal Entity. To do this:

1. Expand the Animal Entity

2. Right-click on the Variables item

3. Select "Add Variable"

4. Select the "Create a new variable" radio button

5. Select "GlobalContent/AnimalInfo.csv" as the type

6. Enter "AnimalInfo" as the name
7. Click "OK"

This new AnimalInfo variable can now be set in code or in Glue. For simplicity we'll set it in Glue; however, CSV variables like AnimalInfo are usually set in code according to player actions or game data. To set the variable:

1. Select the newly-created AnimalInfo variable

2. Set the DefaultValue to "Bear" using the drop-down

Using AnimalInfo in behavior code

Now we can use the AnimalInfo variable in our Animal's behavior code. To do this, add the following code in the CustomActivity in Animal.cs.

 InputManager.Keyboard.ControlPositionedObject(this, this.AnimalInfo.Speed);

Notice that the AnimalInfo and Speed variables are both supported in Visual Studio's autocomplete. Working with these Glue-created types and variables provides full autocomplete support so you know that you're writing the code correctly. Now try running the game and using the arrow keys on the keyboard to move your Animal entity. Also, try changing between the Bear and the Slug and you'll notice the Slug moves much slower. You can also modify the values in the CSV, then run your program again to notice the changes.

Memory Benefits: Since the types defined in CSVs are reference types (classes), then the Entity simply points to a reference of an AnimalInfo. While this might seem like a small gain (in the case of one Entity, it may not be a gain at all), consider a situation where you have numerous variables defined in a CSV, and you may have dozens or even hundreds of Entities that use these CSV values. In this case the reference characteristics of the CSV types is very beneficial. Furthermore, these references are not destroyed or recreated, so you will save on memory allocation and garbage collection if you are creating and destroying Entity instances.

Loading content according to AnimalInfo

Next we'll look at how to load content dynamically according to information in the AnimalInfo CSV. The approach we're going to show is a very powerful approach because it only loads information as needed. We'll be loading a Texture2D to apply to the Animal Sprite, however this approach can be used for any other data such as AnimationChains, Scenes, and ShapeCollections. Also, keep in mind that this is not limited to Entities - you can also use it on Screens to dynamically load data according to information in a CSV that defines level info. To add the textures to your project:

2. Return to Glue

3. Expand the Animal Entity

4. Right-click on the Files item under Animal

5. Select "Add File"->"Existing File"

6. Select the Bear and click OK

7. Repeat the above 3 steps and add the Slug

9. Select the Slug and also set its "LoadedOnlyWhenReferenced" to "True"

Now we need to write a little bit of code to modify the Sprite according to the AnimalInfo. To do this:

1. Open Animal.cs and delete the contents of CustomInitialize - we won't need this code anymore now that we're going to use textures.

2. Select the AnimalInfo variable under Animal in Glue.

4. Right-click on the "Events" item under Animal in Glue

5. Select "Add Event"

6. Verify "Expose an existing event" is selected

7. Verify "AfterAnimalInfoSet" is selected as the existing event

8. Click OK

9. Expand the Events item and select the "AfterAnimalInfoSet" event

10. Add the following code to the text box which appears on the left:

this.MainSprite.Texture = (Texture2D)GetFile(this.AnimalInfo.Texture);

Next we'll modify the Sprite's variables. To do this:

1. Select the MainSprite object in Glue

2. Right-click on the "ScaleX" variable and select "Reset to Default"

3. Right-click on the "ScaleY" variable and select "Reset to Default"

4. Set the PixelSize varaible to .5

5. Set the ColorOpeartion to "Texture"

Order of Variables Matters!

A very common mistake when working with CSVs is to not properly order your variables. If you followed the tutorial above word-for-word, then your project will not have any variable order issues because there is only one variable - the CSV variable. However in larger Entities variable order problems can emerge. For starters, let's consider the example above where we have a single CSV variable which has a script that sets the Texture on a Sprite. The setup may look like this:

Specifically, we have just a CSV variable, and an event that is raised when the CSV variable (called AnimalInfo) is set. Next we'll tunnel in to the Sprite's Texture. To do this:

1. Right-click on Variables

2. Select the "Tunnel a variable in a contained object"

3. Select "MainSprite" as the Object

4. Select "Texture" as the Variable

5. Set the Texture to "Slug"

6. Set the AnimalInfo to "Bear"

Setting the AnimalInfo after initialization

So far we've shown how to set AnimalInfo in Glue. This is very handy for previewing things in GlueView, or for setting initial values; however it is likely that you will want to set values in custom code according to player actions or scripted events. To do this, you can simply access the AnimalInfo variable. To do this:

1. Create a Screen (you don't need to do this if your game already has a Screen)

2. Add an instance of Animal in your Screen

3. Add the following code in your Screen's CustomInitialize:

this.AnimalInstance.AnimalInfo = GlobalContent.AnimalInfo[AnimalInfo.Bear];

Note: You may need to fully-qualify

AnimalInfo.Bear

. You can do this with CTRL+dot. More info here

You can change this from Bear to Slug and the AnimalInstance will respond appropriately. Of course, you don't have to do this just in CustomInitialize, you can do this at any point, and on any Entity that supports this pattern, whether it is created in Glue, or created purely in code.

Considerations and moving forward

While this example may seem to be simple, the approach we've taken here is incredibly scalable, efficient, and flexible. However, as with all approaches there are some things to consider:

• All Entities that are given the same CSV object reference will share the same exact instance. This means that if you change a value (like the Bear's Speed) it will apply to all bears. Also, the CSVs are not destroyed when Entities or Screens are destroyed if put in Global Content Files, so changes will persist until the program is restarted. This can all cause confusing behavior if you are editing the CSV but not seeing changes that you expect to see. You should never change these values in code unless you have a very good reason to do so.

• If you intend on modifying values, such as allowing each individual instance to have a speed boost according to the Animal's level, you should make a custom property that uses the base value and returns a modified value.

• The texture for the Bear and Slug will not be loaded until either is needed. Since the AnimalInfo is set after content is done loading, it is done on a primary thread. In other words, this means you may notice a slowdown or freeze when loading content if you are loading a lot of content. For simplicity this tutorial only covers how to load the content on the primary thread, but you may want to pre-load content that you know you will need in CustomLoadStaticContent.

• Changes in the CSV will immediately show up in code (as long as Glue is open). This means that if you remove a column from the CSV (such as the Speed column), then that variable will be removed from the matching class. Be careful removing or renaming columns as this may break existing code.

Introduction

CSV (comma separated values) is a spreadsheet file format which has extensive support in FlatRedBall.

What is a CSV?

CSV stands for "comma separated values". If you are familiar with Microsoft Excel, then you may be familiar with the .xlsx or .xls file format. The .csv file format is similar to the .xlsx file format in that they are both spreadsheet file formats. One main difference between the two is that the .csv file format is much easier to read and edit in a text editor. For example, consider the following:

If this were a CSV file viewed in a text editor then it would appear as follows:

Column 1,Column 2,Column 3
Value 1,Value 2,Value 3
Next Row,Next Row 2,Next Row 3

You can see above that the values (such as "Column 1" and "Column 2") are separated by commas. This is where the name "comma separated values" comes from.

CSVs create data files

When you create or modify a CSV which is part of your FlatRedBall project, FRB automatically creates code files (classes) which can be used to store information that is loaded from a CSV in your project. These files/classes are often referred to as "data" files and classes because FRB generates them in the Data namespace of your project. The data file will include a class with the same name as your CSV file. This will include members matching the headers of the columns of your CSV. For example, consider a file EnemyInfo.csv which contains the following:

If this file is added to a Screen, Entity, or Global Content, then FlatRedBall automatically creates a file called EnemyInfo.Generated.cs:

public partial class EnemyInfo
{
   public string Name;
   public float Speed;
   public string Texture;
}

Adding a CSV File

To add a CSV file:

1. Open the FlatRedBall Editor

2. Pick a place for your CSV file in your project. Usually CSV files are added to Global Content Files

3. Right-click on on the location which should contain the new CSV and select Add File -> New File

4. Enter the name for the new file. Although not necessary it's common to end the file name with "Data". For example, EnemyData if the file is to include data about enemies.

Once you have added a new CSV file you can edit it in any editor you prefer, such as Excel, Libre Office, or even a text editor.

Accessing CSV Data in Code

CSV files which are added to the FRB Editor are automatically loaded. If your CSV is added to Global Content Files (as is usually the case), then its contents can be accessed through the GlobalContent object.

For example, consider an EnemyData.csv file added to Global Content Files.

This file can be accessed in code through the GlobalContent object in code as shown in the following code snippet:

void CustomInitialize()
{
    var monsterData = GlobalContent.EnemyData["Monster"];
    var health = monsterData.Health;

    // You can use health or any other property in your game
}

The example above assumes a row for the "Monster" enemy and a column for Health as shown in the following image:

Note that if you add additional rows or columns you can access these in your code. Also note that this code assumes that the CSV is loaded into a dictionary. For more information on List vs Dictionary loading, see the CreatesDictionary property.

Headers and Generated Class Definition

As mentioned above, the FlatRedBall editor automatically generate a code file based on the CSV. Specifically, FRB looks at the top row (headers) of the CSV file to determine the class members. If a header does not specify a type, then it will default to a string type.

The example above has two string members: Name and Texture. Headers can also define the type of a class. For example, the header above Speed (float) results in the EnemyInfo class including a Speed property of type float. FRB supports comments for headers resultingin the exclusion of the property. For example, the following CSV would include a single Name property, and the other column is ignored:

CSVs and Lists

Columns in a CSV may be of a list type (such as List<int>). These types can be specified in parenthesis just like any other type. When a CSV includes a list, the required row defines how many entries are in the CSV. For example, the following CSV contains two car definitions, and each car has multiple features.

The generated file is partial

The generated code file for the data class is marked as "partial". This means that you can add additional code files to add additional variables and functionality to data that is created by FRB. To do this:

1. Find the data file in Visual Studio

2. Right-click on the folder containing the Data file

3. Select "Add"->"Class..."

4. Enter the name of your CSV file without the extension. For example, if using EnemyInfo.csv, the new Class name would be EnemyInfo (so it matches the class name in the generated file)

5. Once the file is selected, find the header of the file and make it partial. In other words, change:

class EnemyInfo

to

partial class EnemyInfo

Now you can things to EnemyInfo to help you work with the generated class. Note that this approach of using partial classes is the same as what FRB automatically does for you when you create a Screen or Entity. Custom code is very common in Screens and Entities, so FRB automatically creates a custom code file for you. Custom code in data classes is less common so FRB does not automatically do this for you; however if you do it manually it works the same way.

Introduction

Each row in a CSV can be a basic type or an instance of a full class/struct. This tutorial shows how to add structs and classes to your CSV file.

Why use non-primitive types?

Many games require data types which are more complex than can be identified with simple primitives. For example, you may be creating a game which needs enemy types defined. Each row in your CSV may represent an enemy type; however each instance may also need a non-primitive type to define the type of attack damage it does. If these classes were laid out in code, they might look like this:

// EnemyInfo does not need to be manually defined if you're using Glue
public class EnemyInfo
{
   public string Name;
   public int HP;
   public AttackInfo AttackInfo;
}
// AttackInfo *does* need to be manually defined if you're using Glue.  See below for more info on this
public class AttackInfo
{
   public int Damage;
   public float AreaOfEffect;
}

As we'll see later in the tutorial, using classes and structs also allows for your CSV to benefit from inheritance.

Creating the CSV

First we start by creating the CSV that contains our information, then we'll explain the syntax. The following is a screenshot from Excel, but you can use any spreadsheet editing program (such as LibreOffice):

A few things are worth mentioning:

1. The Name property is marked as "required". This is common practice so that the CSV can be deserialized to a Dictionary.

2. The type for AttackInfo must be fully-qualified - in other words we use "MyGame.DataTypes.AttackInfo", not just "AttackInfo".

3. Each parameter can be assigned to any value valid for the type. Note that order does not matter (AreaOfEffect could be assigned before Damage), and it is not necessary to assign variables. For example, you could simply have "Damage=4" and AreaOfEffect would remain as its default value.

Types used by the CSV must be defined manually. FlatRedBall automatically defines the type that the entire CSV is using - in this case "EnemyInfo", however types used inside the CSV (such as AttackInfo) must be manually defined inside your current project.

Creating Classes for Inheritance

Objects in CSVs also support inheritance. Inheritance allows you to define a base type for a property on your objects, but then specifying derived types in each individual row. First, we modify our data classes as follows:

// No changes on EnemyInfo - just adding for reference
public class EnemyInfo
{
   public string Name;
   public int HP;
   public AttackInfo AttackInfo;
}

public class AttackInfo
{
   public int Damage;
   public float AreaOfEffect;
   public virtual void ApplyDamage()
   {
      // This should get overriden by specific types
   }
}
// Let's create a SlashingAttackInfo derived class:
public class SlashingAttackInfo : AttackInfo
{
   public float CriticalHitChance;
   public override void ApplyDamage()
   {
       //Do logic specific to SlashingAttackInfo here
   }
}
// Let's create one more class: a FireAttackInfo
public class FireAttackInfo : AttackInfo
{
    public float ExtraBurnDamage;
    public override void ApplyDamage()
    {
        // Do logic specific to FireAttackInfo here
    }
}

Defining a CSV that supports inheritance

Using the code above, we now have FireAttackInfo and SlashingAttackInfo, both of which inherit from AttackInfo. We can now instantiate any of those three types in our AttackInfo column. The following shows a CSV that instantiates different types:

When using inheritance we must specify the type that we want to use in each column. The syntax for this is the same as it is when instantiating an object in code - use the keyword "new" followed by the type. The contents of the parenthesis are the same as as before. You can assign values defined in the derived class as well as the base class. You can also leave out assignments that you want to keep as the default. For example the EndBoss enemy does not define the AreaOfEffect - it defaults to 0.

Using Existing Types

The CsvFileManager doesn't differentiate between types that you have defined and types that are defined by other libraries (such as types in the XNA libraries). This means that you can immediately add a lot of types of objects to your CSV without ever having to define them in your project. For example, the following shows how to define a column of XNA Rectangles:

Introduction

CSVs are often used to define data for games, but it's common for one CSV to need to reference information from another CSV. This tutorial will walks you through creating two CSVs, with one referencing the other.

Overview

We will be creating two CSVs:

1. The first defines the weapons in your game. The weapons defined for this game are for a traditional RPG.

2. The second will define the shops in the game which will contain a list of the weapons which they can sell.

Creating the CSVs

First we'll create a CSV for weapons called WeaponInfo:

1. Right-click on Globa lContent Files

2. Select "Add File"->"New File"

3. Select "Spreadsheet (.csv)" as the type

4. Enter the name "WeaponInfo" as the new file's name

5. Click OK

Next create the CSV for StoreInfo:

1. Right-click on Global Content Files

2. Select "Add File"->"New File"

3. Select "Spreadsheet (.csv)" as the type

4. Enter the name "StoreInfo" as the new file's name

5. Click OK

You should now have 2 CSVs in your Global Content Files uner Global Content Files:

Filling WeaponInfo CSV

Fill the WeaponInfo file so it appears as follows:

Filling StoreInfo CSV

Fill the StoreInfo so it appears as follows:

Note that the StoreInfo CSV file uses a List<string> instead of a List<WeaponInfo> for the WeaponTypes it contains. Specifically the StoreInfo references the Name of the WeaponInfo, similar to a key in a database.

Adding a StoreInfo partial class

Next we'll need to write some simple code to associate the values in the WeaponTypes column in the StoreInfo CSV to the weapons defined in WeaponInfo.csv. To do this:

• Open your project in Visual Studio

• Expand the "DataTypes" folder in the Solution Explorer

• Right-click on the "DataTypes" folder and select "Add"->"Class..."

• Name the class "StoreInfo". This should be the same name as your CSV.

You should now have a file called StoreInfo.cs and a file called StoreInfo.Generated.cs

Next, open the newly-created StoreInfo.cs file and make it a "public partial" class. After you do this, your code should look like:

public partial class StoreInfo
{
}

Finally save your project through the "File"->"Save All" option in Visual Studio. This saves changes to the project so that if the FRB Editor is open it will reload the changes.

Adding the "Weapons" property to StoreInfo

Next we'll add a property to the StoreInfo.cs file to make it more convenient to access which WeaponInfo's a Store contains. To do this, add the following code to StoreInfo.cs:

public IEnumerable<WeaponInfo> Weapons
{
    get
    {
        foreach (var weaponType in this.WeaponTypes)
        {
            yield return GlobalContent.WeaponInfo[weaponType];
        }
    }
}

Now each ScreenInfo which is loaded into GlobalContent has an IEnumerable of WeaponInfo's that can be used to populate UI, menus, and drive game logic.

Introduction

UniformRowType can be used to load the CSV data in a more raw format rather than generating a custom class for the CSV. This is useful if the data in the CSV needs to be accessed by row and column index rather than by class member names. For this guide we'll be using a CSV with the following data:

Default Functionality

Before changing the UniformRowType value, we should look at the code generated by Glue for this CSV. The class that contains the CSV will have a dictionary of objects as shown in the following code:

public static System.Collections.Generic.Dictionary<string, RedgrinTest3.DataTypes.Csv> CsvFile { get; set; }

In this case the Csv class is generated as shown in the following snippet:

public partial class Csv
{
    public string Column1;
    public string Column2;
    public string Column3;
    ...

In this case we could access the CSV data through the CsvFile member. If the CSV were part of GlobalContent we could get the information as shown in the following code:

var value = GlobalContent.CsvFile["Value 1"].Column1;

Note that we access the first column using the Column1 property.

Setting UniformRowType

We can change the UniformRowType to string[] to change how Glue generates the CSV code.

This setting tells Glue to generate each row in the CSV as a string[], allowing us to index into each column as shown in the following code:

var value = GlobalContent.CsvFile["Value 1"][0];

String vs. String[]

Glue offers two options for UniformRowType:

1. String

2. String[]

The most commonly used value is String[] which tells glue that each row contains multiple values. Since each value in a row may need to be independently accessed, each row is represented as a string array. For example, to access index 3 in a row, your code may look like:

var row = LoadedCsv[2]; // row at index 2
var value = row[3]; // value at index 3 in the selected row

If your CSV has only one column, then the UniformRowType can be String. This can simplify accessing the row. For example, to access the first item in the row at index 2, your code may look like:

var value = LoadedCsv[2]; // this is a string

Introduction

By default CSVs added to Glue will create a matching class in the DataTypes folder of the game project. For example, adding a file EnemyInfo.csv will create a class GameName.DataTypes.EnemyInfo. While this behavior is convenient it is sometimes too restrictive. For example, games may benefit from fully-defining their data classes by hand - even in other projects completely - rather than letting Glue generate the data classes automatically. Setting Generate Data Class to false allows the code project to specify its own data class.

Example

The following screen shot shows a CSV called EnemyInfo which is tied to a data class with the fully-qualified name of GameProject.DataTypes.EnemyDataClass:

The "Custom Namespace" field allows using classes defined outside of the GameName.DataTypes namespace. For example in the following image the class BuildingInfo is placed in the BaseDataTypes.Buildings namespace (resulting in the fully qualified name BaseDataTypes.Buildings.BuildingInfo):

Introduction

The OrderedList property is a List of values which correspond to the order of values in a dictionary CSV. A given CSV must have its property set to true for OrderedList to be generated.

OrderedList is not dynamicThe OrderedList is a hardcoded list. It is not dynamic, meaning if you make any modifications to a CSV at runtime, the OrderedList property will not update according to these changes.

Code Example

The OrderedList property can provide access to entries in a dictionary CSV when order is important. The reason this is necessary is because values in a Dictionary at runtime are not guaranteed to be in the same order as the values in a CSV. For more information, .

// The following code moves the calling object to the next level
public void SetNextLevel()
{
   // Assumes the object has a CurrentLevel type which is of type LevelInfo
   // (presumably from a CSV called LevelInfo.cs)
   // This also assumes that "Name" is the key used in the dictionary
   // OrderedList is a static property:
   int indexOfCurrent = LevelInfo.OrderedList.IndexOf(CurrentLevel.Name);

   if(index < LevelInfo.OrderedList.Count)
   {
      string nextLevelKey = LevelInfo.OrderedList[indexOfCurrent + 1];
      
      CurrentLevel = GlobalContent.LevelInfo[nextLevelKey];
   }
   else
   {
      // Last level, handle appropriately
   }
}

Introduction

CreatesDictionary is a property that controls whether to deserialize a given CSV file to either a List or Dictionary. If true, the CSV file is deserialized to a Dictionary. Otherwise, it is Deserialized to a List.

If you are accessing entries within a CSV according to some common key (such as the Name of an enemy type), then you should use the CreatesDictionary property to simplify access in code.

CreatesDictionary can be set on a CSV file in its properties tab or when first adding a new CSV. The following shows the option for specifying Dictionary or List when creating a new CSV:

"required" keyword

Dictionaries in code require a key. This is typically the Name property which is marked with the required keyword. For example, the following CSV marks the "Name" as required:

Name is common The most common key for data is "Name". Unless you have a reason to not use this, consider using "Name" as your required property.

If you have a CSV without a "required" field, then FRB cannot create a Dictionary out of the CSV. Just like any other CSV, once you have saved this file, the generated class will be added/updated.

Accessing the Dictionary in code

Now that you have created a CSV that has CreatesDictionary set to true, you can access the file in code and get instances using the Name property:

Concerns about using strings as keys

You may be wondering if it is a good idea to access objects using strings as the key. For example, let's consider the following line:

int damage = GlobalContent.TestCsv["Imp"].Damage;

As you may have realized, this can be an unsafe line of code. What if, for example, the CSV changes so that it no longer contains the "Imp" object? Then that code would compile, and the error would only be discovered if that particular piece of code was executed. In other words, there is a risk of having hidden bugs associated to this line of code. First, we should mention that the reason the code above uses the hardcoded "Imp" value is to show the connection between code and the CSV. In final game code this is not good practice. Fortunately this type of code is usually not necessary. Let's look at the two most common situations where values are retrieved:

Values in Lists

It is common to use values form CSVs in Lists. For example, let's say that the TestCsv used above is being used in a screen where the user picks which enemies to take into battle. Your code may look something like this:

foreach(var value in GlobalContent.TestCsv.Values)
{
   CreateButtonFor(value);
}

This would dynamically loop through the list and create UI elements for each item in the CSV. If an item is added or removed, your code would automatically adjust to this and only show which values are appropriately.

Accessing values directly

In some cases you may need to access values directly. This can happen if:

• You need to set a default value for something in code

• You need to create a script in code, such as defining which enemies appear in a particular level

Fortunately the generated code creates const string values to allow you to access values in a compile-time-protected way. For example, the code above to access the imp could be more-safely done as follows:

int damage = GlobalContent.TestCsv[TestCsv.Imp].Damage;

The TestCsv class has one constant for each entry in the CSV, so the code above will work without any other code.

OrderedList

If a CSV is loaded as a dictionary, then FlatRedBall generates an OrderedList property. this property can be useful if you would like to have your data loaded in to a Dictionary while also providing its order. One example of this usage might be to include a list of data for each level in your game. This CSV could be used to populate a level selection ListBox which should show the levels in a particular order. Keep in mind that the Dictionary collection does not guarantee preservation of order, so if you intend to show your data in the same order as the CSV, be sure to use the OrderedList property.

Note that OrderedList is only generated if CreatesDictionary is set to true.

Introduction

By default Glue creates a new class in the DataTypes namespace for every CSV in your project. For example, consider a game where each enemy can have multiple types of attacks. Each enemy might store the attack information in its own CSV file. In this example the CSV files would be called:

1. SoldierAttackData.csv

2. OgreAttackData.csv

3. SlimeAttackData.csv

4. ZombieAttackData.csv

We will assume that each CSV file has the same columns, and we would like to have the same code handle enemy attacks regardless of which type of enemy is performing the attack. However, by default Glue will create four classes - one for each CSV. To solve this problem, we can create a common class to be used by all CSV files. This can be done by right-clicking on each of the CSV files and selecting the Set Created Class option.

Example - Enemy AttackData

This example uses enemy entities which each provide their own attack data in CSV files. Each CSV has its Created Class set to Enemy Data.

A new class can be added in the Created Class window.

Once added, classes appear in the list below.

This class can be used for the current CSV by selecting the class and clicking the Use This Class button.

Once a class is added, Glue generates a file for this in the DataTypes folder.

The four CSVs specified above will deserialize into AttackData Dictionaries or Lists.

Platformer Values

Glue automatically creates a class called PlatformerValues if a game includes platformer entities. Every entity will store its platformer values in instances of the common PlatformerValues class. Removing this class can cause compile errors.

Additional Information