ShapeCollections can be created through files. To add a ShapeCollection to a Screen or Entity:

1. Create a Screen or Entity which will contain the ShapeCollection file

2. Right-click on the Files item

3. Select "Add File"->"New file"

4. Select "Shape Collection (.shcx)" as the file type

5. Click OK

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

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:

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:

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

The AnimationChainList type is the runtime type for the .achx file type. AnimationChainLists are used to store a collection of animations. Examples of AnimationChainLists might be all of the animations for a Player in a platformer game, such as:

• WalkLeft

• WalkRight

• IdleLeft

• IdleRight

• JumpLeft

• JumpRight

• AttackLeft

• AttackRight

The easiest way to add an AnimationChainList to your game is to add a new .achx file to a Screen, Entity, or global content:

For information on how to add a Sprite to your Entity, see this page. For information about how to use the AnimationEditor, see the AnimationEditor documentation.

Viewing an AnimationChainList in game

AnimationChainLists are ultimately lists of textures and texture coordinates. They must be used on an object to be seen in game. Therefore, if you are creating an Entity or Screen which includes an AnimationChainList file, you will likely also need to add a Sprite to view the AnimationChainList.

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

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

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:

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:

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

CreatesDictionary is a property that controls whether to deserialize a given CSV file to either a List or Dictionary. 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.

Setting CreatesDictionary" in the Properties Tab

CreatesDictionary can also be set to true in the Properties tab of a CSV file:

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:

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:

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:

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

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, .

Introduction

The .fbx file format can be loaded into a MonoGame Model class which can be drawn to the screen. The FlatRedBall Camera provides matrices which simplify the drawing of a Model object. Since the Model object is a native MonoGame object, it must be draw either your Game1's Draw method or in an IDrawableBatch.

Example: Loading and Drawing an .fbx file

Models can be loaded just like any other FlatRedBall file. For example, .fbx files can be dropped into Global Content Files.

Once the file has been added to global content, it can be drawn in Game1.cs as shown in the following code:

Shader Effect Files (.fx) can be added to FlatRedBall projects. At runtime this produces an Effect object which can be used to perform custom rendering. FlatRedBall FNA projects require extra steps to use FX files as explained below.

Creating a Post Processing Effect File

FlatRedBall can import existing .fx files, but also provides a standard way to create effect files for post processing. The easeist way to add a post processing effect file to your project is to use the Add File dialog:

1. Right-click on the Files folder where you would like to add your .fx file (such as Global Content Files or GameScreen) and select Add File -> New File

2. Select Effect (.fx) as the file type

3. Check the Post Processing Shader option

4. Verify that the Include YourFileName.cs Post Process File option is checked

5. Select the type of shader you would like to use. For example, Saturation.

6. Enter a name for your new effect file, such as SaturationEffect.

7. Click OK

This creates the following files in your project:

1. The .fx file. This is a text file using the HLSL syntax which you can edit

2. The .xnb file (if you are using MonoGame or targeting Web)

3. The accompanying PostProcess file

4. A FullscreenEffectWrapper.cs file. This file is only created one time when the first post processing effect is added

If you intend to use the effects as they are when created, you do not need to work with these files. However, these files can also serve as a starting point for your own shaders so you may be interested in locating them.

Once a shader has been added, you can add it to the global effect list. If your shader is part of Global Content Files, the addition can be performed in Game1. The following code shows how to add the shader to post processing in Game1.

If your shader is part of a screen such as GameScreen, you can add it in the Screen's CustomInitialize. Note that if you add it in the Screen's CustomInitialize, you should also remove it in CustomDestroy. The following code shows how an effect might be added through GameScreen.

Note that by using a SwapChain, FlatRedBall internally creates and assigns a RenderTarget when performing rendering, so you should not manually create and assing a RenderTarget prior to drawing FlatRedBall.

Effect Files in MonoGame

Effect files require the use of the MonoGame Content Pipeline. If you are using the FlatRedBall Editor, this is automatically handled for you. You can verify that this is the case by checking the UseContentPipeline property.

Effect Files in FNA

FNA does not provide a content pipeline, and use of XNA Content Pipeline is discouraged because it does not function in newer versions of Visual Studio.

