Introduction

All of FlatRedBall, including the editor and the core engine, is open source. If you are using FlatRedBall in your game, you may want to use source. Specifically you may want to:

1. Build the FlatRedBall Editor (aka Glue) from source to get the most up-to-date features and code generation

2. Link your game to source to improve debugging. For information on how to do this, see the Linking Games to FlatRedBall page.

Building FlatRedBall from source is not required to use FlatRedBall.

Most users do not need to follow the steps outlined in this section. New users are encouraged to skip this and head over to the Tutorials section. If you would like to build FlatRedBall to do more advanced debugging, contribute to the project, or out of pure curiosity then feel free to continue through this section.

If you are interested in using FlatRedBall in a code-only project, see the Code-Only Projects page.

Downloading FlatRedBall and Gum Source

You first need to clone FlatRedBall and Gum (two separate repositories) whether you are going to run the FlatRedBall or link your game to source.

Currently all development is being done on the NetStandard branch:

• FlatRedBall on Github

If you plan on using FlatRedBall FNA, be sure that you include all submodules when pulling FlatRedBall. This may automatically happen if you are using some Git clients (such as GitHub Desktop), but you may need to perform additional configuration if using a client that doesn't pull submodules by default (such as Rider).

FlatRedBall uses Gum UI including at runtime. This is also open source and can be found on GitHub:

• Gum on Github

Both repositories should be cloned to the same folder to make linking easier.

Installing Multi Platform Workloads

FlatRedBall Editor (Glue) links a version of FlatRedBall which builds for multiple platforms including Android and iOS. You must have an installiation that supports these platforms even if you are only building the FlatRedBall Editor.

Be sure to install both workloads:

• .NET Multi-platform App UI development

• .NET desktop development

Downloading FlatRedBall Source

The easiest way to download and keep FlatRedBall source up to date is to use a Github client such as Github for Desktop. To download source using Github for Desktop:

1. Install Github for Desktop

2. Select File -> Clone Repository
3. Select the URL tab

4. Enter the FlatRedBall URL: https://github.com/vchelaru/FlatRedBall. Keep the default folder as FlatRedBall

6. Switch to the appropriate branch. The default branch is NetStandard

After FlatRedBall is cloned, you will have a local copy on your machine.

Downloading Gum Source

You will also need to download Gum source, as FlatRedBall games which link against source also reference Gum files. To do this (assuming Github for Desktop):

1. Select File -> Clone Repository

2. Select the URL tab

3. Enter the Gum source: https://github.com/vchelaru/Gum . Keeping the default folder is recommended, but if not, be sure to use the same root as the FlatRedBall clone above.

Building the FlatRedBall Editor (Glue)

Verify that you have .NET 6 SDK installed https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/sdk-6.0.309-windows-x64-installer

To build the FlatRedBall Editor (also referred to as Glue):

1. Download the FlatRedBall repository (either clone it or download the .zip file from Github) following the steps above

2. Download the Gum repository following the steps above. Make sure to download it to the same folder where you downloaded the FlatRedBall repository, and name the folder Gum. See below for an example. If you do not do this, you will have reference errors when opening the solution.
3. Open the file <FlatRedBall Root>\FRBDK\Glue\Glue with All.sln.
4. To rebuild Glue with all plugins, select Build -> Build Solution in Visual Studio. You must Build or Rebuild the first time you run FlatRedBall. If you make further changes to any plugins, you must either build the entire solution, or build the project that contains the plugin. Simply building the Glue project, or pressing F5 to build and run Glue, will not build all plugins.\
5. Set Glue as the Startup Project

1. Building the solution creates an .exe from which the FRB editor can be run. You can find this .exe at <your git repo location>\FlatRedBall\FRBDK\Glue\Glue\bin\Debug\GlueFormsCore.exe. Alternatively, you can start up the FRB editor from Visual Studio. Doing so in Debug Mode allows you to see error messages in case the FRB editor throws an exception.

It's important that Gum and FlatRedBall are checked out to the same folder. For example, you may have:

• c:/MyDocuments/FlatRedBall

• c:/MyDocuments/Gum

Troubleshooting

Gum Project References Broken

The Glue project references Gum projects, so the two project folders must be in the same root folder. To verify:

1. Open Glue with All.sln

2. Open the Solution Explorer

3. Expand the GumProjects folder

If the references are correct, your window should look similar to the following image:

If your references are broken, then you may see something similar to the following image:

Notice that the projects are marked as unloaded. To solve this make sure that both of the projects (FlatRedBall and Gum) are in the same root folder. If you unzipped the files, then they may need to be moved up one folder.

Microsoft.Windows.UI.Xaml.CSharp.targets was not found...

When opening the project, you may get a message which states:

The imported project "C:\Program Files (x86)\MSBuild\Microsoft\WindowsXaml\v14.0\8.1\Microsoft.Windows.UI.Xaml.CSharp.targets" was not found. Confirm that the path in the <Import> declaration is correct, and that the file exists on disk. C:\Program Files (x86)\MSBuild\Microsoft\WindowsXaml\v14.0\Microsoft.Windows.UI.Xaml.CSharp.targets

For information on how to solve this problem, see the following link: http://www.c-sharpcorner.com/UploadFile/8a67c0/visual-studio-2015-feature-shared-project-part-2/

Prerequisites

1 - Visual Studio 2022 or Newer

https://visualstudio.microsoft.com/vs/community/ Although it is possible to make games without Visual Studio or Rider, doing so requires advanced knowledge of MSBuild. We recommend downloading and installing Visual Studio Community which is free.

At a minimum you need to install .NET desktop development.

2 - XNA 4.0 Redistributable

https://www.microsoft.com/en-us/download/details.aspx?id=27598 Although this is not required to build and run FlatRedBall games, it is required to use Gum, which is the preferred FlatRedBall UI tool.

3 - .NET SDK

FlatRedBall projects are built with .NET 8 or newer. If you are using Visual Studio then you do not need to explicitly install .NET 8. If you are using a different IDE such as Visual Studio Code, then you need to install .NET SDK 8:

https://dotnet.microsoft.com/en-us/download/dotnet/8.0

You must also install the .NET 6 SDK even if you have .NET 8 installed since the FlatRedBall Editor relies on this version for loading projects. This may change in a future version of FlatRedBall:

https://dotnet.microsoft.com/en-us/download/dotnet/6.0

Newer Versions of Visual Studio (as of version 17.5.1) install .NET SDK 7.0 or newer which have a bug preventing projects from being loaded in the FlatRedBall Editor. Therefore, you need to manually install .NET 6 SDK.

4 - Visual C++ Redistributable Packages for Visual Studio 2013

This dependency is required to build shader files. If you are certain that you will not be using any custom shaders or post processing, then you can skip this installation. However, we recommend installing this to avoid confusing errors if you do end up using any shaders.

https://www.microsoft.com/en-us/download/details.aspx?id=40784

Downloading FlatRedBall

The most common approach to making FlatRedBall games is to use the FlatRedBall Editor. The Editor can be downloaded from a pre-built .zip file, or it can be built from source. New users should download the pre-built .zip file.

Downloading and Running FlatRedBall

1. Download the latest zip file from https://files.flatredball.com/content/FrbXnaTemplates/DailyBuild/FRBDK.zip.

   1. Alternatively, the FlatRedBall Editor (no additional tools) prebuilt can be downloaded from Github. This is not recommended for new users, but experienced users can replace the FlatRedball Glue folder with the contents from the built files: https://github.com/vchelaru/FlatRedBall/actions

2. 1. Right-click the ZIP file and chose Properties

   2. Check-mark the Unblock option and Click Apply

   3. Close the Properties window

3. Unzip the file after downloading
4. Go to the folder where the .zip file unzipped to (by default called FRBDK)

5. Open the Run FlatRedBall.bat file (double click it)

If you see the Windows protected your PC dialog, click More info -> Run Anyway

The FlatRedBall Editor should appear.

If you're stuck on a problem or if you believe you've found a bug, there's lots of ways to get in touch with us.

Adding FlatRedBall Source to a Game Project using the FRB Editor

To add the FRB source to your project:

1. Make sure you have already cloned the FlatRedBall and Gum repositories. We recommend using Github for Desktop and cloning to the default location so that your game and FlatRedBall are sibling folders in the same parent folder. For more information on cloning FlatRedBall, see the main Building FlatRedBall From Source page. For more information on cloning Gum, see this section on the main Building FlatRedBall From Source page.

2. Open your project in the FlatRedBall Editor

3. Select the Project -> Link Game to FRB Source menu item
4. The Add FRB Source tab appears, showing a text box for FlatRedBall and Gum root folders. If your current project is also a Git project which is cloned to the same folder as FlatRedBall and Gum, then the FRB Editor attempts to fill in the file paths.

5. If your paths are blank or incorrect, use the ... button to select the file paths for each repository. Select the root folder for where Gum and FRB repositories.

   1. The FRB Root Folder is the folder where FlatRedBall is cloned locally. For example, if you use the default folders when cloning in Github Desktop, this would be <Documents Folder>\GitHub\FlatRedBall\ . This folder contains the root-most FlatRedBall files like LICENSE and README.doc

   2. The Gum Root Folder is the folder where Gum is cloned locally. For example, if you use the default folders when cloning in Github Desktop, this would be <Documents Folder>\GitHub\Gum\ . This folder contains the root-most Gum files like Gum.sln

6. If you are planning to use Gum Skia, check the option

7. Click Link to Source

8. After your project is linked, the Add FRB Source tab will disappear

Your game project should now directly reference the FlatRedBall Source.

Game Project Location and FlatRedBall Source

The FlatRedBall Editor attempts to link FlatRedBall source regardless of the location of your projects relative to source. We strongly recommend keeping your project in the same directory (such as C drive) as FlatRedBall source. Otherwise, projects will be linked using absolute paths which makes your project far less portable. By using absolute paths others who clone your project must have the same exact folder structure as you do or the project will not build and run.

Furthermore, Github for Desktop always clones projects to the same directory: C:\YouserUerName\Owner\Documents\GitHub\YourProjectName

We recommend keeping these defaults for all repositories - your game and FlatRedBall. By using default locations others can clone the engine and game without needing ot make modifications to their defaults.

Adding FlatRedBall Source to a Game Project Manually

If you would like to use the engine source in your game project:

1. Open your game project in Visual Studio

2. Expand the game project in the solution explorer

3. Expand the References item

4. Find the FlatRedBall entries. This is the reference to the prebuilt-dll. Note that these may be direct references or NuGet packages depending on which version of FlatRedBall you are using, so be sure to check under both Assemblies and Packages. Press the Delete key on all references as mentioned below:

   1. FlatRedBall DesktopGL:

      1. FlatRedBallDesktopGLNet6

      2. FlatRedBall.Forms.DesktopGlNet6

      3. GumCore.DesktopGlNet6

      4. SkiaInGum

      5. StateInterpolation.DesktopNet6

   2. FlatRedBall FNA:

      1. FlatRedBall.FNA

      2. FlatRedBall.Forms.FNA

      3. GumCore.FNA

      4. StateInterpolation.FNA

5. Right-click on the solution

6. Select Add -> Existing Project...

7. Navigate to the location of the FlatRedBall .csproj file for your given platform. For example, for PC, add <FlatRedBall Root>\Engines\FlatRedBallXNA\FlatRedBall\FlatRedBallDesktopGL.csproj
8. Click Open to add the project to your game's solutionComment

9. Right-click on your game's References item and select Add Reference...Comment

10. Click the "Projects" categoryComment

11. Check the FlatRedBallDesktopGL project (or whichever FlatRedBall project used for the given platform)Comment

12. Repeat the process for the other librariesComment

13. Click OK
14. Build and run your project

Introduction

If you're looking to get started without going through lengthy tutorials, this guide will get you running with the minimum number of steps.

Note that this guide assumes you are using the FlatRedBall Editor. If you are creating a code-only project, see the Code Only Projects page.

Downloading FlatRedBall

First you will need to make sure you have the prerequisites. Once you do, you need to download FlatRedBall. For detailed steps, see the Downloading FlatRedBall page.

Creating a New Project

To create a new project:

1. Click the Create New Project button
2. Leave the defaults and click the Create Project! button. The defaults select the most common project setup.
3. After the project loads, the Project Setup Wizard appears. Select which project type you would like such as Standard Platformer or Standard Top Down. These options are the quickest way to get a functional game running. If you would like to have an empty project, close the wizard by pressing the X button at the top right.

   1. If you selected a project type, wait for the project creation to finish.

You now have a FlatRedBall Project. You can run the project through the FlatRedBall Editor, or in Visual Studio.

Running your Project in FlatRedBall

To run your Project in FlatRedBall, click the play button. Notice that this tells you which Screen will load when the project starts.

Once the project is running you will see it in its own window.

Running in Visual Studio

To run your project in Visual Studio:

1. Click the Visual Studio icon in FlatRedBall\
2. Wait for the project to load in Visual Studio
3. Press the Play button to build and run your project in Visual Studio. FlatRedBall projects are standard .NET projects, which means you can treat it as you would any other .NET project including debugging, NuGet packages, and full C# syntax support.

What's next?

Now that you have FlatRedBall running on your machine, you can get started making games. Here are some next steps to consider:

• Join the FlatRedBall Discord - come say "hi" and tell us about what you want to do with FlatRedBall. We have an active community who loves to help new users.

• Check out the Beefball tutorials and other tutorials. These will get you up to speed on how to use the FlatRedBall Editor.

• If you prefer to dive right in to the docs, check out the FlatRedBall Editor reference to see what it can do, or the FlatRedBall API Documentation for info about working with FlatRedBall in code.

• Try things out! The best way to learn is by doing, so try making changes to the project and explore what is already there.

Introduction

