Combining .csvs With Entities
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:
Simple coefficients like HP or AttackDamage for enemies in an RPG, or like Horsepower and Weight for cars in a racing game
Content information such as which .PNG to use for a enemy, or which .scnx to load for a level
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:
Right-click on the Entities item in Glue
Select Add Entity
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:
Expand the Animal Entity
Right-click on Objects
Select Add Object
Select the Sprite type
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:
Select the MainSprite object
Set the ColorOperation value to "Color"
Set the Red value to 1
Set ScaleX to 64
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:
Right-click on the Screens item in Glue
Select "Add Screen"
Enter the name "GameScreen" and click OK
Move the mouse over the Animal Entity and push/hold the mouse button
Drag the mouse down to the newly-created GameScreen and release the button
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:
Click on the Settings menu item
Select "Camera Settings"
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:
Right-click on the "Global Content Files" item
Select "Add File"->"New File"
Select the "Spreadsheet (.csv)" file type
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:
Name (required) | Speed (float) | Texture |
Bear | 60 | Bear |
Slug | 20 | Slug |
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:
Select the AnimalInfo.csv file in "Global Content Files"
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:
Expand the Animal Entity
Right-click on the Variables item
Select "Add Variable"
Select the "Create a new variable" radio button
Select "GlobalContent/AnimalInfo.csv" as the type
Enter "AnimalInfo" as the name
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:
Select the newly-created AnimalInfo variable
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.
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:
Return to Glue
Expand the Animal Entity
Right-click on the Files item under Animal
Select "Add File"->"Existing File"
Select the Bear and click OK
Repeat the above 3 steps and add the Slug
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:
Open Animal.cs and delete the contents of CustomInitialize - we won't need this code anymore now that we're going to use textures.
Select the AnimalInfo variable under Animal in Glue.
Right-click on the "Events" item under Animal in Glue
Select "Add Event"
Verify "Expose an existing event" is selected
Verify "AfterAnimalInfoSet" is selected as the existing event
Click OK
Expand the Events item and select the "AfterAnimalInfoSet" event
Add the following code to the text box which appears on the left:
Next we'll modify the Sprite's variables. To do this:
Select the MainSprite object in Glue
Right-click on the "ScaleX" variable and select "Reset to Default"
Right-click on the "ScaleY" variable and select "Reset to Default"
Set the PixelSize varaible to .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:
Right-click on Variables
Select the "Tunnel a variable in a contained object"
Select "MainSprite" as the Object
Select "Texture" as the Variable
Set the Texture to "Slug"
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:
Create a Screen (you don't need to do this if your game already has a Screen)
Add an instance of Animal in your Screen
Add the following code in your Screen's CustomInitialize:
Note: You may need to fully-qualify
. 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.
Last updated