Instead, FNA recommends compiling shader files in the fxc.exe tool which is available as part of the Windows SDK.

fxc.exe can be used to build effect files which can be consumed by FNA (and FlatRedBall FNA) using syntax similar to the following command:

In the command above, ShaderFile.fx is the input file and ShaderFile.fxb is the output file. FlatRedBall recommends using the extension fxb as the output file.

Once an .fxb file is built, it can be added to FlatRedBall just like any other file (by drag+dropping it into the FlatRedBall Editor) and it will be loaded into a standard Effect object.

Introduction

The MP3 file format often used for music. All information on this page also applies to the OGG file format. FlatRedBall loads MP3 files as instances. For more information on working directly with Songs, see the .

How to play a MP3 in your game

To play an MP3 in your game:

1. Create or select the screen that you want to have the song

2. Expand the screen to see the Files item

3. Drag+drop the MP3 file from the explorer into a Screen's Files node.

   1. Alternatively you can right-click on the Files tree node and select Add File->Existing File and browse to the location of the MP3

Note that by default the dropped song uses the Microsoft.Xna.Framework.Media.Song runtime type. See below for more information on this compared to other types.

The song automatically plays when the Screen starts. The song automatically stops playing when the Screen exits. You do not need write any code to play or stop the music. If a Screen contains multiple audio files, then additional settings and logic are needed to select which song should be played.

Adding a New Default Song

FlatRedBall provides sample songs which you can use to test song playing. To add a new song to your game:

1. Right-click on the Files folder in a Screen

2. Select Add File -> New File

3. Search for Song

4. Select one of the song types and click OK

For more information on NAudio, see below.

Basic Song Controls

FlatRedBall provides simple song controls in the Song tab. To view the Song tab:

1. Add a song file to your game (as shown above)

2. Select the newly-created song

3. Select the Song tab

Moving between Screens

By default a Song added to a Screen plays when the Screen starts and stops when the screen is destroyed. To have songs persist between Screen transitions, check the Keep Playing After Leaving Screen checkbox. Note that if this is checked, the song continues to play only if either of the following conditions are true:

• The new screen does not specify a song to play

• The new screen does specify a song to play, but the song is the same as the song that was playing in the previous screen

If the new screen specifies a different song, then the new screen's song begins playing even if the old song's Keep Playing After Leaving Screen checkbox is checked.

Optionally Playing Songs

You can add multiple songs to your Screen if you would like to select which one to play in custom code. To do this:

1. Create a Screen

2. Add any number of .mp3 files to your Screen
4. In custom code, play the song you would like to play. For example, if your song is called MySong, then add the following code:

NAudio_Song

FlatRedBall provides built-in support for NAudio. When a new song is added through the Add File -> New File right-click option, a window allows the selection of NAudio or (MonoGame) Songs.

Already-added songs can be changed between Song and NAudio_Song by changing the runtime type on the file's properties.

Both MonoGame/FNA Song and NAudio_Song share much of the same functionality. Both:

• Can be managed through the Song tab in FlatRedBall

• Can be played through AudioManager.PlaySong

• Respond to the AudioManager's MasterSongVolume if played through AudioManager.PlaySong

NAudio provides additional functionality for playing songs, so games which need more control over music playing may want to use NAudio_Song.

Introduction

A NodeNetwork is a collection of nodes (points in world space), connected by links. A node network is used to perform "pathfinding" - the movement logic for navigating a map with obstacles.

Creating a NodeNetwork in Glue

Glue has built-in support for working with NodeNetworks. To add a NodeNetwork to your level screen:

1. Expand your level Screen in Glue

2. Right-click on the Files folder

3. Select Add File -> New File

4. Use the dropdown to select Node Network (.nntx)

5. Change the name of the file if desired

6. Click OK

Editing a NodeNetwork File

To edit a NodeNetwork file, double-click the file in Glue and the AIEditor should open. If you have not set up the file associations, you can do this by following these steps:

1. Right-click on the node network in Glue

2. Select View in Explorer

3. Right-click on node network file (.nntx) in Windows Explorer

4. Select Open with...
5. Click More Apps to expand the list

6. Scroll to the bottom of the list and select Look for another app on this PC
7. Navigate to the location where the FRBDK was unzipped (this is also where Glue is located)

