Introduction

This tutorial walks you through installing and creating an empty FlatRedBall project.

Creating a New Project Without FlatRedBall Editor

If you would like to avoid using the FlatRedBall Editor completely, or if you are running on Linux or Mac, then you can directly download a project template .zip file. To do this:

1. Go to https://files.flatredball.com/content/FrbXnaTemplates/DailyBuild/ZippedTemplates/

2. Select your target platform. For example, if developing for desktop select https://files.flatredball.com/content/FrbXnaTemplates/DailyBuild/ZippedTemplates/FlatRedBallDesktopGlNet6Template.zip

3. Download and unzip the file to your machine

4. Open the .sln in Visual Studio or Visual Studio Code (see below for Visual Studio Code instructions)

Using FlatRedBall with Visual Studio Code

Visual Studio is not a requirement for using FlatRedBall. You can write, compile, and run FlatRedBall projects using Visual Studio code. To do so:

1. Install Visual Studio Code

2. Install Visual Studio Code C# Dev Kit https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit&ssr=false#overview

3. Make sure you have .NET SDK 6 installed. If you are targeting iOS, Android, or Web then you must have .NET 8 SDK installed.

Open the folder where the .sln is located for your project.

Select the folder where you have unzipped your project earlier.

If asked, check Yes, I trust the authors.

Alternative - Adding FlatRedBall to your MonoGame Project

If you have an existing MonoGame project, you can add FlatRedBall with the following steps:

1. Open your MonoGame project in Visual Studio

2. Add FlatRedBall reference to your project

   1. If targeting Desktop GL, you can add FlatRedBall through the FlatRedBall NuGet package\
   2. If targeting other platforms, you will need to manually add the FlatRedBall .dlls to your project:

      1. Download the .dll for the project you are working on from this folder: https://files.flatredball.com/content/FrbXnaTemplates/DailyBuild/SingleDlls/

      2. Save the .dll to a location relative to your project, such as a Libraries folder

      3. Link your game project to the newly-downloaded .dll

3. Modify Game1 so it contains the following calls:

In Initialize before base.Initialize():

FlatRedBallServices.InitializeFlatRedBall(this, _graphics);

In Update before base.Update(gameTime):

FlatRedBallServices.Update(gameTime);
// Optional if you plan on using Screens:
ScreenManager.Activity();

In Draw before base.Draw(gameTime):

FlatRedBallServices.Draw();

FlatRedBall requires a shader file for rendering. You need to add this to your project. To do this:

1. Download the compiled shader XNB file from: https://github.com/vchelaru/FlatRedBall/blob/NetStandard/Templates/FlatRedBallDesktopGlNet6Template/FlatRedBallDesktopGlNet6Template/Content/shader.xnb

2. Save this to your Content folder in your project

3. Add this file to your Visual Studio project (.csproj)

4. Mark the file as Copy if newer

Running Your FlatRedBall Project With Visual Studio

To run your newly-created project:

1. Double-click the .sln file to open it in Visual Studio

2. Once your project opens, click the Start button in Visual Studio

Your project should compile and run, displaying an empty (black) screen.

Running your Project Without Visual Studio

If you would like to run your project without Visual Studio, you can use the dotnet build command line, but you must first install the .NET 6 SDK. https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/sdk-6.0.308-windows-x64-installer Once you have installed it, you can run the dotnet command to build your project. To build your project

1. Open a command window (like Windows PowerShell)

2. Go to the folder where your .sln is located

3. Type the command dotnet build YourSolutionFile.sln

This should produce a .exe which you can then run.

Although the FlatRedBall Editor can help make game development much faster, some developers prefer to work more low-level, using just the FlatRedBall engine without any generated code. The following set of tutorials will show you how to create a basic code-only project.

Code-only projects can be effective if you are:

• Looking to integrate portions of FRB into an existing game (such as using FRB's collision and physics)

• Developing primarily on a platform which does not support the FRB Editor such as Linux

• Interested in developing a game without using an editor, but woud still like to use FlatRedBall for its various features (input, physics, collision management, content loading, content management, and so on)

Introduction

FlatRedBall provides a number of primitives which can be used to render your game, and to perform collision. These include:

• Sprite - draws an image to screen. This image is often referred to as a Texture.

• Text - draws text to screen.

• Circle - draws a circle to screen and can be used for circular collision.

• AxisAlignedRectangle - draws a rectangle to screen and can be used for collision. AxisAlignedRectangles cannot be rotated.

This tutorial shows how to create, move, and destroy a circle. It uses input from the keyboard to control the circle.

A Note About Organization

FlatRedBall provides Screens and Entities for organizing your code. These are built-in to the FlatRedBall editor, but we will not use these in this tutorial so we can focus on the raw FlatRedBall engine. Instead, this tutorial will place all code in Game1. Feel free to move this code to other classes to fit your own patterns.

Initializing the Camera

FlatRedBall provides a built-in Camera object which can be used to scroll, zoom, or even display graphics using a 3D perspective. For this tutorial we will set our camera up to be a pure 2D camera, where one unit equals one pixel on screen. To do this, add the following code to Game1's Initialize method, after the InitializeFlatRedBall call.

Camera.Main.UsePixelCoordinates();

Creating a Circle

The Circle object can be created and managed using the ShapeManager class. The ShapeManager class is responsible for:

• Creation of new instances

• Movement (velocity and acceleration)

• Drawing

• Destroying (removing references)

We will also use the InputManager which provides common classes for accessing keyboard, mouse, and Xbox gamepad input. We will be writing our code in the Update method in Game1.cs. By default our Update method looks like this:

protected override void Update(GameTime gameTime)
{
    FlatRedBallServices.Update(gameTime);

    FlatRedBall.Screens.ScreenManager.Activity();

    GeneratedUpdate(gameTime);

    base.Update(gameTime);
}

Some of this code is needed if using FRB editor's code generation functionality. If you are absolutely sure you do not want to use the editor, you can remove some code in Update as shown in the following snippet:

protected override void Update(GameTime gameTime)
{
    FlatRedBallServices.Update(gameTime);

    base.Update(gameTime);
}

You may notice other calls to partial methods which begin with the word "Generated" in your code. You are free to remove those methods as well.

To add a circle whenever the mouse is clicked, we will use the Cursor class to detect input and create a new circle, as shown in the following code:

protected override void Update(GameTime gameTime)
{
    FlatRedBallServices.Update(gameTime);

    IsMouseVisible = true;

    var cursor = FlatRedBall.Gui.GuiManager.Cursor;

    if(cursor.PrimaryClick)
    {
        var circle = FlatRedBall.Math.Geometry.ShapeManager.AddCircle();

        circle.X = cursor.WorldX;
        circle.Y = cursor.WorldY;
        circle.Radius = 8;
    }

    base.Update(gameTime);
}

Circle Movement

Circles (and most other FlatRedBall objects) can be positioned directly by setting the X and Y values, or their position can be modified by changing their velocity and acceleration values. For example, we can modify the code to give the circle a positive XVelocity and negative YAcceleration:

protected override void Update(GameTime gameTime)
{
    FlatRedBallServices.Update(gameTime);

    IsMouseVisible = true;

    var cursor = FlatRedBall.Gui.GuiManager.Cursor;

    if(cursor.PrimaryClick)
    {
        var circle = FlatRedBall.Math.Geometry.ShapeManager.AddCircle();

        circle.X = cursor.WorldX;
        circle.Y = cursor.WorldY;
        circle.Radius = 8;

        circle.XVelocity = 120;
        circle.YVelocity = 220;
        circle.YAcceleration = -180;
    }

    base.Update(gameTime);
}

The circles will now move to the right and up, but fall naturally.

Notice that the velocity and acceleration values apply automatically once they are assigned. The ShapeManager keeps track of all Circles and applies these values every frame. For more information on working with the Circle object in code, see the Circle page.

Introduction

Textures (which use the type Microsoft.Xna.Framework.Graphics.Texture2D) are used to draw graphics on the screen. A Texture is a resource which is usually loaded from .png and is drawn to the screen using the Sprite type. This code-only tutorial shows how to load a PNG to disk and how to draw it on screen using a FlatRedBall Sprite.

Adding a PNG to Your Project in Visual Studio

Before a PNG can be loaded, it must be added to your project. Normally the management of content files is handled by the FlatRedBall Editor, but this is something that must be done manually in a code-only project.

You can add files to your project by manually editing the .csproj or you can add a file through Visual Studio (or your current IDE).

To add a file to the project through Visual Studio:

1. Find or create a PNG file that you would like to use

2. Drag+drop the file into your Visual Studio project. Usually content is added to the Content folder, or a subfolder inside of the Content folder. \
3. Right-click on the file and select Properties
4. Set the Copy to Output Directory item to Copy if Newer

This tells Visual Studio to copy the Bear.png file to the output directory (where the .exe is created) while maintaining the folder structure. For example, if your .exe is built to <Project Root>\bin\DesktopGL\x86\Debug\CodeOnly.exe, then the Bear.png file will be copied to <Project Root>\bin\DesktopGL\x86\Debug\Content\Bear.png.

Adding a PNG to Your Project in Visual Studio Code

To add a PNG to your project in Visual Studio Code:

1. Find or create a PNG file that you would like to use

2. Drag+drop the file from an explorer window into your project's Content folder

We need to add an entry for the newly-added TextureFile so that it is copied to our project. We will need to do this for any PNG file (or other content file) that we add to our project in the future. To do this:

1. Select your .csproj file to display its contents
2. Look for a section of the .csproj where existing content is already handled
3. Copy/paste one of the None blocks to copy the newly-added TextureFile.png

Adding a File by Modifying Your .csproj File

To modify your .csproj file, you can open it and add the referenced file, similar to adding a file in Visual Studio Code. Note that you can also add wildcards. For example:

<None Update="Content\*.png">
  <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>

Creating a Texture2D

Next we'll create a Texture2D. Normally a Texture2D instance might be added to a Screen or Entity object, but we'll do all of our code in Game1 to keep things simple. Also, this example doesn't store a reference to the Texture2D at class scope, but you may want to do so in a real game so Texture2D reference can be reused outside of the initialization function. In this case we'll modify Game1.Initialize. The following code is the default for Initialize:

protected override void Initialize()
{
    #if IOS
    var bounds = UIKit.UIScreen.MainScreen.Bounds;
    var nativeScale = UIKit.UIScreen.MainScreen.Scale;
    var screenWidth = (int)(bounds.Width * nativeScale);
    var screenHeight = (int)(bounds.Height * nativeScale);
    graphics.PreferredBackBufferWidth = screenWidth;
    graphics.PreferredBackBufferHeight = screenHeight;
    #endif

    FlatRedBallServices.InitializeFlatRedBall(this, graphics);

    GlobalContent.Initialize();
    GeneratedInitialize();

    base.Initialize();
}

Since we are not using any generated code from the FlatRedBall Editor and we are not targeting iOS, we can remove most of the code, as shown in the following snippet:

protected override void Initialize()
{
    FlatRedBallServices.InitializeFlatRedBall(this, graphics);

    base.Initialize();
}

Now we can add code to load our PNG:

protected override void Initialize()
{
    FlatRedBallServices.InitializeFlatRedBall(this, graphics);

    // Use the name of your file, which might be Bear.png or TextureFile.png or whatever yours was called
    var bearTexture = FlatRedBallServices.Load<Texture2D>("Content/Bear.png");

    base.Initialize();
}

Now that the texture is loaded, we can draw it with Sprites. For example, the following code adds a Sprite to the center of the screen:

protected override void Initialize()
{
    FlatRedBallServices.InitializeFlatRedBall(this, graphics);

    // Use the name of your file, which might be Bear.png or TextureFile.png or whatever yours was called
    var bearTexture = FlatRedBallServices.Load<Texture2D>("Content/Bear.png");

    var sprite = SpriteManager.AddSprite(bearTexture);
    sprite.TextureScale = 1;

    Camera.Main.UsePixelCoordinates();

    base.Initialize();
}

The game now loads a Bear and shows it in the center of the screen.

Modifying a Sprite

Sprites inherit from the PositionedObject class, just like the Circle type used in the previous tutorial. Therefore, Sprites have many of the same properties as Circles including Position, Velocity, and Acceleration. We can create multiple Sprites in a loop, changing their position by setting X and Y as shown in the following code snippet:

protected override void Initialize()
{
    FlatRedBallServices.InitializeFlatRedBall(this, graphics);

    var bearTexture = FlatRedBallServices.Load<Texture2D>("Content/Bear.png");

    for(int i = 0; i < 5; i++)
    {
        var sprite = SpriteManager.AddSprite(bearTexture);
        sprite.TextureScale = 1;
        sprite.X = -100 + 40 * i;
        sprite.Y = i * 10;
    }


    Camera.Main.UsePixelCoordinates();

    base.Initialize();
}

This code creates five sprites, each using the same Texture2D.