If you're looking for a jump-start on how to make games with FlatRedBall and the FlatRedBall Editor, you've come to the right place. The following tutorials walk you through how to make a game called Beefball. Beefball is a fast-paced physics based game similar to air-hockey. What are you waiting for, let's get started!

Completed Project: Beefball.zip

Code Only Projects

This tutorial covers how to create Beefball with the FlatRedBall Editor, which is the typical way to work with FlatRedBall. Of course, you can also use FlatRedBall without the editor. If you are interested in developing in a code only environment, you can download the BeefballCodeOnly project which is located in the FlatRedBall Samples folder:

You can still look through this documentation to see how the project might be structured conceptually as you browse the sample code.

Introduction

By default FlatRedBall projects link pre-built binary files including prebuilt FNA libraries. You may want to link your FlatRedBall project to FNA source for improved debuggability or to contribute back to FNA.

This document includes the required steps for linking your game to FNA.

Linking Your Game to FRB Source

Before you link your game to FNA, you must first link your game to FRB source. If you do not do this, then the FlatRedBall.FNA nuget package will include FNA which results in the FNA libraries being included twice.

Follow the steps outlined here to link your game to source: Linking your Game to FlatRedBall Source.

Once you have finished these steps, your solution should include your game project and all FlatRedBall source projects.

Linking Latest Native Libraries

By default FlatRedBall templates include FNA binaries which are marked as copy if newer. These can be found in your game's csproj at the root level:

These are marked as copy if newer:

If you would like to update these to the latest version, you can:

1. Download the latest daily files from https://github.com/FNA-XNA/fnalibs-dailies/actions

2. Unzip the folder for x64

3. Copy the files into your game project

The latest .dll files will now be copied to your bin folder whenever the game is built.

Welcome!

We're glad you came to check out FlatRedBall. Before jumping in, let's take a few moments to discover what FlatRedBall is all about. If you're new to game development or just new to FlatRedBall, this page will introduce you to common FlatRedBall (FRB) concepts.

What is FlatRedBall?

The FlatRedBall game engine has been in active development since 2005 with the goal of making 2D game development as easy as possible. Even today FlatRedBall is continually being improved. Not only are we developing the best 2D game engine in the world, but we're actively using it to make our own games. Every FlatRedBall feature has been tested with a real-world game development team.

All FlatRedBall development centers around a program called the FlatRedBall Editor.

This program is where you'll start when making a new project, and you'll use it throughout development as your game grows. The editor is a visual tool, which means you won't be writing any code directly in the editor. However, the editor is a programmer-friendly environment. Everything you do in the editor results in generated code. This makes your game easy to debug and keeps your program as efficient as possible.

You still have the full power of C# and Visual Studio to write and debug code. Ultimately your project is a standard .NET project which builds and runs just like any other project. It's real .NET!

The editor can set up your project and keeps it structured using the best patterns, but gives you all of the freedom you'd expect from a code-based game engine.

FlatRedBall Code-Only Projects

Although FlatRedBall provides a powerful editor, if you prefer you can use FlatRedBall in code-only situations. Ultimately the FlatRedBall Editor does not generate any binary data - it is all code generated, which means you can do everything that the editor does yourself. You can even use the FlatRedBall Editor to look at the generated code to learn how to write your own code.

Screens

Screens define the flow of your game. Most games have a screen called GameScreen for all common parts of the main game play. For example, GameScreen may contain a list of enemies, a player, a list of collectable coins, and collision for the player and enemies to walk on. Anything that's specific to a particular level (such as the Tiled map file) is added to a new screen for that specific level. Games may also have screens which aren't created specifically for game play, such as settings, credit, and level select screens. To help visualize this, let's take a look at the screens that might be used in a game like Super Mario World.

Note that the three levels are grouped together because they use the GameScreen as their base screen. Of course, a full game like Super Mario World contains dozens of screens, but the picture above gives an example of how it could be organized.

Tiled Map Files

Each level in FlatRedBall uses (at least) one Tiled Map File. Tiled is a powerful, commonly-used tool for creating level files using tileset images. The following image shows a typical platformer level in Tiled.

Notice that the level is composed of small squares which are called tiles. This approach to game development can be very efficient because it allows reuse of art to create large levels. The image above is created using tiles from a tileset sprite sheet which is a .png file with all of the art needed to create a level.

Once you have a tileset created, making new levels is easy.

Entities

Entities are objects in your game which can move (a player walking in a level), collide (a bullet hitting a wall), have animations (an enemy playing a walk animation), and have AI behavior (enemy ships flying towards a target). In other words, entities are objects in a game world which the player can interact with. There are two parts to creating an entity. The first is to define the entity. When creating an entity, you are answering the following questions:

• What does it look like?

• Does this entity have collision? In other words, do we care if this entity is touching any other entity or any solid part of the level? For example, coins in Super Mario World are entities which have collision so that the game can respond when Mario touches the coin.

• Can the entity be controlled by the player?

• Does the entity have any logic that has to be continually performed every frame? For example, an enemy in Mario must check whether it is going to walk off of a cliff. Some enemies turn around when reaching the edge of a platform.

Once you've defined an entity, you can place the entities in a screen. Each time you place an entity in a screen, you are creating an instance of that entity. A screen may have lots of instances of an entity. For example, consider the following image from Super Mario World.

Here we see eight instances of the Coin entity. Of course, the full level may have dozens or even hundreds of coins. The image above also has a few Enemy entity instances, and an instance of the Player (Mario).

Gum

FlatRedBall works well with the Gum UI tool. You can add user interfaces like menus and HUD (UI) to your game with no code. Experienced programmers will feel right at home working with Gum. It provides an event system similar to other common UI frameworks such as WPF, Winforms, and Xamarin Forms. Gum is a visual layout tool with a flexible, powerful layout engine. You can create pretty much anything in Gum!

You can use Gum to create interactive menu screens (as shown above) or in-game HUD.

Live Editor

FlatRedBall's Editor is also a live editor, enabling the creation of content in real time. The live editor comes out-of-the-box with powerful features, but it can be customized by adding code to your game. You can add error checking, real time visualizations, and custom logic in response to variable assignments. The editor runs your game, so your code runs while you are making changes.

FlatRedBall is Active

FlatRedBall is one of the longest-running actively developed game engines available! We started development in 2005 and never stopped. It is fully open-source (MIT License) on GitHub and is updated almost daily with bug fixes and improvements.

If you need help you can post an issue or join our Discord channel. The FlatRedBall team is dedicated to making the best game engine for you and for ourselves. We are continually dogfooding (using it to make our own games). This means our improvements are not just to show off fancy visuals, but to help you complete your game as fast as possible.

Let's Get Started

If you're ready to start making games, head over to the downloads page to get the latest version of FlatRedBall. Once it's installed, start moving through the tutorials to start making your first game.

Introduction

So far we have a very simple project with a PlayerBall (which appears as a Circle) which can be moved with a gamepad or the keyboard. This tutorial covers creating collision for the game. This tutorial introduces two new types.

• ShapeCollection - an object which can contain any number of shapes. Adding multiple shapes to a ShapeCollection makes the creation of collision relationships very easy.

• AxisAlignedRectangle - this is a rectangle shape which can be created in Glue just like We'll use multiple AxisAlignedRectangles to assemble our level, and we'll be organizing these in a list object.

Creating the Walls ShapeCollection

First we'll create a ShapeCollection called Walls. This ShapeCollection contains all of the rectangles in our game. ShapeCollections are a specialized list which can contain multiple instances of Shape objects such as Circles and AxisAlignedRectangles. To create the Walls ShapeCollection:

1. Select GameScreen

2. Click the Quick Actions tab

3. Click Add Object to GameScreen

4. Select ShapeCollection as the type

5. Enter the name Walls

6. Click OK

Adding Wall AxisAlignedRectangles

Now that we have a ShapeCollection for our walls, we can add the individual walls. To add the first wall AxisAlignedRectangle:

1. Right-click on the Walls item.

2. Select Add Object

3. Select AxisAlignedRectangle as the type. Notice that available types are limited to shapes since we are adding to a ShapeCollection.

4. Enter the name Wall1 and click OK.

Now we can modify the properties of this wall. Select Wall1 and change the values as follows:

• Y = 300

• Width = 800

• Height = 30

Doing so moves the rectangle to the top of the screen. If you run the game you should see the wall at the top of the screen.

Now that we've created a single wall, we can duplicate it by right-clicking on it and selecting the "Duplicate" command:

Create 5 duplicates, so that the Walls list holds a total of 6 AxisAlignedRectangle instances:

Next set the X, Y, Width, and Height variables for for the newly-created walls as follows: Wall2

• X = 0

• Y = -300

• Width = 800

• Height = 30

Wall 3

• X = -400

• Y = 200

• Width = 30

• Height = 200

Wall 4

• X = 400

• Y = 200

• Width = 30

• Height = 200

Wall 5

• X = -400

• Y = -200

• Width = 30

• Height = 200

Wall 6

• X = 400

• Y = -200

• Width = 30

• Height = 200

When finished, the game should have walls made of AxisAlignedRectangles with gaps on the left and right sides for goals:

Implementing Collision

Next we'll use collision relationships to define collision between the PlayerBall and Walls. We'll revisit collisions in later tutorials, so keep in mind that this is only the first step in setting up our game's collision. When we created our PlayerBall entity in an earlier tutorial, we marked that the entity should contain a Circle object. Doing so automatically marked the Entity as using the ICollidable interface. As a reminder, the following image shows the window we used to create the PlayerBall entity:

Since our PlayerBall is an ICollidable, that means it can collide with any other ICollidable and with any shapes - like the Walls. We need to tell our game that we want the PlayerList to collide against the PlayerWalls. The easiest way to do this is to create a Collision Relationship in Glue. To do this:

1. Drag+drop the PlayerBallList onto the Walls in the Glue explorer. This creates a new CollisionRelationship

2. Select the new CollisionRelationship (which is named PlayerBallVsWalls)
3. Select the Collision tab

4. Change the Collision Physics to Bounce Collision so that our PlayerBall bounces against the walls

5. Change the PlayerBall Mass to 0. This means that the PlayerBall behaves as if it has no mass, so it will not be able to move the walls. Be sure to press Enter or Tab to save the change.

If we run the game now, the PlayerBall collides with the walls.

We use CollisionRelationships here because they are very powerful and require no code. Just like everything else in FlatRedBall, collisions can also be managed in code. If you are interested in writing collision purely in code, see the CollideAgainstMove page.

Why doesn't the PlayerBall Bounce?

The CollisionRelationship we created in the previous step set the Collision Physics to Bounce Collision, but if we move the PlayerBall to the wall, it doesn't bounce. While this may seem like bounce collision is broken at first glance, the real reason is because of the way our movement has been implemented. Our code in PlayerBall sets the velocity values every frame. When the PlayerBall collides against the wall, the bounce physics sets the velocity values to simulate a bounce; however, our code in PlayerBall overwrites this velocity immediately. We will make changes in a later tutorial to our movement code so we no longer overwrite the velocity every frame, and so the bounce movement works as expected.

Conclusion

Even though the game isn't really playable yet, we're definitely starting to see something come together. We have a movable object and game boundaries which have solid collision. The next tutorial duves deeper into the control of our PlayerBall Entity.

Introduction

This tutorial implements more advanced controls for the PlayerBall. Most games with first-person control (that is control where you directly direct an Entity, as opposed to third person control like RTS games - not to be confused with first person view) have fairly complex control logic. We'll be implementing more advanced controls in our game, investigating the logic in detail along the way.

Velocity vs. Acceleration

Our current implementation provides immediate control over the PlayerBall's velocity values:

this.XVelocity = MovementInput.X * MovementSpeed;
this.YVelocity = MovementInput.Y * MovementSpeed;