8. Find the AIEditor.exe and select that as the default application

Introduction

The .splx file format is an XML file that stores a list of Splines. For more information on using Splines in code, see the Spline page.

Adding a SplineList file to Glue

To add a new SplineList file:

1. Create a Screen or Entity which will contain the SplineList file

2. Right-click on the Files item

3. Select "Add File"->"New file"

4. Select "Spline List (.splx)" as the file type

5. Click OK

Introduction

OpenDocument Spreadsheet files can be loaded into your game similar to .csv files. Technically, .ods files are converted to .csv files by the FlatRedBall Editor and are loaded as if they are standard CSV files.

Using .ods files offers a number of benefits over .csv files:

• They can contain formulas

• They can contain styling and formatting, such as cell colors or bold text

• They can contain dropdowns and other formatted cell types

The .ods file format does add a small amount of complexity to your projct:

• .ods files must be converted to .csv which requires installing LibreOffice

• .ods file conversion to .csv is performed by the FlatRedBall Editor if the .ods file is newer than the .csv, or if the .csv is missing. This takes a short amount of time when first opening the project.

FRB creates a class for your .ods file using the same rules as .csv files. For information about the automatic generation of data for .csv files, see the .csv page.

Example - Adding an .ods File and Accessing Values

To add a new .ods file:

1. Decide where to keep the .ods file. Usually game data such as .ods and .csv files are stored in Global Content Files

2. Right-click on the desired location (such as Global Content Files) and select Add New File

3. Select the ods file type

4. Enter a name, such as EnemyData

5. Click OK

Confirm the conversion of .ods to .csv in the popup window by clicking OK.

The newly-created file should appear in the tree view in FRB. Notice that the file is listed as a .csv file since it is converted from .ods to .csv.

You can confirm the original file is an .ods file by selecting the file and viewing its properties.

FlatRedBall automatically creates a backing data class for your file which matches the name of the .ods file. For example, the following screenshot shows the EnemyData class using the default contents of the .ods.

Similarly, the enemy data class is loaded in the object which contains the .ods file. Using the example from above, the EnemyData file would be loaded into GlobalContent and it can be accessed as shown in the following code:

// This assumes that the data is loaded into a List, not a Dictionary
var firstItem = GlobalContent.EnemyData[0];
var health = firstItem.Health;

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

Font files (.fnt) are produced by AngleCode's Bitmap Font Generator ( https://www.angelcode.com/products/bmfont/ ). These files can be loaded through the FlatRedBall Editor and used on FlatRedBall Text objects. Note that the recommended approach for working with files is through Gum. If using Gum, you do not need to explicitly load font files in the FlatRedBall Editor.

Working with .fnt Fiels in the FRB Editor

To load a font file:

1. Verify that you have the .fnt file and any referenced files already placed in the correct folder. This is important because both files must be part of the project.

2. Drag+drop the .fnt file into your Files folder - either in Global Content Files or the Files folder of a Screen or Entity

Your font file should appear in the Files folder.

This file can now be referenced on a Text's Font property.

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

Texture2D instances can be created through Glue by adding image files to entities, screens, or global content. By default, any image file added to Glue will be loaded when the containing screen/entity is created. Files added to Global Content can be accessed as soon as the game launches from any screen or entity.

Example - Adding a Texture2D For a Sprite

Texture2D's which are added to a screen or entity can be accessed by objects in the same screen or entity. The following steps show how to add a Texture2D to an entity and reference it on a sprite:

1. Create an entity with a Sprite object. See the Sprites in Glue page for more information.
2. Drag+drop a .png file from any location on your computer onto the entity's Files object. Note that if the file is not located outside of your game's Content folder, the file will be copied.

1. Select the Sprite object

2. Locate the "Texture" property

3. Use the drop-down to select the desired texture

The sprite will now use the selected texture.

Example - Accessing a Texture2D in code

Texture2D instances added to Glue can be accessed in code. If a Texture2D is added to a screen then the custom code for that screen can access the Texture2D variable name matching the name of the file (excluding extension). Similarly, if a Texture2D is added to an entity, then the custom code for that entity can access the Texture2D as well. If a Texture2D is added to global content, then any code in the entire game can access the Texture2D at any time. For this example, consider the CharacterEntity shown in the example above. The custom code for CharacterEntity can access the Character PNG as follows:

private void CustomInitialize()
{
    // This is a redundant set, since the SpriteInstance
    // already uses the Character texture. It simply shows
    // that custom code can access the Texture2D by file name
    // in a type-safe way.
    SpriteInstance.Texture = Character;
}

Similarly, files added to global content can be accessed in code through the GlobalContent object. For example, consider a file Background.png which could be added to global content:

This file could be accessed in code as shown in the following snippet:

private void CustomInitialize()
{
    SpriteInstance.Texture = GlobalContent.Background;
}

Introduction

Wav files can be used for sound effects in FRB. Wav files, which are uncompressed, are used because compression can introduce latency (delay before the sound plays).

SoundEffect and SoundEffectInstance

The FRB Editor can use .wav files to create two types of objects:

• SoundEffect

• SoundEffectInstance

By default .wav files are loaded as a SoundEffect, which is the simplest object to work with. The SoundEffect object allows fire-and-forget sound effects. Once a .wav file is added to FRB, the SoundEffect it creates can be used with a Play call as shown in the following code:

Once a SoundEffect Play call is made, the sound cannot be modified or stopped. It will play to completion and then stop. Therefore, to adjust the Play call, parameters can be added. For example to play a sound at half-volume, 0.5f could be passed as the first parameter:

By contrast, SoundEffectInstances are single-instance sounds which can be played, and manipulated after playing. For example, the following code plays a sound, but then adjusts its volume after 0.5 seconds:

To change whether a .wav file is loaded as a SoundEffect or SoundEffectInstance, change its RuntimeType as shown in the following image:

Adding a .wav to a FRB project

To add a .wav file to FRB:

1. Right-click on a Screen or Entity's Files item

2. Select Add File->Existing File

3. Navigate to the location of the .wav that you would like to use and click OK

You should see the .wav file in your project:

Alternatively you can drop WAV files into your project from Windows Explorer:

1. Open your project in the FRB Editor

2. Locate the WAV file you would like to use on disk

3. Drag+drop the file from Windows Explorer into your project in the desired Files folder. Note that if the file is not already a child of your Content folder, the file will be copied to the desired folder and the original file will be left on disk in its original location.

Playing a SoundEffect in custom code

Once a .wav file has been added to your FRB project, your Screen, Entity, or GlobalContent includes an instance of a SoundEffect in generated code.

The following example assumes a file named GunShotSound.wav, so the code instance is named GunShotSound. The following code can be added to CustomActivity to play the sound when the space bar is pressed:

WAV and XNB Files

FlatRedBall MonoGame does not require WAV files to be built and loaded from XNB files, but this is optionally supported. XNB files are built by the MonoGame content pipeline. If using the content pipeline, then the WAV file is built into an XNB file when initially added and also whenever the WAV file ever changes.

If using the content pipeline, WAV files are added as XNB files to your Visual Studio project. For example, the following SoundEffectFile.wav is part of GameScreen:

This file is automatically added to your Visual Studio project by FlatRedBall, as shown in the following screenshot:

WAV files can be explicitly rebuilt in the FRB Editor by right-clicking on the file and selecting Rebuild Content Pipeline File (.xnb).

When the file is built, the output window displays information about the build so you can diagnose problems.

Global SoundEffect, Screen/Entity SoundEffectInstance

As mentioned above, the easiest way to work with wav files is to load them as SoundEffects which provide a fire-and-forget Play method. You may want to provide additional control over SoundEffect playing in which case you can use a SoundEffectInstance. If your game pre-loads content, you can add the WAV file to global content as a SoundEffect, then add individual instances to the Screens or Entities which must play them.

Note that when this occurs, a copy is created so be careful adding instances to entities which will have multiple instances alive at once.

Note that this approach does not result in the wav file being loaded multiple times - the SoundEffect in global content is reused for each instance saving time.

To do this:

1. Add the wav file to global content. Note, this can even be done with wildcards

2. Set the RuntimeType to SoundEffect
3. Add the same file to a Screen or Entity - you can drag+drop the file from global content, or right-click on the Files folder and select Add Existing.

4. Change the RuntimeType to SoundEffectInstance using the dropdown