In other words, if the input for moving right is held (whether that's a keyboard key or an Xbox360 analog stick), the PlayerBall immediately moves at maximum speed. Similarly, when the movement input is released, the PlayerBall immediately stops. As mentioned earlier, this logic prevents the collision relationship from making the ball bounce. We will modify our input code to gradually add to the speed of the PlayerBall when the input is held down. To do this, we'll change our code to set the PlayerBall's acceleration rather than velocity. Modify the MovementActivity in PlayerBall.cs as follows:

private void MovementActivity()
{
    if (MovementInput != null)
    {
        this.XAcceleration = MovementInput.X * MovementSpeed;
        this.YAcceleration = MovementInput.Y * MovementSpeed;
    }
}

Notice that the code above still uses the MovementSpeed variable, which can be modified in Glue. This value can be increased to make movement more responsive. You may want to increase this value from 100 to a larger number such as 300. Now our ball can bounce against the walls, and it doesn't immediately speed up or slow down - it takes some time to gain speed.

Since we're no longer setting velocity values directly (acceleration values add and subtract to the current velocity), the ball continues to move even after releasing input. We'll address this in the next section.

Reducing Momentum

We'll use the Drag property to slow the PlayerBall. Drag modifies velocity proportionally and in the opposite direction of current Velocity. In other words, drag slows an object regardless of its movement direction. The faster an object is moving, the more Drag reduces its velocity. Drag is a built-in variable on all Entities, so if you are creating a game which uses acceleration to move an object, you may want to also implement Drag. Drag is applied whether an object is accelerating or not. Drag slows an object in proportion to its absolute speed - the faster it moves the more Drag slows velocity. This results in a maximum speed, also known as terminal velocity. To add Drag to the PlayerBall Entity:

1. Select the PlayerBall Entity in Glue

2. Select the Variable tab

3. Click the Add New Variable button

4. Select the Expose an existing variable option

5. Click the Drag variable

6. Click OK

7. Change the Drag variable to 1

The addition of Drag has changed the way our ball moves:

1. The ball now has a maximum speed

2. Releasing all input results in the ball slowing down

3. The ball does not accelerate as quickly as it used to

We'll increase the MovementSpeed to make up for the addition of Drag on the PlayerBall's acceleration. Feel free to play with the MovementSpeed variable. A value around 350 should result in responsive movement.

Bouncing Elasticity

The previous tutorial created a collision relationship between the PlayerBall and Walls. Now that we have bouncing implemented, we can revisit the PlayerListVsWalls collision relationship. Notice that the relationship provides an Elasticity value as shown in the following image:

This value controls how much velocity is preserved after a collision occurs. A value of 1 indicates that 100% of the velocity is preserved. A value less than 1 results in some of the velocity being absorbed. Feel free to play with this number to create a bounce elasticity that you like. If you want the balls to remain bouncy, you can keep it at 1. If you want the walls to absorb some of the PlayerBall velocity, try putting a (positive) value less than 1, such as 0.5.

Conclusion

Now we're getting somewhere! The game is starting to feel pretty solid. Next we'll add a Puck Entity which can be used to score goals.

Introduction

So far we have a basic structure for our game: an Entity with graphical representation, a Screen, and an instance of our Entity in our Screen. This tutorial requires writing code.

How will we control our Entity?

Before implementing code to control your Entity you need to decide how to control an Entity. For this tutorial we will implement controls using gamepads as well as keyboard (in case you do not have a gamepad). We will use FlatRedBall's input interfaces so that our game code doesn't need to consider which input device is using after initial setup. Note that FlatRedBall uses the Xbox36GamePad name since FlatRedBall was originally written to work with XNA. Most controllers will work including wired and wireless XBox controllers, Switch Pro controllers, and Playstation DualShock (although usually the DualShock requires a wired connection).

Defining Control Interfaces

First we need to define which controls are needed in our game. Our PlayerBall requires the following input:

• Movement in the X and Y coordinates - also known as "2D input"

• Input for executing a boost. Boosts temporarily increase the player's speed when executed for a short amount of time. The user does not need to hold the input down, simply pressing the button/key is enough.

We'll write the PlayerBall so that it works with any input device, whether that's Xbox 360 controller, Keyboard, or any other device. To add code to PlayerBall, double click PlayerBall.cs in Visual Studio. This is located in your project's Entities folder.

Modify the PlayerBall.cs file so it contains two input properties as follows:

public partial class PlayerBall
{
    public I2DInput MovementInput { get; set; }
    public IPressableInput BoostInput { get; set; }
    ...

Next we will add code to move the player ball. Notice that there are four methods in PlayerBall.cs:

• CustomInitialize

• CustomActivity

• CustomDestroy

• CustomLoadStaticContent

CustomActivity gets called every frame, so we can use it method to respond to controller input and modify our PlayerBall appropriately. Add the following code in the CustomActivity method in PlayerBall.cs:

private void CustomActivity()
{
    float movementSpeed = 10;
    if (MovementInput != null)
    {
        this.XVelocity = MovementInput.X * movementSpeed;
        this.YVelocity = MovementInput.Y * movementSpeed;
    }
}

At this point we have written fully-functional code for moving the ball according to its MovementInput; however, we haven't assigned the MovementInput yet. We'll do this next.

Assigning Movement Input

The MovementInput and BoostInput were intentionally created as public properties so that they could be assigned by the GameScreen. The GameScreen will contain logic for deciding which input device to use. To assign the input interfaces, open GameScreen.cs in the Screens folder and modify the CustomInitialize method as follows:

public partial class GameScreen
{
    void CustomInitialize()
    {
        PlayerBall1.MovementInput =
            InputManager.Keyboard.Get2DInput(Microsoft.Xna.Framework.Input.Keys.A,
            Microsoft.Xna.Framework.Input.Keys.D,
            Microsoft.Xna.Framework.Input.Keys.W,
            Microsoft.Xna.Framework.Input.Keys.S);
        PlayerBall1.BoostInput = InputManager.Keyboard.GetKey(Microsoft.Xna.Framework.Input.Keys.B);
    }
    ...

Notice that the object we are assigning code to (PlayerBall1) matches the name of the entity in the editor. FlatRedBall objects in the editor always have a matching name in code, as shown in the following image:

For more information on the Keyboard class, see the Keyboard page.

Cleaning up the code

Clean code is very important. This is something we stress at FlatRedBall for all developers making any kind of game regardless of size. Therefore, this tutorial (and others in the future) discusses how code can be improved to be more flexible and maintainable. The code we wrote above has a number of problems:

• The velocity (which was set to 10) is set right in the method where it's used. This velocity value is typically considered "data", while its application is considered "logic". The separation of data from logic is a fundamental concept in keeping game projects maintainable.

• The game includes logic in the CustomActivity method. We encourage no logic, only method calls in the standard "Custom" methods.

Separating Data from Logic using FlatRedBall Variables

FlatRedBall provides a number of ways to separate data from logic. The simplest of these is to create variables. To add a variable to the PlayerBall entity:

1. In the editor, click the PlayerBall Entity

2. Right the Variables tab

3. Click the Add New Variable button

4. Verify that float is the Type

5. Enter the name MovementSpeed and click the OK button

6. Verify Variables is selected and set MovementSpeed to 100. Deselect the text box or press ENTER to apply the value.

Finally, return to the movement code inside PlayerBall.cs and change the code to:

private void CustomActivity()
{
    if (MovementInput != null)
    {
        this.XVelocity = MovementInput.X * MovementSpeed;
        this.YVelocity = MovementInput.Y * MovementSpeed;
    }
}

If we run the game now we can control the player with the W, A, S, and D keys:

Adding Gamepad Controls

The benefit of using the input interfaces (I2DInput and IPressableInput ) is that the input device being used can be set or changed without any code changes in the entity. For example, we can modify the GameScreen to optionally use an gamepad if connected, otherwise it falls back to using the keyboard. To add support for keyboard and gamepad controls, open GameScreen.cs and Modify CustomInitialize as shown in the following code:

void CustomInitialize()
{
    // As mentioned above, non-xbox controllers should work fine
    if (InputManager.Xbox360GamePads[0].IsConnected)
    {
        PlayerBall1.MovementInput =
            InputManager.Xbox360GamePads[0].LeftStick;
        PlayerBall1.BoostInput =
            InputManager.Xbox360GamePads[0].GetButton(Xbox360GamePad.Button.A);
    }
    else
    {
        PlayerBall1.MovementInput =
            InputManager.Keyboard.Get2DInput(Microsoft.Xna.Framework.Input.Keys.A,
            Microsoft.Xna.Framework.Input.Keys.D,
            Microsoft.Xna.Framework.Input.Keys.W,
            Microsoft.Xna.Framework.Input.Keys.S);
        PlayerBall1.BoostInput = 
            InputManager.Keyboard.GetKey(Microsoft.Xna.Framework.Input.Keys.B);
    }
}

For more information on Xbox360GamePad, see the Xbox360GamePad page.

Cleaning CustomActivity and CustomInitialize

Finally, we should clean up CustomActivity. In general, we encourage keeping the Custom methods free of logic so that it is clear what an Entity/Screen is doing when initialized and when destroyed without having to mentally translate code into concept. Open PlayerBall.cs and replace the CustomActivity with the following:

private void CustomActivity()
{
    MovementActivity();
}

Then define MovementActivity in PlayerBall.cs file:

private void MovementActivity()
{
    if (MovementInput != null)
    {
        this.XVelocity = MovementInput.X * MovementSpeed;
        this.YVelocity = MovementInput.Y * MovementSpeed;
    }
}

Similarly, we'll want to clean up the CustomInitialize method in GameScreen.cs:

void CustomInitialize()
{
    AssignInput();
}

We'll implement the AssignInput method in GameScreen.cs:

private void AssignInput()
{
    if (InputManager.Xbox360GamePads[0].IsConnected)
    {
        PlayerBall1.MovementInput =
            InputManager.Xbox360GamePads[0].LeftStick;
        PlayerBall1.BoostInput =
            InputManager.Xbox360GamePads[0].GetButton(Xbox360GamePad.Button.A);
    }
    else
    {
        PlayerBall1.MovementInput =
            InputManager.Keyboard.Get2DInput(Microsoft.Xna.Framework.Input.Keys.A,
            Microsoft.Xna.Framework.Input.Keys.D,
            Microsoft.Xna.Framework.Input.Keys.W,
            Microsoft.Xna.Framework.Input.Keys.S);
        PlayerBall1.BoostInput =
            InputManager.Keyboard.GetKey(Microsoft.Xna.Framework.Input.Keys.B);
    }
}

Conclusion

Now we have a PlayerBall Entity which is cleanly written, has speed which can be customized through the FlatRedBall Editor, and can be moved with the game pad or keyboard. The next tutorial covers defining collision in the GameScreen.

Introduction

Now that we have a visible HUD, we need to add logic to have it update when players score. This tutorial adds code to the ScoreHud to update the displayed text according to public properties which are set by GameScreen whenever a goal is scored.

Adding Team Score Properties

First we'll be adding properties to the Hud object for the scores of each of the players. We could do this purely in code, but the FRB Editor provides a convenient way to set the score values to integers. We will be combining two FRB Editor features for this:

• Tunneling variables - Creating a variable in an entity which is tied to the variable of a contained object. In this case we'll be creating variables which are tied to each of the score Texts' DisplayText variable.

• Built-in casting of the variable type - although DisplayText is a string, we'll tell FRB that we intend to use it as an integer.

To do this:

1. Expand ScoreHud's Objects in the FRB Editor

2. Drag+drop the Team1Score onto the Variables item

3. Select DisplayText as the variable

4. Set the Alternative Name to Score1

5. Set the Converted Type to int

6. Click OK

Repeat the steps above, but this time use Team2Score, and create a variable called "Score2".

Updating the HUD

Now that the ScoreHud can react to score changes, the ReactToNewScore can be modified to update the HUD. To do this, modify the ReactToNewScore method in GameScreen as follows:

private void ReactToNewScore()
{
    PlayerBall1.X = -180;
    PlayerBall1.Y = 0;
    PlayerBall1.Velocity = Microsoft.Xna.Framework.Vector3.Zero;
    PlayerBall1.Acceleration = Microsoft.Xna.Framework.Vector3.Zero;

    PlayerBall2.X = 180;
    PlayerBall2.Y = 0;
    PlayerBall2.Velocity = Microsoft.Xna.Framework.Vector3.Zero;
    PlayerBall2.Acceleration = Microsoft.Xna.Framework.Vector3.Zero;

    Puck1.X = 0;
    Puck1.Y = 0;
    Puck1.Velocity = Microsoft.Xna.Framework.Vector3.Zero;


    ScoreHud1.Score1 = player1Score;
    ScoreHud1.Score2 = player2Score;

}

If we run the game now we'll notice that scores start out at 0 and increments whenever a player scores a goal.

Troubleshooting

If you are seeing a conversion error similar to Cannot implicitly convert type 'int' to 'string' , then you may need to modify the variables for Score1 and Score2. See the steps above where the Variable Type is set to int. If you've already created the variables, you can set the variable conversion:

1. Select the Score1 variable

2. Select the Properties tab

3. Change OverridingPropertyType to int

Conclusion

Well, that was easy! Now we have scoring working. At this point we could call the game done. The next tutorial adds some extra finishing touches to the controls to make it more competitive and make the game play deeper.

Introduction

Beefball is intended to be a competitive multiplayer game. So far we only have one PlayerBall instance, so let's add some more PlayerBall instances. Previously we added a list for our PlayerBall. We can now add a second PlayerBall with minimal changes to our project.

Adding a new PlayerBall

To add a new PlayerBall:

1. Expand the GameScreen's Objects folder

2. Select the PlayerBallList object

3. Select the Quick Actions tab

4. Click the Add a new PlayerBall to PlayerBall List. Alternatively, you can right-click on the PlayerBallList and select Add Object

1. Change the new PlayerBall's X value to 180

You should now see two PlayerBall instances under the PlayerBallList and in game. Also, since we created our collision relationships between the lists, the new PlayerBall can already collide against the walls and the Puck.

Player vs. Player collision

Now that we have two PlayerBall instances, we need to add a new collision relationship. This time, we will create a collision relationship between the PlayerBallList vs itself. To do this:

1. Select the PlayerBallList

2. Select the Collision tab

3. Find the PlayerBallList in the list of items

4. Click the Add button

5. Set Collision Physics to Bounce

If you run you game now, the two PlayerBall instances collide against each other. Also, if we added more players (a third or fourth player) those would also collide with each other automatically.

Adding input for Player 2

We'll assign input on PlayerBall2Instance with code similar to the input-assigning code for PlayerBallInstance. To do this, open GameScreen.cs and modify AssignInput as shown in the following code:

private void AssignInput()
{
    if (InputManager.Xbox360GamePads[0].IsConnected)
    {
        PlayerBall1.MovementInput =
            InputManager.Xbox360GamePads[0].LeftStick;
        PlayerBall1.BoostInput =
            InputManager.Xbox360GamePads[0].GetButton(Xbox360GamePad.Button.A);
    }
    else
    {
        PlayerBall1.MovementInput =
            InputManager.Keyboard.Get2DInput(Microsoft.Xna.Framework.Input.Keys.A,
            Microsoft.Xna.Framework.Input.Keys.D,
            Microsoft.Xna.Framework.Input.Keys.W,
            Microsoft.Xna.Framework.Input.Keys.S);
        PlayerBall1.BoostInput =
            InputManager.Keyboard.GetKey(Microsoft.Xna.Framework.Input.Keys.B);
    }

    if (InputManager.Xbox360GamePads[1].IsConnected)
    {
        PlayerBall2.MovementInput =
            InputManager.Xbox360GamePads[1].LeftStick;
        PlayerBall2.BoostInput =
            InputManager.Xbox360GamePads[1].GetButton(Xbox360GamePad.Button.A);
    }
    else
    {
        PlayerBall2.MovementInput =
            InputManager.Keyboard.Get2DInput(Microsoft.Xna.Framework.Input.Keys.Left,
            Microsoft.Xna.Framework.Input.Keys.Right,
            Microsoft.Xna.Framework.Input.Keys.Up,
            Microsoft.Xna.Framework.Input.Keys.Down);
        PlayerBall2.BoostInput = 
            InputManager.Keyboard.GetKey(Microsoft.Xna.Framework.Input.Keys.RightShift);
    }
}

Now each PlayerBall uses a different Xbox360GamePad or set of keys.

Conclusion

Now that we have multiple PlayerBall instances, we have a game that is playable, but it's missing scoring and game rules. The next tutorial adds the ability to score goals.

Introduction

Currently the game is playable, but scoring a goal results in the puck moving off-screen. We'll add logic and data to detect when a goal is scored by resetting the position of all objects and assigning points.

Creating the Goal Region Rectangles

Conceptually detecting a goal is simple - whenever the Puck collides with a certain area then a goal has been scored. The first step is to define the goal area. First we'll create a Goal entity:

1. Select the Quick Actions tab

2. Click the Add Entity button

3. Name the entity Goal

4. Select the AxisAlignedRectangle option under Collisions

5. Click OK

The default rectangle size for a Goal is too small, so we should make it bigger:

1. Select the AxisAlignedRectangleInstance in the Goal entity

2. Click the Variables tab

3. Change Height to 200

Just like before, we'll also add a list of goals in our GameScreen:

1. Select the Goal entity

2. Select the Quick Actions tab

3. Click the Add Goal List to GameScreen button

Next we'll add two goal rectangles to the GameScreen. Instead of using the Quick Actions tab, we'll show an alternative method here by drag+dropping the Goal entity onto GameScreen. Do this twice, changing the name of the first to LeftGoal and the second to RightGoal:

Why do goal names matter? In an earlier tutorial we created the wall collision and named them sequentially (Wall1, Wall2, etc). However, the goals are slightly different - we will be checking which goal we collided with in code to determine whether the left or right team should earn a point. Setting clear names makes it easier to keep track of which goal is on each side.

Next, modify the goals values as follows: LeftGoal:

• X = -410

RightGoal:

• X = 410

Keeping the PlayerBall Instances in the game

If you tried playing the game, you may have noticed that the PlayerBall instances can leave the screen by passing through the goals. To fix this we can create another CollisionRelationship between the PlayerList and GoalList:

1. Expand the GameScreen's Objects folder

2. Drag+drop the PlayerBallList onto the GoalList object

3. Select the new PlayerBallVsGoal collision relationship

4. Click the Collision tab

5. Change the Collision Physics to Bounce Collision

6. Set the PlayerBall Mass to 0

If you run the game, you can no longer leave the play area with either PlayerBall.

Detecting Goals

Now that we have all of our data and object instances set up, we can write code to detect if a goal has occurred. First we'll need two variables to keep track of score. Add this code to GameScreen.cs at class scope (outside of any methods):

 int player1Score = 0;
 int player2Score = 0;

Now we'll create another collision relationship, but this time we won't use any physics. Instead, this will be an event only collision relationship. This means that when the relationship detects a collision, it raises an event (call a function) which allows us to perform custom logic such as increasing score and resetting the game. First we'll create a collision relationship:

1. Expand the GameScreen's Objects folder

2. Drag+drop the PuckList object onto the GoalList

Now we'll create an event, which is a function that is automatically called whenever the collision occurs:

1. Select the new PuckVsGoal collision relationship

2. Select the Collision tab

3. Scroll to the bottom and click the Add Event button

4. Accept the defaults and click OK

When an event is added, Glue automatically adds a new file to contain events called GameScreen.Events.cs. We can find the new event there. You need to expand the GameScreen.cs in Visual Studio's Solution Explorer to see this file.

We can check which Goal collided with the Puck in the code and perform different logic. We can Modify the OnPuckVsGoalCollided method and add a new ReactToNewScore method to the GameScreen.Event.cs file as shown in the following snippet:

public partial class GameScreen
{
    void OnPuckVsGoalCollided (Entities.Puck puck, Entities.Goal goal)
    {
        if (goal == LeftGoal)
        {
            player2Score++;
            ReactToNewScore();
        }
        else if (goal == RightGoal)
        {
            player1Score++;
            ReactToNewScore();
        }
    }
    
    private void ReactToNewScore()
    {
        PlayerBall1.X = -180;
        PlayerBall1.Y = 0;
        PlayerBall1.Velocity = Microsoft.Xna.Framework.Vector3.Zero;
        PlayerBall1.Acceleration = Microsoft.Xna.Framework.Vector3.Zero;

        PlayerBall2.X = 180;
        PlayerBall2.Y = 0;
        PlayerBall2.Velocity = Microsoft.Xna.Framework.Vector3.Zero;
        PlayerBall2.Acceleration = Microsoft.Xna.Framework.Vector3.Zero;

        Puck1.X = 0;
        Puck1.Y = 0;
        Puck1.Velocity = Microsoft.Xna.Framework.Vector3.Zero;
    }
}

Whenever a Puck collides with either goal, we call ReactToNewScore, which resets the player and puck positions and velocities back to their starting states. Notice that the code in GameScreen.Event.cs has access to the player1Score and player2Score variables. This is because the GameScreen is one class split into multiple files using the partial keyword. Therefore, anything you define in Glue or GameScreen.cs is available in GameScreen.Event.cs.

Conclusion

If you've made it this far, congratulations! You now have a fully-playable game...at least, to the point where you can play with friends. There's still a few more things we'll do to improve the design and add polish. The next tutorial covers adding a HUD to display player score.

Introduction

This tutorial covers how to create an Entity, which is the FRB term for a "game object". Examples of entities include:

• Game characters (like Mario)

• Projectiles (like a bullet)

• Power-up (like a health pickup)

Our first entity is called "PlayerBall".

Creating PlayerBall

To create an Entity:

1. Click the Add Entity in the Quick Actions tab...

   ...or right-click on the Entities folder and select Add Entity
2. Enter the name PlayerBall

3. Check the Circle checkbox under the Collisions category. This adds a circle object to the PlayerBall entity, which we'll use to test if it is touching the walls, goals, or other ball instances.

4. Notice that the ICollidable checkbox is checked - we'll cover this in a later tutorial. We'll leave it checked for now.

5. Notice that Create Factory is also checked. This option simplifies the creation of additional entities in code. We'll leave this checked as well.

6. Click OK

Our entity is now created with a Circle named CircleInstance under its Objects folder, as shown in the following image:

Alternative Approach - Adding a Circle

The previous section showed how to create an entity and add a Circle to the entity at the same time. Objects can be added after an entity is created as well. Note, the following steps are only shown for example, and do not need to be followed if you performed the previous steps. To add a Circle to an already-created entity:

1. Click the Add Object quick action...

   ...or right-click on Objects and select Add Object
2. Select the FlatRedBall Or Custom Type option

3. Select Circle in the list

4. Enter the name CircleInstance and click OK

Creating an Entity - the Code and Data

When a new Entity or Screen is created, a number of files are created:

• <EntityName>.glej or <ScreenName>.glsj

• <EntityName>.cs

• <EntityName>.Generated.cs

For example, the PlayerBall entity creates PlayerBall.glej, PlayerBall.cs, and PlayerBall.Generated.cs. These files can be viewed by right-clicking on the entity and selecting View in Explorer.

PlayerBall.glej

The PlayerBall.glej file is a JSON file which stores all of the information for the PlayerBall. This file does not need to be edited manually in most cases since the FlatRedBall Editor provides controls for making changes. Of course, the file can be edited by hand, and any changes are automatically reloaded by the FlatRedBall Editor if the file changes.

This file should be included in version control so that the project can be opened and re-generated on other computers.

PlayerBall.cs

The PlayerBall.cs is a code file which contains custom logic. By default this file contains only empty functions, but these can be filled in to customize initialization, every-frame logic, destruction, and content loading. This file is often referred to as the custom code file. In a typical game, a lot of your game's code is written in screen and entity custom code files.

PlayerBall.Generated.cs

PlayerBall.Generated.cs is a file which is generated by the FlatRedBall Editor mirroring the contents of the JSON (glej) file. Any changes to the JSON file, whether through the FlatRedBall Editor or by manually editing the contents of the JSON file, results in the PlayerBall.Generated.cs being re-generated.

The contents of this file are re-generated if any change is made to the Player entity, or if the FlatRedBall editor is re-opened. In other words, generated files are re-generated by the FRB Editor, so any changes made directly to the generated file should be considered temporary. In practice this file can be used to help debug, or to perform temporary tests, but final changes should either be made in the JSON file or in custom code.

Generated files can optionally be included in version control. By default FlatRedBall excludes generated files since they can be re-generated from the corresponding JSON files. Of course, if the project is cloned to a new computer then the project must be opened in the FlatRedBall Editor to re-create all generated files. If this is problematic (such as if the development team includes individuals who do not open the FlatRedBall Editor), then the generated code files can be added to version control. Keep in mind that doing so may result in a larger version history.

Conclusion

At this point our project has a PlayerBall Entity which is ready to be used in a game. Of course, we haven't yet created an instance of the newly-created Entity, so if you run your game you won't see it (yet). The next tutorial creates a Screen which contains our PlayerBall Entity.

The following tutorials provide an introduction to working with Platformers in the FlatRedBall Editor.

Introduction

This tutorial is an introduction to making games with FlatRedBall. It covers using the FlatRedBall Editor and writing code in C#. The FlatRedBall Editor is a program which helps with the creation and organization of game projects. We'll be exploring its features by creating a game called Beefball - a multiplayer competitive game similar to air hockey. When finished our game will have two circles, each movable with either the keyboard or an gamepad, and a smaller circle which each player can use to earn points.

Opening FlatRedBall

The first step in any game project is to open up the FlatRedBall Editor. If you've downloaded and unzipped the FRBDK.zip file, then you should already have this on your machine. Unzip the file, and double-click Run FlatRedBall.bat.

If you haven't yet downloaded the FRBDK.zip file, you can get it from the Download page.

Creating a new project

Once you open the editor, you can create a new project. To create a new Project:

1. Select File -> New Project
2. Enter Beefball for the Project Name.

3. Leave Desktop GL as the platform. Our game targets this platform because it is easy to debug. Creating the project for a desktop platform is recommended even if the game is intended to run on non-desktop platforms (such as Android). Additional platforms can be added at any time.

4. Uncheck Open New Project Wizard. We'll make Beefball "from scratch".
5. (Optional) Change the location of the project. By default the project is created in Documents\FlatRedBallProjects.

6. Click the Create Project! button to create the project.

The latest FlatRedBall template is downloaded, so your project runs against the newest version available. Now that you've made a project, FlatRedBall remembers this and automatically open it for you next time it is started.

FlatRedBall Editor and Visual Studio

FlatRedBall Editor is a tool meant to work hand-in-hand with Visual Studio. It is not a replacement for Visual Studio, meaning you will be doing work in both Visual Studio and the editor. It is quite common to develop FlatRedBall games with both Visual Studio and the FRB Editor open at the same time.

Opening and Running your project

FlatRedBall projects automatically create a Visual Studio project too. To open the project in Visual Studio, click the Visual Studio icon as show in the following image:

FlatRedBall uses the windows default file association for your .sln file. If you would like to change this association, you can right-click on the .sln file in Windows Explorer to change the default file association.

You can also open the project in visual studio by opening the .sln file. The project folder can be opened by clicking the folder icon in the task bar. This opens the location of the .csproj file, which is one folder below the .sln file. The following animation shows how to navigate to the solution:

When you double-click the .sln file you may see a window like this:

If so you should select the version of Visual Studio that is compatible with the type of project you are running. At the time of this writing, Visual Studio 2022 Community is the most common version to use with FlatRedBall. Once Visual Studio is open, you can run your project by pressing the "start" button, or by pressing F5.

Your game should run if all prerequisites have been properly installed. You should see a blank game

Conclusion

That was easy! So far you have a fully-functional game using FlatRedBall. The next tutorial covers making our first Entity.

Introduction

This tutorial provides a set of steps for creating an entity with platformer behavior.

Using the Wizard

The FlatRedBall Editor provides a quick setup for creating a platformer project. To create a platformer project:

1. Launch the FlatRedBall Editor

2. Create a new project

3. Wait for the project to finish loading

4. Wait for the Wizard window to appear

5. Select the Platformer project option
6. Wait for the wizard to finish processing

7. Run the game from either Visual Studio or the FlatRedBall Editor

Creating a GameScreen

Although this tutorial is focused on creating a platformer entity, we will first add a GameScreen. Creating a GameScreen first makes it much easier to add an entity after. Most FlatRedBall projects have a GameScreen - it's a standard screen created by the wizard, so it's best to follow this naming convention in your own projects even if you aren't using the wizard.

Note that you may already have a GameScreen in your project. If so, you can skip this section. To add a GameScreen:

1. Select the Quick Actions

2. Click the Add Screen/Level button

3. Leave the default GameScreen name

4. Check both the Add SolidCollision ShapeCollection and Add CloudCollision ShapeCollection options

5. Click OK

We will return to the GameScreen in future tutorials, but having one created before we create entities will speed up the process.

Creating a Player Entity

The Player entity is our entity that will be controlled and have platformer physics. Regardless of the genre, most FlatRedBall games have a Player entity. It's a convention that your games should follow, just like having a GameScreen.

To create an entity with platformer behavior:

1. Select the Quick Actions tab in Glue

2. Click the Add Entity button

3. Enter Player as the name for the entity

4. Check the AxisAlignedRectangle checkbox - platformer entities perform collision against their environment

5. Verify that the ICollidable checkbox is checked - this enables collision which is necessary for platforming physics

6. Change the Input Movement Type to Platformer

7. Leave the Tiled options selected to automatically create a list for this new entity in GameScreen

8. Click OK

This will create a new platformer entity with a rich set of default functionality. We can verify that the entity is marked as a platformer by checking its Entity Input Movement tab to verify that it is marked as a platformer and that it has two movement types:

• Ground

• Air

Adding a Player to the GameScreen

Now that we have the Player entity set up with platfomer control values, we can add it to our GameScreen by drag+dropping the Player onto the GameScreen node. We should already have a PlayerList in our GameScreen so the newly-added object will be inside of that list after the drag+drop.

Note that we add a Player to the GameScreen before creating any Levels. We add the Player to the GameScreen so that we have a player in every Level (screens which inherit from GameScreen).

Adding a CameraControllingEntity Instance (Optional)

To create a CameraControllingEntity:

1. Select GameScreen

2. Select the Quick Actions tab

3. Click the Add Object to GameScreen button

4. Find and select Camera Controlling Entity

5. Click OK

We want to set up the newly created CameraControllingEntityInstance to track our player as it moves around in the map. To do this:

1. Select CameraControllingEntityInstance under GameScreen/Objects

2. Select the Variables tab on the right

3. Set the variable Targets to PlayerList

4. Set the variable Map to Map

Adding a Level

Before we can run our game, we also need to add a Level. Typically, the GameScreen includes objects, files, and objects which are common to all screens (such as a Player), while each level includes objects and logic which are level-specific (such as the TMX).

To add a level:

1. Select the Quick Actions tab

2. Click the Add Screen/Level button

3. Leave all defaults and click OK
4. After clicking OK, another popup appears with options for the level tile map (TMX). Leave all defaults and click OK

Your project should now have a Screen named Level1. This is marked as the startup screen (it has the play icon and appears in the startup dropdown).

Conclusion

If we run our game now, we'll see the entity functional - at least, it seems to fall with gravity. In the next tutorial we'll add collision and controls using our entity.

Introduction

FlatRedBall is a set of technology for creating games on a variety of platforms. FlatRedBall focuses primarily on creating 2D games, although it does provide 3D support and full access to the underlying XNA-like system (MonoGame, FNA, Kni) for creating full 3D games.

FlatRedBall has been used to create dozens of commercial games on a variety of platforms. FlatRedBall's ultimate goal is to boost your productivity as a game developer and to help you ship your game on your target platform.

FlatRedBall Editor

The FlatRedBall Editor is a visual tool for creating and organizing screens, entities, and files.

Project Setup Wizard

Use the wizard to get your game up and running in seconds.

Tiled Integration

Tiled maps can be drag+dropped into the FlatRedBall Editor and loaded with no extra code. Use Tiled to define visuals, collision, and add entity instances.

Gum UI Integration

FlatRedBall provides full integration with the Gum tool. Gum projects are added to your project and loaded by generated code, enabling the creation of UI from the very first click.

Game Live Edit

Run your game in edit mode to make changes in real time.

Hot Reload Files

Make changes to files such as Tiled (.tmx), Textures (.png), and spreadsheet (.csv) files and see the changes update in realtime.

Aseprite Integration

Native support for .aseprite files enables creating animated characters by drag+dropping files into the FlatRedBall Editor.

Clean Design and Theme support

FlatRedBall Editor supports customizing accent colors and changing between light and dark mode.

Customizable Rendering Using Shaders

Add built-in effects like Bloom and CRT with a few clicks, or create your own fully customizable shaders.

Platformer Controls and Physics

Creating a platformer has never been easier. Mark your entity as a Platformer or use the new project wizard to get production quality platformer physics and movement.

Built-in Damage System

The flexible damage system simplifies and standardizes dealing damage and reacting to receiving damage.

Pathfinding

Create node networks from Tiled maps or in code to navigate maps.

AnimationEditor Integration

Use the AnimationEditor to define animations for your characters using individual files or sprite sheets. Preview animations, adjust timing, and add shapes for collision or defining key positions.

FlatRedBall.Forms

FlatRedBall.Forms is a flexible UI system similar to WPF and MAUI. It is fully integrated with Gum and has MVVM support.

SkiaSharp Integration

Use SkiaSharp to render GPU-accelerated vector graphics in your game. Perform layout purely in code or use Gum.

Spine Integration

Use all features in the Spine tool including defining skeletons, animations, and events.

Spine files can be dropped in to your project and loaded with no code. Play animations at runtime in response to input or game events.

Tweening (Interpolation)

Use built-in interpolation systems to move, resize, rotate, and color objects over time.

Physics

Physics engine handles collision between circles, rectangles, polygons, and lines.

Collision Relationships

Define collision relationships in UI or code to add physics, damage dealing, and custom events.

Display Settings

Set your initial game's resolution, whether it supports resizing, aspect ratio, and more.

Camera Controlling Entity

The camera controlling entity can follow one or more targets, supports zooming, provides customizable tweening, and respects map bounds.

Realtime File Reference Tracking

Turn difficult-to-find runtime errors into clear in-editor errors the moment a file is changed or removed.

MonoGame/FNA and NAudio Music

MonoGame and FNA Song support included out of the box. For more flexibility song files can be loaded using NAudio.

CSV and Open Office/Libre Office Integration

Use CSV files or open office spreadsheet files to define your game data. FlatRedBall automatically generates the classes for loading your data and deserializes the files in geneated code.

Flexible Input

FRB input supports mouse, keyboard, touchscreen, and a variety of gamepads (Xbox, Switch, PlayStation, and PC) including direct and abstract access through a variety of interfaces.

Localization Support

Add multiple languages to your game using a simple spreadsheet. Localization is automatically loaded and can be accessed through a LocalizationManager static class. Include multiple pages per string ID and add custom columns for your game's specific needs.

Multiple Platforms

Target multiple platforms with the same code and content. FRB games can run on:

• Windows

• Browser

• Mac

• Linux

• Android

• iOS

• Switch/Xbox using FNA AOT

• PS4/PS5 using MonoGame AOT (coming soon)

Full .NET C# (not scripted)

FlatRedBall projects are regular .NET projects with full access to modern C# syntax, the full .NET library, and NuGet packages. FlatRedBall Projects are regular Visual Studio project, enabling you to use your favorite IDE and debugger.

Open Source

FlatRedBall is fully open source using the MIT License. It is built using libraries which themselves are also open source. You can build your games without the worry of future inconveniences caused by license changes.

All Data is Text

All data created by FlatRedBall is in text format. The FlatRedBall Editor saves .json files and generates pure C# code files. Never worry about binary file conflicts wiping out your work again.

XNA-Like Foundation

FlatRedBall was built in the early days of XNA and has continued to grow, adding support for MonoGame and FNA. Your FlatRedBall game is a MonoGame/FNA game, and the full flexibility of these libraries is available to you.

Async Programming

FlatRedBall provides a syncrhonization context and multiple methods returning Tasks to simplify async programming.

Introduction

Now that we have our PlayerBall movement working, we'll add a Puck Entity which the user can hit around. You'll find that the Puck is very similar to the PlayerBall.

Creating a Puck Entity

To create a Puck Entity:

1. Click on the Quick Actions tab

2. Click the Add Entity button

3. Name the Entity Puck

4. Check the Circle check box under Collisions

5. Verify that ICollidable is checked (it should be checked automatically when Circle is checked)
6. Click OK

The Puck entity should appear in the FlatRedBall Editor.

Differentiating the Puck

Currently our Puck and PlayerBall both have Circle bodies, and by default the Circles have the same size and color. To differentiate the Puck from the PlayerBall:

1. Expand the Puck entity

2. Click on the CircleInstance object under the Puck Entity

3. Click the Variables tab

4. Find the Color variable

5. Change the value to Red using the drop-down

6. Change the Radius value to 6

Computer settings matter: If your computer is set up so the decimal separator is the comma ',' instead of the period '.' then you should enter values using the ',' character. Unlike C# code, Glue obeys your computer's language settings.

PuckList in GameScreen

By default the FlatRedBall Editor adds lists of newly-created entities to the GameScreen. Therefore, you should already have a PuckList in your GameScreen.

If you unchecked the option, or if you would like to know how to manually add a PuckList to your GameScreen, the following section shows how to add a list. This is not necessary if you kept the defaults.

(Optional) Adding a PuckList Manually

1. Click the Puck entity

2. Select the Quick Actions tab

3. Click the Add Puck List to GameScreen button

Adding a Puck Instance

1. Select the Puck entity

2. Click the Add Puck Instance to GameScreen button

Now the GameScreen has a list and a single Puck.

Positioning your objects

If you run your game you'll notice that the PlayerBallInstance and PuckInstance are both at the center of the Screen. Let's reposition the PlayerBall1:

1. Select the PlayerBall1 object under your GameScreen

2. Change the X value to -180

Puck Collision

Now that we have a Puck in our game, we need to create two collision relationships:

1. Puck vs Walls - this prevents the Puck from moving through the walls.

2. Puck vs PlayerBall - this allows the PlayerBall to "hit" the puck to try to score a goal. We haven't yet created the handling of goals, but this is the first step towards implementing that feature.

We create these two collision relationships just like the previous PlayerListVsWall collision relationship. To create a relationship between the PuckList and Wall:

1. Expand GameScreen's Objects folder in Glue

2. Drag+drop the PuckList onto the Walls object

3. Select the new PuckVsWalls collision relationship

4. Select the Collisions tab

5. Set the Collision Physics to Bounce

6. Change the Puck Mass to 0

7. Optionally adjust the Elasticity value

To create a relationship between the PuckList and PlayerBallList:

1. Expand GameScreen's Objects folder in Glue

2. Drag+drop the PlayerBallList onto the PuckList object

3. Select the new PlayerBallVsPuck collision relationship

4. Select the Collisions tab

5. Set the Collision Physics to Bounce

6. Change the Puck Mass to 0.3 - this makes it 30% the mass of the PlayerBall

7. Optionally adjust the Elasticity value

Notice that the mass variables for PlayerInstance vs. PuckInstance differ compared to wall collision. The PuckInstance is given a mass of .3 relative to a mass of 1 for the PlayerInstance, resulting in the PuckInstance behaving as if it has 30% of the mass of the PlayerInstance. If you run the game, you should be able to hit the Puck around the level.

Adding Drag

Currently the Puck moves indefinitely after being hit. We'll assign the Drag value to the Puck just like we did to PlayerBall:

1. Select the Puck Entity in Glue

2. Select the Variables tab

3. Click the Add New Variable button

4. Select the Expose an existing variable option

5. Select the value Drag

6. Enter a value of 0.4 for Drag

Now the Puck slows down over time just like the PlayerBall.

FlatRedBall makes platformer game creation easy. This section includes tutorials covering various platformer topics from beginner to expert.

Introduction

Screens and Entities are two common FlatRedBall concepts. A Screen represents a container for game content and other Entities. Screens define the flow of your game. Often game developers create many screens up-front to help think through a game's structure. Here are some examples of Screens in a typical game:

• Game play Screen (like the playing Screen in Pong). This is usually called "GameScreen"

• Splash Screen (like a FlatRedBall logo displaying splash Screen)

• Main menu Screen

Creating a Screen

As you work with Screens you will find that they are very similar to Entities. To create a Screen:

1. Click on the Screens folder and select the Add Screen quick action...

   ...or right-click on the Screens folder and select Add Screen
2. Uncheck Add Map LayeredTileMap option - Beefball doesn't use Tiled maps

3. Accept the other defaults by clicking OK.

Notice that FlatRedBall suggests the name GameScreen for your screen. Recommended practice is to always have the screen where your game takes place called GameScreen. If your game has multiple levels, each level would inherit from GameScreen. Since Beefball does not have multiple levels, we only create GameScreen.

PlayerBallList in GameScreen

By default, your GameScreen now has a PlayerBallList - this is a list which will contain all PlayerBall instances in your GameScreen.

If you unchecked the Add Lists for Entities option, or if you would like to know how to create lists manually, follow these steps:

1. Select the PlayerBall entity

2. Click the Quick Actions tab

3. Click the Add PlayerBall List to GameScreen button

The PlayerBallList object will contain all of the PlayerBalls we plan on adding later. Our game is a two-player game, so it will eventually contain two PlayerBall instances. The PlayerBallList object will be used to define collision relationships in a later tutorial. Collision relationships define which objects can collide with each other (such as players vs the walls) and what to do when they collide (such as performing bounce physics).

Adding an Entity Instance to GameScreen

Once you have at least one Screen in your game (GameScreen), you can add Entity instances to that Screen. Entities can be added through the editor or through game code. The editor provides a number of ways to add an entity:

• Drag+drop an entity on a screen to add an instance...

• ... or add an instance to the GameScreen by selecting PlayerBall and clicking the Add PlayerBall Instance to GameScreen quick action. Note that this option will only exist if you have a Screen called GameScreen...
• ... or add an object to a screen by right-clicking on the GameScreen's Objects folder:

  • Right-click on your GameScreen's Objects folder

  • Select Add Object

  • Select Entity as the object type

  • Select PlayerBall as the type. The name will automatically be changed to PlayerBallInstance

  • Click OK

Running your Game

Now that you have a PlayerBall instance in your GameScreen, you can run the game to see it. You can run the game through either the FlatRedBall Editor or Visual Studio.

• To run the game through the editor, click the Play button in the toobar at the top
• To run the game through Visual Studio, click the Visual Studio icon to open the game in Visual Studio and run it like any other desktop project

Your game should now be open in Visual Studio.

Once the game runs, you should see a circle (the PlayerBall1 instance) in your Screen.

FlatRedBall Coordinates

Now that we have an object in our screen we can take a moment to understand how the coordinates in FlatRedBall work. By default, our entity exists at X=0 and Y=0. We can observe this by selecting the PlayerBall1 instance and looking at its Variables tab.

By default the center of the screen is at the origin (0,0), and objects are positioned by their center, so the PlayerBall appears at the center of the screen.

For more information on how to control the screen's resolution and world units, see the FlatRedBall Resolution section.

For more information on how to control the Camera to change the center of the screen, see the Camera code reference.

Conclusion

To recap we now have an Entity called PlayerBall which has a Circle. We've also created a GameScreen which contains an instance of our PlayerBall. If we run our game, it shows a white circle (our PlayerBall instance).

We're now ready to start adding some code to our project. The next tutorial covers controlling your Entity's movement.

Introduction

Note - if you created your Platformer project using the wizard, feel free to skip this tutorial. This tutorial is only needed if you are manually creating your game.

Adding a Collision Relationship

The previous tutorial created a GameScreen which contains two TileShapeCollections:

• SolidCollision

• CloudCollision

By default, each is associated with a standard tile from the tileset included in our Level1Map.tmx. However, these collisions do not have any effect on our player since we haven't told the player to collide with them.

To set up collision between our PlayerList and SolidCollision:

1. Expand GameScreen Objects

2. Drag+drop the PlayerList onto the SolidCollision to create a relationship

Since our Player is marked as a Platformer entity, the FlatRedBall editor assumes that the PlayerVsSolidCollision relationship should use platformer physics. You can verify that this is the case by selecting the PlayerVsSolidCollision object and clicking on the Collision tab.

Now the player will collide with the level.

Controlling the Entity with Input

By default, the platformer entity already supports a default set of controls. To see this, select the Player entity, then select the Entity Input Movement tab.

By default, the platformer will be controllable with a plugged-in Xbox Gamepad. If no Gamepad is detected, then the entity can be controlled with WASD and Space.

Note - the animation above shows a game that is using the CameraControllingEntity to position the camera in the center of the map. If you are not using the CameraControllingEntity, then you can manually position the camera in your GameScreen by changing the Camera.Main.X and Camera.Main.Y variables in CustomInitialize. Also, note that the Player is inside of the map. You can modify the player's starting X and Y values either in code or by selecting the Player1 object in GameScreen and changing its X and Y values.

If you want to override which input is used to move the player, you can change the controls in code. For example, to change the character to jump with the Enter key and to move with the arrow keys:

1. Go to GameScreen.cs

2. Modify the CustomInitialize function to contain the following input assignment code:

The code above added keyboard controls so that the Player can be moved horizontally with the Left and Right arrow keys and jumps using the Enter button.

Conclusion

Now our platformer character reacts to input and collides with the environment. We can change the environment by opening Level1Map at any time and painting new tiles. The next tutorial takes a deeper look at the control values.

Introduction

This tutorial covers creating a HUD object which displays the scores of each player.

Creating a ScoreHud Entity

First we'll create an Entity to store all of our scoring information. We could place all of our HUD objects directly in the Screen, but this approach can result in a large number of objects in the GameScreen, making it difficult to maintain. We'll create a "Hud" entity to keep all HUD objects organized. To do this:

1. Select the Quick Actions tab

2. Click the Add Entity button

3. Enter the name ScoreHud

4. Click OK

Creating the ScoreHud Text objects

For the ScoreHud we'll define the Text objects in Glue (just like we defined the body of the Puck in Glue). To do this:

1. Select ScoreHud

2. Select the Quick Actions tab

3. Click the Add Object to ScoreHud

4. Select Text as the type

5. Enter the name Team1Score

6. Click OK
7. Repeat the steps above to create another Text object called Team2Score

8. Repeat the steps above to create another Text object called Team1ScoreLabel

9. Repeat the steps above to create another Text object called Team2ScoreLabel

You should now have 4 Text objects:

Now we'll change the following variables on the Text objects in Glue. Select the following Text objects and set the variables as defined below: Team1Score

• DisplayText = "99"

• X = -150

• Y = 270

Team2Score

• DisplayText = "99"

• X = 180

• Y = 270

Team1ScoreLabel

• DisplayText = "Team 1:"

• X = -205

• Y = 270

Team2ScoreLabel

• DisplayText = "Team 2:"

• X = 124

• Y = 270

To add the ScoreHud to the GameScreen:

1. Select the ScoreHud

2. Select the Quick Actions tab

3. Click the Add ScoreHud Instance to GameScreen button

You should now see everything showing up correctly in your game

Conclusion

Now we have a score HUD that shows up when the game plays, but it doesn't react to scored goals. The next tutorial adds the necessary logic to have it react to scored goals.

Introduction

This page covers all control values available in a platformer entity. It also provides ways to implement common functionality such as ice physics and under-water levels.

Modifying Control Values

If you created your game using the wizard, then the Player entity already has a set of default values. If you manually created your Player entity, then it should also have a set of default control variables.

These values serve as a starting point for platformers - they can be tuned to provide a custom feel to platformer entities. The platformer control values can be viewed and edited by selecting the Player entity and clicking on the Entity Input Movement tab.

Max Speed

This is the maximum speed (maximum absolute horizontal velocity) that the character can move through input. Note that if using Immediate horizontal movement, then this is a hard value - not other forces can modify the character movement. For more information, see the next section. Increasing this value makes the character move more quickly, but doing so can make the game more difficult to control if the value is too large.

Immediate and Speed Up/Down

This value controls whether the character reaches maximum velocity immediately, or if it takes time for the character to speed up and slow down to the maximum velocity and back to standing still. Using Immediate increases the responsiveness of your game, and allows players to move very accurately. Examples of immediate-movement games include Mega Man and Castlevania.

The Speed Up/Down option results in the platformer entity accelerating to max speed and back down to a standstill over time, instead of immediately. This option creates more natural movement and requires more planning on the player's part (such as building up speed before a big jump). Examples of speed up/down movement include the Super Mario Bros. series and the Donkey Kong Country series.

Speed Up Time

The Speed Up Time value controls how many seconds are required for the platformer entity to reach max speed. This value is only available if using Speed Up/Down horizontal movement.

Increasing this value makes the character makes the platformer entity feel sluggish. Decreasing this value makes the platformer entity feel more responsive. A value of 0 is identical to using Immediate horizontal movement. A larger speed up time can also be used for different terrains and environments. For example, a larger value can make the ground feel more slippery (if the character is walking on ice). A larger value can also make the character seem heavier, or can be used to simulate under-water movement. A larger Speed Up Time can be used for air movement so that control is less precise when in the air.

Slow Down Time

The Slow Down Time value controls how many seconds it takes for the platformer entity to decelerate from full-speed to a standstill. A larger value can make the ground seem more slippery, especially when paired with a larger Speed Up Time. Usually Slow Down Time should not be larger than Speed Up Time. If the two values are similar, then this makes the ground feel slippery. The following table shows common combinations of Speed Up Time and Slow Down Time. The values High, Medium, and Low do not have fixed meaning, but a typical setup may include these values:

• Low .15 seconds

• Medium .4 seconds

• High .8 seconds

Of course, you should modify values to achieve the desired movement for your specific game.

Jump Speed

This value controls the velocity of the platformer entity at the moment when jumping off the ground, or when initiating a double-jump. Larger values allow the character to jump higher. This value is typically larger than Max Speed, but the exact value often requires multiple iterations to get the right feel.

A platformer entity's jump height is also impacted by Gravity, so both Jump Speed and Gravity may need to be modified together. A low jump speed can be used for double-jumps, or for swimming when under water. A large jump speed can be used for characters who can jump higher. The Jump Speed value on Air movement can control whether the character can perform a double jump. By default, this value is 0 which means that the character cannot double-jump. Setting a value greater than 0 means a character can double jump. This topic will be covered in more detail in the following tutorial.

Hold to Jump Higher

If Hold to Jump Higher is checked, then the player will be able to hold the jump button to cause the platformer character to jump higher. This allows players to perform shorter hops when desired, and longer jumps to clear large obstacles. The larger this value, the longer the player can hold the button to jump higher.

Implementation Details

Variable-height jumping can be implemented a number of different ways. The platformer entity implements variable height jumping by turning off gravity while the player is holding the button down. This approach has the following characteristics:

• Jumps feel responsive and immediate - the platformer entity does not delay jumping while the player is holding the button down. Instead, jump height is determined by not applying acceleration immediately.

• Jump motion may not appear totally fluid, especially in high-gravity games.

The following image shows two jump arcs. The first is the movement of the character when the button is held, the second is without:

Although it may be difficult to see, the entity moves in a straight line on the first part of the first jump, rather than moving in an arc. This is the result of gravity being turned off while the button is held. If we color the first part red, the linear movement is a little easier to see:

Max Jump Hold Time

The Max Jump Hold Time value sets the maximum amount of time that the player can hold the jump button to extend the platformer entity's jump. A large value gives the player the option to hold the button to jump higher. A small value results in the max and min jump heights not differing by much. A very large value may result in the player appearing to "float" while jumping, so keep this in mind when setting large values (such as over 1 second). A large Max Jump Hold Time may be used with a small Max Jump Speed to create swimming controls.

Can Fall Through Clouds

This value controls whether the platformer entity can press the down arrow + jump to fall down through cloud collision. If this value is false, then cloud collisions can only be jumped up through, but the player cannot fall down through them.

Cloud Platform Thickness

This is the distance to fall when pressing down + jump on a cloud platform before testing cloud collision again. When falling through cloud collision, collision against clouds is temporarily disabled until the user has fallen far enough. Once that has happened, cloud collision is re-enabled. This value should be roughly the thickness of cloud collision objects plus the height of the player collision. For example, if the tile height is 16 and the player's collision height is 32, then the Cloud Platform Thickness value should be set to 48. If a TileShapeCollection's UpdateShapesForCloudCollision method is called, then only half of the shape will be used for collision, so only half of the tile height needs to be considered when determining the Cloud Platform Thickness.

Gravity

Gravity controls how fast a character accelerates downward when falling. This value is assigned to the PositionedObject.YAcceleration property. Increasing this value makes the entity fall more quickly, while a smaller value makes the entity fall slower, or seem to float.

Max Falling Speed

Max Falling Speed sets a limit to the platformer entity's y velocity. A smaller max falling speed results in the entity falling more slowly, even if Gravity is large. A smaller max falling speed can be used to slow a player's fall down with special abilities such as the raccoon tail in Super Mario Bros 3.

A smaller Max Falling Speed and low Gravity can be used to implement water physics such as the water levels in Donkey Kong Country.

Introduction

At this point Beefball is a fully-playable game, but we'll be adding one final feature: dashing. This provides deeper gameplay that rewards skill and adds an element of anticipation and excitement.

Adding Dashing

A dash gives the player a burst of speed in the current direction that the player is pointing. The dash can be used to hit other players, shoot the puck, or dive in front of the puck to block a goal. To add a dash, modify CustomActivity in PlayerBall.cs as follows:

Next, implement DashActivity in PlayerBall.cs:

If you try to build your game, you'll notice that the variable DashSpeed is undefined. This is a variable that should be defined in the FRB Editor so that it can be tuned easily:

1. Click on PlayerBall

2. Select the Variables tab

3. Click the Add New Variable button

4. Verify that float is selected

5. Enter the name DashSpeed

6. Click OK

7. Enter a value of 600 for DashSpeed

Your game should build and dashing should be fully functional.

Limiting Dash Frequency

Currently the player can dash indefinitely. We'll modify the dash so it has a cool-down after it's used. We'll need a variable to keep track of when the dash was first used, and compare against that variable to check if the user can dash again. First, add the following variables to your PlayerBall.cs at class scope (make it a field):

Next, add a check for the last dash time and a set to lastDashTime in DashActivity in PlayerBall.cs. Your entire method should look like:

Just like before, we need to create a DashFrequency variable in the FRB Editor:

1. Click on PlayerBall

2. Select the Variables tab

3. Click the Add New Variable button

4. Verify that float is selected

5. Enter the name DashFrequency

6. Click OK

7. Enter a value of 2 for DashFrequency to indicate a 2 second frequency

Now the player can only dash once every two seconds.

Why did we create DashFrequency and DashSpeed variables in the FRB Editor, but lastTimeDashed in Visual Studio? You may have noticed that we defined some of our variables (like DashFrequency and DashSpeed) in the FRB Editor, but we defined lastTimeDashed in Visual Studio. When working in the FRB Editor it is important to distinguish between "data" and "logic". Variables considered data are created in the FRB Editor so that they can be easily modified. Game development is an iterative process, and even the most experienced game designers make changes to their game throughout development. Creating variables in the FRB Editor makes changing variables easy, and communicates to other developers that these variables should be tuned. The lastTimeDashed variable, on the other hand, exists solely to support the logic of limiting dashing. The actual value of lastTimeDashed changes many times as the game runs, and setting it through the FRB Editor either has no impact on the game or introduces an unintended bug of making dash not work (if the value is set to a large positive value).

Adding a Cooldown Indicator

Now that the player's dashing is limited, we need to add some visible indication of when another dash can occur. We'll do this by adding a second Circle to the PlayerBall which grows when the user has dashed, then disappear when the user can dash again. To do this:

1. Click on PlayerBall

2. Select the Quick Actions tab

3. Click Add Object to PlayerBall

4. Select Circle

5. Enter the name CooldownCircle

Defining States

Next we'll use States (something we haven't used yet) to define what the PlayerBall should look like when the cooldown first begins and when the cooldown ends. States have the following benefits:

1. They let you "code against concept, not content". In other words, you can define a state and use it in code, and later make changes to the state without having to modify any code. This is desirable because when you set the PlayerBall to a "Tired" state, your code shouldn't depend on anything except for the presence of a Tired state. Code should simply set the state to Tired, while the logic of Tired should be handled elsewhere.

2. States can interpolate from one to the other. In this case, we'll have the "Tired" state set the CooldownCircle to have a small radius, and the "Rested" will have a large circle. The end result is the CooldownCircle "grows" as the player's dash is recovering.

All states must be categorized, so the first step is to create a new category:

1. Right-click on the States item under PlayerBall and select Add State Category
2. Name the category DashCategory and click OK

Now the PlayerBall has a category named DashCategory.

Next we'll add states to the category:

1. Right-click on DashCategory

2. Select Add State
3. Enter the name Tired and click OK
4. Repeat the above steps to create a "Rested" state as well

As mentioned above, we'll want the CooldownCircle ball to grow (increase its Radius) to give the player an indication of how much time is left in the cooldown. To do this, we'll need to tunnel in to the CooldownCircle's Radius property:

1. Drag+drop the CooldownCircle object onto the Variables item

2. Select Radius for the Variable

3. Click OK

Categories must be told which variables to modify. By default, categories do not modify any variables.

To add a variable to a state, drag+drop the variable onto the category:

In this case, the only variable is the CooldownCircleRadius. Next let's define the two states:

1. Change Tired CooldownCircleRadius to 0.

2. Change Rested CooldownCircleRadius to 16. This should match the default radius for Body.

Using States in code

Now that our states are defined, let's use them in code. The simplest way to use states is to assign an entity's current state variable. FlatRedBall also provides functions for interpolating between states, which is the process of gradually changing from one state to another. We will write code to set the state to "Tired", then interpolate to rested over the course of two seconds - of course we'll use DashFrequency rather than hard-coding the value 2. To use these newly-created states, go to PlayerBall.cs and modify the DashActivity function as follows: To use the states, add the following two lines of code inside the if-statement in DashActivity in PlayerBall.cs:

Changing Player Colors

Lets change the color of the PlayerBall to help tell the two players apart. We will "tunnel" to the Body's Color so that it can be changed per player instance.

1. In FlatRedBall, expand the PlayerBall entity

2. Drag+drop the CircleInstance object onto the Variables folder

3. Select Color as the variable.

4. Click OK

5. Repeat for the CooldownCircle's Color

Now that the color variables is exposed, lets change one circle in GameScreen

1. In GameScreen, choose PlayerBallInstance2

2. Change both CircleInstanceColor and CooldownCircleColor custom variables to Cyan, or the color of your choosing.

3. Run the game!

You can now tell the difference between each player.

You just made a game!

If you've read this far, then you have officially just finished your first FlatRedBall game. Way to go! At this point, you can continue reading other tutorials, tweak this game more, or start on your own brand new game. Good luck!

Introduction

This walkthrough covers the concept of doors - objects which can move the player from one area on the map to another. Doors are often used to subdivide single levels, and are used in games like Super Mario World (pipes and doors) and Mega Man X (doors leading to bosses).

This walkthrough refers to the DoorsDemo as this demo and the demo.

Main Concepts

This walkthrough covers a number of concepts for using doors:

• The map is broken up into three sections which are all part of the same TMX file, but the Camera follows bounds defined by rectangles in the map

• Doors are entities which are added to the Tiled map

• The collision event between Player and Door instances is used to check if the player is pressing the up direction

• When transitioning (the screen is fading in and out), the code uses async/await to wait for the fading animations before allowing the Player to move

Tile Map CameraBoundsLayer

The Level1Map file is a TMX which contains three sections. These three sections are drawn just like normal tile maps, but they also contain a layer called CameraBoundsLayer. This layer, which is an Object Layer, contains three rectangles. Object layers with shapes can be used any time a shape is needed for game logic. Other uses besides camera bounds include defining large triggers (such as the goal in a level) or areas to destroy objects which fall off of a level (such as enemies falling into pits).

These three rectangles will be used to mark the bounds of the Camera when the Player is in one of the three areas of the map. These bounds will apply directly to the Camera, so they must not extend beyond tile edges. Every object layer with shapes is automatically loaded into a ShapeCollection contained in the map. The name of the ShapeCollection matches the name of the layer, so it can be retrieved with a First linq call on the map's ShapeCollections object, as shown in GameScreen's CustomInitialize.

The boundsShapeCollection field is used to position the player in the UpdateBoundsForPosition method. This takes a Vector3 defining a point inside the rectangle. The method then looks through all rectangles to find which rectangle contains the argument position, and adjusts the CameraEntityInstance's Map object.

Normally the Map object references an entire MapDrawableBatch (the runtime for TMX files), but in this case we replace it with an AxisAlignedRectangle. In either case, the CameraControllingEntityInstance will respect the bounds of the Map object it is assigned. We can observe this behavior by walking to the edge of the map. Notice that the Camera doesn't move further to the right even though it hasn't reached the edge of the TMX file.

Door Entity

The demo defines a Door entity in Glue which contains a Sprite and AxisAlignedRectangle. The Sprite is used to display the visual, and the AxisAlignedRectangle defines the collision area used to detect if the player can enter the door. The Door instances are created in our map which contains four Door tiles. The standard door tile is used to place doors in the map.

Its Type is set to Door, which results in instances of that tile automatically being replaced with Door entities.

The map contains four doors. Each door in the map has another door which marks where the Player should appear when travelling through the door. These pairs are identified by their names. The demo uses the convention of setting the Name of each pair of doors with the same letter. Specifically, the doors "A 1" and "A 2" are paired together and the doors "B 1" and "B 2" are paired together. This convention could support up to 26 pairs of doors if using only upper case, and more if using lower case and numbers, so it will work for even larger levels.

When collision occurs between a Door and Player and the up direction is pressed, the demo obtains the otherDoor to determine where to place the player. This code is used in the OnPlayerListVsDoorListCollisionOccurred method.

Player vs Door Collision

The logic for moving between doors is ultimately driven by the PlayerListVsDoorList collision relationship in Glue. This collision relationship raises an event OnPlayerListVsDoorListCollisionOccurred in GameScreen.Event.cs.

We'll focus primarily on the collision and positioning logic in this section. Initially we check if the player has input enabled and whether the player is pressing up. Checking the InputEnabled property is important otherwise the Player could press Up multiple times during the transition animation and force the animations to play over and over, resulting in confusing behavior. We use the PressedUp property which returns whether the default up input was just pressed. This property is defined in Player.cs.

As mentioned earlier, once inside the if-statement, the demo searches for a matching door which has the same first letter in its name. The player is immediately moved to this position and UpdateBoundsForPosition is called. As shown earlier, this method updates the camera bounds to the rectangle which contains the other door.

The demo also immediately moves the camera to the new bounds through the ApplyTarget method. The ApplyTarget method can optionally lerp (move the Camera smoothly) or move immediately. In this case we move immediately so that the camera doesn't move across the level and through areas inbetween the map sections. Notice that we are moving between two doors when entering a door, but we could also have created a convention which results in players moving to a completely different level. In this case, we would have called MoveToScreen rather than moving the Player to a new position. Such a system would enable games with maps which have multiple areas but which also connect to other maps, such as a dungeon in Final Fantasy 4.

Transitioning to Other Doors

When the player collides with a door and the if-check passes, the player's input is disabled and the transition logic begins. The first part of this transition is the async prefix on the OnPlayerListVsDoorListCollisionOccured method. This enables the method to use the await keyword to delay logic. Without this, the method would need to use more complex code to enable and disable input as the fade animations are playing. The OnPlayerListVsDoorListCollisionOccurred method is effectively split up into three sections, separated by the await calls:

The first section (yellow) happens immediately when the player presses up - the player's input is disabled, the door shows its open graphic, and the fading animation begins playing. Once the animation finishes the second section (green) happens. This section moves the player immediately and adjusts the camera bounds, and opens the other door. This happens while the screen is completely covered by the black overlay, so the player cannot see the immediate movement happen. Once this movement happens, the black overlay fades away. Finally, once the fade happens, the third section (blue) happens. This closes the door and enables the player's movement.

Conclusion

This walkthrough has covered how to add doors to a map enabling the player to move between different sections in the same level.

Introduction

This walkthrough covers the concepts of climbing ladders. When climbing a ladder, the platformer Player is able to move vertically by pressing up or down on the analog stick or d-pad. Ladders and vines are used to provide access to areas normally not reachable by jumping alone.

This walkthrough refers to LadderDemo as this demo and the demo.

Main Concepts

This walkthrough covers a number of concepts for climbing ladders:

• Defining ladder platformer values to control climbing speed

• Defining ladders in the TMX file

• Controlling whether currently climbing or not according to ladder collision and input

• Limiting the climbing height

Climbing Values

The Player entity defines a set of movement values for climbing called Climbing.

When this is set as the CurrentMovement, the player has direct control over vertical movement. When climbing up and down, the Climbing Speed is set as the player's Y velocity. As we will see later in the walkthrough, these values are explicitly set when the player presses Up to grab the ladder. Notice that the Player has a non-zero Max Speed under the Horizontal Movement section. This means that the player can move horizontally on the ladder. Some games like Super Mario world allow horizontal movement on ladders. Other games like Mega Man X only allow vertical movement on ladders. This game allows vertical movement, but changing the value to 0 results in no horizontal movement.

Defining Ladders

Ladders are placed in the TMX file as tiles. The following image shows just the GameplayLayer with ladders.

Notice that the ladder tiles define the maximum height that the player can climb.

The code for this is defined below, but we can add extra climb height by adding additional tiles to the map. Keep in mind the GameplayLayer tiles do not need to match the visual layer exactly.

These ladders tiles use the Ladder type.

This allows the creation of a LadderCollision TileShapeCollection.

Changing to Climbing Movement

Platformer Entities do not (currently) support automatic switching to climbing movement values. The demo includes custom code to enable switching to climbing. The main logic controlling the movement values is in the Player.cs CustomActivity method.

The CustomActivity method checks if the current movement can climb. If CurrentMovement.CanClimb is false, then the player is not climbing a ladder so we can do regular platformer logic for ducking and running. Otherwise, if the player is climbing, the game checks if the player is on ground (solid collision is colliding with the player from below) and if the user is pressing down. If so, we set the ground movement back to Ground so players can climb to the bottom and leave the climbing state.

The second half of CustomActivity code performs logic which switches between being on the ground, in the air, and on th eladder. Rather than only relying on a null check with LastCollisionLadderRectangle, the code also checks if the player's center point (X) is inside the bounds of the LastCollisionLadderRectangle. This prevents the player from moving too far off of the ladder horizontally before falling off. This code could be adjusted to allow the player to move more or less horizontally.

If the player is colliding with the ladder and presses up, then the player can grab a ladder. The player's movement on the horizontal axis is stopped and the player snaps its X position to the ladder's position. We also force the player to be on the ground and to use the Climbing movement values. If the player is not over the ladder but CurrentMovement.CanClimb is true, then the player has moved horizontally off of a ladder, so the player's movement is changed to air (falling). The LastCollisionLadderRectangle property is necessary rather than a bool value so that the player can snap to the ladder's X position. This is a regular property defined at the top of Player.cs.

This value is controlled by GameScreen. The ladder collision requires logic to be executed before collision occurs, so the PlayerListVsLadderCollision relationship does not automatically run.

Instead, all Players have their LastCollisionLadderRectangle explicitly set to null, then the PlayerListVsLadderCollision relationship is manually called in GameScreen CustomActivity.

Whenever a collision occurs, the LastCollisionLadderRectangle is set, as shown in GameScreen.Event.cs OnPlayerListVsLadderCollisionCollisionOccurred.

All of this results in the LastCollisionLadderRectangle storing a rectangle if the player collides with a ladder, and storing null if not. Note that this implementation will not work effectively if two ladders are placed next to each other.

Custom Movement Logic vs. Player Platform Movement Values

Limiting Ladder Height

When a player climbs down a ladder and collides with solid collision, IsOnGround will be set to true and the climbing movement values will be undone. The demo performs extra logic to prevent the player from climbing above the top of the ladder. Platformer entities like Player automatically have a TopOfLadderY property which can be assigned in custom code. The demo assigns this in the OnPlayerListVsLadderCollisionCollisionOccurred.

Whenever a collision occurs with ladder rectangles, the code moves up one tile at a time (using GridSize) until it finds the last tile. This is marked as the TopOfLadderY which prevents the player from climbing up indefinitely. The Player's position is defined as the bottom of the player, so in this case, the code limits the height that the player to the bottom of the ladder. This can be changed by modifying the last line of code in the code above. For example, we could let the player's feet reach the top of the ladder by changing the last line to:

Conclusion

This walkthrough has covered how to add ladder climbing to a platformer game.

Introduction

This walkthrough covers concepts related to creating an end-of-level entity which moves the player to the next level and creating a checkpoint which lets the player start at a midpoint in a level after dying.

This walkthrough refers to CheckpointAndEndLevelDemo as the demo and this demo.

Main Concepts

This walkthrough covers a number of concepts for checkpoints and end of level:

• Creating instances of Checkpoint and EndOfLevel entities in Tiled on object layers to allow different values on each instance

• Storing the current checkpoint name in a static variable so it persists across Screen instances

• Spawning and re-spawning the player at checkpoint locations

• Collision between the Player and objects controlling spawning (Checkpoint, EndOfLevel, and PitCollision)

Tiled Entity Creation

This demo includes two levels: Level1 and Level2. Each level has its own TMX file: Level1Map.tmx and Level2Map.TMX. If your project used the platformer plugin then it should have these by default. If your game already has existing levels, you can follow along but you will work in your existing levels rather than Level1 and Level2.

Adding an Object Layer

The checkpoints and doors will be added to a Tiled object layer. You must have at least one object layer on each level which should include a checkpoint. For this video we'll use the name GameplayObjectLayer so that it is similar to the standard GameplayLayer.

Creating Checkpoint and EndOfLevel Entities

We will create two entities: Checkpoint and EndOfLevel.

To add a Checkpoint entity:

1. Right-click on the Entities folder

2. Select Add Entity

3. Enter the name Checkpoint

4. Check the AxisAlignedRectangle option

5. Click OK

Repeat the process above to create an EndOfLevel entity

Next we'll add a new variable to EndOfLevel:

1. Expand EndOfLevel

2. Right-click on Variables

3. Select Add variable

4. Select the type string

5. Enter the name NextLevel

6. Click OK

Setting the Class on a Tile

Next we need to associate a particular tile with the entity. By doing this, FlatRedBall automatically instantiates the entities whenever it encounters a tile.

To do this:

1. Open your level in Tiled. Make sure you do not have other levels open as to avoid mixing tilesets

2. Select the TiledIcons tileset and click on the edit button

3. Select the tile that you would like to use as a checkpoint, such as the checkered flag

4. Set the Class to Checkpoint - be sure to match the name of your entity exactly\
5. Save your tileset

Now you can add instances of the Checkpoint tile to your level in the GameplayObjectLayer. You should provide a descriptive name of the Checkpoint, such as LevelStart. Note that checkpoints can exist at the beginning of a level - this is where the player may spawn when going from one level to another.

To do this:

1. Select the Checkpoint tile

2. Select the GameplayObjectLayer

3. Clck the Add Tile icon to go into tile placement mode

4. Click on the map to add the Checkpoint tile

All checkpoints must have names so that they can be referenced in code. For this project we assume that every level has at least one checkpoint with the name LevelStart. You can set this name on the newly-created Checkpoint by selecting it and setting its name in Tiled:

Next we'll declare which tile in our tileset should create an EndOfLevel instance. To do this, open up the TiledIcons tileset in edit mode again. Select the icon that looks like a door. You may notice that it already has a Class set, so you can change it from "Door" to "EndOfLevel". As mentioned above, the name must match your entity exactly.

Next, we can add a new property to the tile. This should match the name of our variable in the FRB Editor exactly. To do this:

1. Select the tile

2. Click the + icon at the bottom of the properties

3. Keep the type as string

4. Enter a property name of NextLevel

5. Click OK

The variable should appear on the tile.

Repeat the process above to add an EndOfLevel instance to your GameplayObjectLayer.

Once this instance has been placed, its variable can be changed. For example, we can set the variable to Level2.

LastCheckpointName and Spawning

We want our player to spawn at a checkpoint. We'll create a static variable called LastCheckpointName which indicates the starting Checkpoint.

Initially when the game starts the LastCheckpointName should be set to LevelStart so that the checkpoint that was previously created is used:

The following code shows the logic that does this:

The spawning checkpoint is used to set the player's position. Notice that the player is moved down 8 units after spawning - this accounts for the position of the spawn point being the center of the object, while the player's position is at the bottom (at the player's feet).

Player Collision

Collision between the Player and various objects controls the spawning behavior. As mentioned earlier, the LastCheckpointName variable controls which checkpoint is used to position the Player instance. The CustomInitialize method is called whenever a level is created (or recreated).

We will use the EndOfLevel instances to move the player from one level to the next, and to set the LastCheckpointName.

To do this:

1. Create a collision relationship between the PlayerList and EndOfLevelList in GameScreen

2. Add an event to the newly-created collision relationship

3. Open GameScreen.Event.cs

4. Add the following code to move to the next level and set the LastCheckpointName:

Notice that the code above assumes that the EndOfLevel instance has a valid NextLevel value. If the EndOfLevel NextLevel property is not set to a valid screen then this code will throw an exception. The code above resets the LastCheckpointName to LevelStart so that the Player spawns at the beginning of the level.

We can set the LastCheckpointName whenever the player collides with a checkpoint - it doesn't have to be only when the player collides with a door. To do this:

1. Create a collision relationship between PlayerList and CheckpointList

2. Add an event to the newly-created collision relationship

3. Open GameScreen.Event.cs

4. Add the following code:

The OnPlayerVsEndOfLevelCollided resets the LastCheckpointName whenever colliding with a door, so this checkpoint will apply whenever the screen changes. The OnPlayerListVsCheckpointListCollided sets the LastCheckpointName to the name of the collided checkpoint, but this will only apply when the screen is restarted. Typically, this would happen when the player dies.

Player death can be handled in a variety of ways, such as by collision with a TileShapeCollection, or even with a hotkey to test death. Regardless, the way to restart the screen is by calling this.RestartScreen().

For example, if you have a TileShapeCollection named PitCollision, a collision relationship can be created between the PlayerList and PitCollision to restart the screen. This relationship would have an event with the following code in GameScreen.Event.cs:

This code restarts the screen, which results in the entire screen being completely destroyed and recreated. Since CustomInitialize runs again, the Player will be re-positioned according to the LastCheckpointName.

Checkpoint Visuals

The demo includes two types of checkpoints:

1. Visible checkpoints - when the player collides with these checkpoints, the checkpoint changes appearance and sets the LastCheckpointName property.

2. Invisible checkpoints - are used only to spawn the player. In the case of the demo, only at the beginning of the level.

Whether a checkpoint is visible or not is controlled by an exposed Visible property.

Please note that if you are adding the checkpoints to your own custom project, to have the Visible property available you will need to set the ImplementsIVisible in Checkpoint Properties to true and then create a variable via the Expose an existing variable and select Visible. Also, since FlatRedBall purely converts the Tiled objects in the objects layer to instances of a FlatRedBall Entity with the same class, to actually see the flag and the door in your game you will need to add a Sprite object to the Checkpoint and EndOfLevel entities and set them to appropriate images or animation chain files. This subject is explained in detail in following tutorials.

Only Visible Checkpoint instances are considered in the Player vs Checkpoint relationship event.

The Checkpoint is visually composed of two Sprites:

• PoleSprite

• FlagSprite

By default, the FlagSprite is invisible, but is turned on in the MarkAsChecked function. This provides visual confirmation to the user that the checkpoint has been triggered.

Conclusion

This walkthrough showed how the demo project creates checkpoints which can be used to restart the player mid-level and end of level objects (doors) which can move to the next level.

Introduction

This tutorial explores how to add double jump to a platformer character. It covers how to add an extra jump (double jump), infinite jumping, or a limited number of jumps in the air.

Double Jump Variables

Double jumping is a feature in many platforms which gives the player more control over player movement. Players can use double jumping to remain in the air for a longer period of time, to reach areas higher than possible with a single jump, and improve horizontal movement precision. Entities which support double jumping require two sets of values - the movement values before double jump and the movement values to apply after double jump. Platformer entities automatically receive a platformer values called Air which are the before double jump variables, so we need to create a new set of values. To do this:

1. Select your platformer entity (Player)

2. Expand the drop-down next to the Add Movement Type button

3. Select Default Air Control option
4. Change the name of the new values to AfterDoubleJump

Changing Values

Now that we have a set of values for after double jump, we need to tell our game to use these new values for double jump:

1. Select the platformer entity

2. Click the Variables tab

3. Change the After Double Jump value dropdown to the name of the new set of values we just created (AfterDoubleJump)

Finally we need to change the Jump Speed value on the Air movement values to be greater than zero. This is the velocity which will be applied when performing a double jump.

Now the platformer entity (Player) supports double jumping.

Infinite Double Jumps

We can also support infinite double jumps by either setting the AfterDoubleJump Jump Speed value to greater than zero, or by setting the AfterDoubleJump variable to be Air. This results in the character being able to jump indefinitely which can be useful if implementing swimming or abilities like the flying racoon power-up in Super Mario Bros 3.

Limiting Jump Count

As shown above, the platformer entity can support a single double jump by making the AfterDoubleJump variables have a Jump Speed of 0. By increasing the Jump Speed to greater than 0, then the platformer entity can jump infinitely similar to flying or swimming. It is also possible to limit the number of jumps, but this requires custom code.

For this example we will use the two movement types from the previous sections: Air and AfterDoubleJump. To limit the number of jumps, make sure that AfterDoubleJump has a Jump Speed value of 0.

Next we will conditionally assign the Air value in code AirMovement value in code according to the number of jumps the player has performed since touching the ground.

To do so, open your platformer entity's code file (Player.cs) and modify the code as shown in the following snippet:

public partial class Player
{
    int currentNumberOfJumps = 0;

    private void CustomInitialize()
    {
        this.JumpAction += HandleJump;
    }

    private void HandleJump()
    {
        currentNumberOfJumps++;

        if(currentNumberOfJumps < 5)
        {
            // Assign air, which allows continual jumps
            AfterDoubleJump = PlatformerValuesStatic["Air"];
        }
        else
        {
            // assign AfterDoubleJump, which has a Jump Velocity of 0 so 
            // the player can't jump again
            AfterDoubleJump = PlatformerValuesStatic["AfterDoubleJump"];
        }
    }

    private void CustomActivity()
    {
        if(IsOnGround)
        {
            currentNumberOfJumps = 0;
        }

        FlatRedBall.Debugging.Debugger.Write($"Current number of jumps: {currentNumberOfJumps}");
    }

    private void CustomDestroy()
    {
    }

    private static void CustomLoadStaticContent(string contentManagerName)
    {
    }
}

Now our platformer entity can jump 5 times, as controlled by a variable in HandleJump.

Introduction

The GroundCollidedAgainst property can be used to detect the type of terrain that a platformer entity is standing on. This property, along with the standard ItemsCollidedAgainst property, can be used to perform complex logic in response to collision after all collision for a frame has been resolved. The most common use of the GroundCollidedAgainst property is to assign movement values.

Code Example - Setting GroundMovement According to GroundCollidedAgainst

Typically a platformer game will have collision relationships between the Player and various TileShapeCollections. For example, the following screenshot shows collision relationships between the Player and a number of TileShapeCollections.

Whenever the player collides with one of these TileShapeCollections, the GroundCollidedAgainst property will be updated. Some games may have multiple TileShapeCollections represent one type of terrain (such as Ice and IceCloud), so all collision should be resolved before determining the terrain type. In such a situation, the Player entity can have properties for determining the ground type as shown in the following code snippet:

public bool IsOnIce => GroundCollidedAgainst.Contains(nameof(GameScreen.IceCollision)) 
    || GroundCollidedAgainst.Contains(nameof(GameScreen.IceCloudCollision));
public bool IsOnSticky => GroundCollidedAgainst.Contains(nameof(GameScreen.StickyCollision));

These properties enable the assignment of movement values, such as GroundMovement, in CustomActivity as shown in the following code snippet:

if (IsOnIce)
{
    this.GroundMovement = PlatformerValuesStatic[DataTypes.PlatformerValues.IceGround];
}
else if(IsOnSticky)
{
    this.GroundMovement = PlatformerValuesStatic[DataTypes.PlatformerValues.StickyGround];
}
else if(IsInWater)
{
    this.GroundMovement = PlatformerValuesStatic[DataTypes.PlatformerValues.WaterGround];
}
else
{
    this.GroundMovement = PlatformerValuesStatic[DataTypes.PlatformerValues.Ground];
}

Similar logic could be performed to assign AirMovement and AfterDoubleJump. Consider that the code above requires that the GameScreen has its collision objects exposed publicly. To verify this is the case, select the object in the FlatRedBall Editor and check its HasPublicProperty value.

This set of tutorials covers how to add breakable blocks to your platformer game. Breakable blocks have been popularized in the Super Mario Bros franchise, but are also common in other games such as Castlevania, Metroid, and Mega Man.

Despite being introduced in an early Nintendo Entertainment System (and arcade) game, the feature of being able to break blocks requires advanced FlatRedBall collision functionality. We will be covering the following FlatRedBall topics:

• Creating entities in Tiled

• Using TileShapeCollections to adjust Entity RepositionDirections

• Dynamic destruction of entities

• Combining manual collision calls with CollisionRelationships

• Manually calling CollisionRelationship

Introduction

This walkthrough covers concepts related to creating moving platforms. Moving platforms can be used to transport a player vertically or horizontally, and can provide challenge and variety to a platformer level. When walking on a moving platform, the platformer Player is able to move faster and jump further.

This sample can be downloaded from GitHub: https://github.com/vchelaru/FlatRedBall/tree/NetStandard/Samples/Platformer/MovingPlatformDemo

This walkthrough refers to MovingPlatfomDemo as this demo and the demo.

Main Concepts

This walkthrough covers a number of concepts related to moving platforms:

• Moving platforms horizontally using acceleration and await calls

• Performing platformer collision between the PlayerList and MovingPlatformList

Moving Platforms Horizontally

The MovingPlatform entity is used in this demo. It moves itself by setting its XAcceleration value and changing this value on a timer controlled by async calls. This logic is started in MovingPlatform.cs and continues to loop until the MovingPlatform is destroyed.

public partial class MovingPlatform
{
    bool isDestroyed = false;

    private void CustomInitialize()
    {
        StartMoving();
    }

    private async void StartMoving()
    {
        async Task AccelerateFor(float acceleration, float seconds)
        {
            XAcceleration = acceleration;
            await TimeManager.DelaySeconds(seconds);
        }

        while(!isDestroyed)
        {
            await AccelerateFor(30, 1);
            await AccelerateFor(0, 2);
            await AccelerateFor(-30, 2);
            await AccelerateFor(0, 2);
            await AccelerateFor(30, 1);
        }
    }

    private void CustomActivity()
    {

    }

    private void CustomDestroy()
    {
        isDestroyed = true;
    }