The CornerGrabbingResize event is fired whenever a Windows Desktop application is resized by dragging the corners/edges, or by maximizing/restoring the window.

Introduction

The Game property returns a reference to the Microsoft.Xna.Framework.Game object. This will match the Game-inheriting class that is the root of all FlatRedBall games, usually called "Game1". For more information, see the Game page.

Code Example

// Sets the cursor to be visible on PC games:
FlatRedBallServices.Game.IsMouseVisible = true;

The ForceClientSizeUpdates method makes FlatRedBall update to the current size of the containing window or Control. This method is useful if you have implemented FlatRedBall in WinForms instead of using the default template.

The AddManager method can be used to add an instance of a FlatRedBall.Managers.IManager to the engine. This allows you to perform every-frame logic without requiring code to be added to the Game class or to the current Screen class if using Glue.

Introduction

FlatRedBallServices is a static class which is responsible for initializing the FlatRedBall Engine, performing managed behavior, and drawing. Although managed behavior and drawing is technically handled by manager classes, the FlatRedBallServices exposes methods which initiate these behaviors. The FlatRedBallServices class also provides methods for loading and unloading assets from memory. It standardizes the process of loading assets both from file and through the content pipeline and provides simple methods to organize and unload content selectively. The FlatRedBallServices also provides access to common game elements such as the Game class itself, the Owner Control, and other classes.

Creating a FlatRedBall Application

The following 3 lines are required to add the FlatRedBall Engine to an XNA template:

// in Initialize
FlatRedBallServices.InitializeFlatRedBall(this, this.graphics);

// in Update
FlatRedBallServices.Update(gameTime);

// in Draw
FlatRedBallServices.Draw();

For more information see the tutorial for Creating a FlatRedBall XNA Project.

FlatRedBallServices.Load

The generic Load method standardizes the loading of common FlatRedBall objects. The signature for the method is as follows:

FlatRedBallServices.Load<Type>(string objectName, string contentManagerName)

The Load method can be used to load both FlatRedBall and XNA types. For more information on the Load method, see the Load page. For more information on the contentManagerName, see the FlatRedBall Content Manager wiki entry.

Random Numbers

To generate random numbers the FlatRedBallServices class exposes an instance of the System.Random class. The following code creates a random int between 1 and 6; similar to a 6-sided die.

// The first argument is inclusive, the second is exclusive
int value = FlatRedBallServices.Random.Next(1, 7);

The following code creates a random number between 0 and 10 inclusive:

float randomNumber = (float)(FlatRedBallServices.Random.NextDouble() * 10);

The NextDouble returns a double value between 0 and 1. The code above multiplies it by 10 to get a value between 0 and 10. This value is a double, so the value must be converted to a float if it is to be used for a float variable.

Exiting FlatRedBall

To exit an application, call the Game's Exit method. This can be accessed through FlatRedBallServices:

FlatRedBallServices.Game.Exit();

Introduction

The GetManagerInformation returns a string which includes information about objects which are being managed by the different FlatRedBall managers.

The GetManagerInformation method returns counts of all of the different types of objects managed by FlatRedBall. It is likely that over time this list will grow, so when using this method you may find more information than is shown in the code examples on this page.

Code Example

The following code creates a Text object to display the result of the GetManagerInformation method. Even though there are no changes, the Text is updated every frame. If you are testing for accumulation errors (see below) then you will likely want to update the display frequently.

Add the following using statements:

using FlatRedBall.Graphics;

Add the following at class scope:

Text text;

Add the following to Initialize after initializing FlatRedBall:

text = TextManager.AddText("");
text.X = -10;
text.Y = 10;

Add the following to Update:

text.DisplayText = FlatRedBallServices.GetManagerInformation();

Accumulation Errors

Accumulation errors are bugs similar to memory leaks in unmanaged code. Accumulation errors occur when an object is added to the engine, but the object is not removed from the engine. For example, the method results in an accumulation error assuming that the created Sprite is not cleared at some other time:

public void CreateSpriteAndLoseReferenceToIt()
{
    Sprite sprite = SpriteManager.AddSprite("redball.bmp");

    // The next line will NOT get rid of the reference:
    sprite = null;
    // The Sprite is still being held by the SpriteManager
}

The GetManagerInformation method is a great way to check for accumulation errors.

One of the most indicative symptoms of having accumulation errors is if your game continually runs slower and slower over time. This often happens because more and more objects are being added to the engine. As more objects build up in the engine, the engine must manage more objects every-frame, and it can eventually get to a point where frame rate suffers.

To check for this, simply print out the result of the GetManagerInformation call and watch for steady increases over time. This method will not only verify if you are experiencing accumulation errors, but the growing category can also give you an idea of where to look for the bug.

Introduction

The Load method is a method which can be used to load content either from a XNB (if using content pipelines) or from raw file if FlatRedBall supports the file format. For more information on the Load method and how FlatRedBall caches content, see the FlatRedBall Content Manager wiki entry.

File locations

The Load method supports either absolute or relative file names. In other words, both are valid (assuming the files exist):

Texture2D texture = FlatRedBallServices.Load<Texture2D>("redball.bmp");

--or--

Texture2D texture = FlatRedBallServices.Load<Texture2D>("C:\MyGame\bin\x86\debug\content\redball.bmp");

The Load method will prepend FileManager.RelativeDirectory if the argument file is relative. In other words, the following two are equivalent:

Texture2D texture = FlatRedBallServices.Load<Texture2D>("redball.bmp");

--and--

Texture2D texture = FlatRedBallServices.Load<Texture2D>(FileManager.RelativeDirectory + "redball.bmp");

FileManager.RelativeDirectory defaults to the project's Content directory (the location where the Content project copies/builds files if using XNA). Therefore, if redball.bmp were present at the root of the content folder, then "content\redball.bmp" would be used to load the file.

Files and Folders

If using an XNA project, most files are added to a Content project. Any file added to the Content project must be loaded with the "content/" prefix. For example, if a file "redball.bmp" is added to the root of the Content project, then the call to load it would be:

// If added as a file:
FlatRedBallServices.Load<Texture2D>("content/redball.bmp");
// If added through the content pipeline:
FlatRedBallServices.Load<Texture2D>("content/redball");

Load and Caching

The Load method supports caching and returning cached content to improve speed and reduce memory usage. To understand this, consider the following

// Assuming this code is written in a Glue screen:
var contentManager = this.ContentManagerName;
var loadedTexture = FlatRedBallServices.Load<Texture2D>("Character.png", contentManager);
// loadedTexture is now a valid texture

The Load call performs the following logic:

1. Look for a ContentManager with a name matching the contentManager argument.

   1. If no contentManager is specified, the "global" ContentManager is used.

   2. If no matching ContentManager is found, create one.

2. Search the ContentManager for an instance that has a matching name.

   1. If the content is found, return the existing instance. This saves time loading content and reduces RAM usage.

   2. If the content is not found, attempt to load it.

For more information on how file names are stored, see the ContentManager.IsAssetLoadedByName page.

Load can return IDisposables added through AddDisposable

The Load method can give you disposables that have been added through AddDisposable. This means that you can use FlatRedBallServices as a cache for content that comes from disk as well as content created dynamically. For example, the following method would work:

Texture2D texture2D = CreateTextureDynamically();
FlatRedBallServices.AddDisposable("UniqueTextureName", texture2D, ContentManagerName);
// later you can get the texture as follows:
Texture2D sameTexture = FlatRedBallServices.Load<Texture2D>("UniqueTextureName", ContentManagerName);

Introduction

The Initialize method is responsible for preparing the FlatRedBall engine for execution. It should be called prior to interaction with any FlatRedBall managers. This function is automatically called in all FlatRedBall templates and Glue projects so you do not need to manually call this unless you are adding FlatRedBall to an existing XNA project.

Code Example

// "this" refers to the Game instance, which is by default called Game1
FlatRedBallServices.InitializeFlatRedBall(this, this.graphics);

Introduction

The Draw function performs all FlatRedBall rendering. This function is automatically part of all FlatRedBall templates, including projects created by the FlatRedBall Editor, so it does not need to be added manually. However, it can be removed to quickly disable rendering of FlatRedBall for debugging and customization.

Breaking down Draw

The Draw function can be broken down into two calls: and . Therefore, the following line:

could be replaced with:

The function can be further broken-up:

The Renderer.Draw method can be further broken-up. By breaking apart the draw calls, each individual camera can be optionally drawn, or it can be drawn to a separate render target:

The contents of DrawCamera are currently private so this method cannot be broken up further; however, the source for DrawCamera can be inspected by looking at the source code.

The GlobalContentManager is a value which can be used to load content using a "global" content manager. Not only is this content manager available globally, but it is never unloaded. Therefore, any content loaded using GlobalContentManager will not be unloaded until the game exits.

Using a GlobalContentManager is useful for content which appears frequently in games (such as fonts) or for content which may take a long time to load/process, and should be kept in RAM to improve load times despite occupying space permanently.

For information on global content in Glue, see the GlobalContentFiles page and the UseGlobalContent page.

Introduction

If you are dynamically creating IDisposable (such as Texture2Ds), you will need to dispose them at some time. Adding them to a ContentManager is the easiest way to do this. The AddDisposable method can be used to add Texture2Ds (and any other IDisposable) to FlatRedBall for convenient caching and automatic unloading.

The AddDisposable method takes an IDisposable to add to a Content Manager along with the name to use for the IDisposable and the Content Manager to place the IDisposable in.

When should this be used?

This is only needed if a piece of content comes from somewhere other than the ContentManager or FlatRedBall.FlatRedBallServices.Load. For example, the Texture created here does not need to be added to through the AddDisposable method:

Texture2D texture = FlatRedBallServices.Load<Texture2D>("fileName.png", "ContentManagerName);

It will already be added to a content manager by the name "ContentManagerName". However, if you use something like ImageData or some other method to create your texture that doesn't come from file or content pipeline, you'll want to add the texture with AddDisposable.

Code Example

The following code creates a Texture2D using the Texture2D's FromFile method, then places the Texture2D in the Content Manager named "SomeContentManager":

Add the following using statements:

using FlatRedBall;
using Microsoft.Xna.Framework.Graphics;

Add the following using statements:

string fileName = "redball.bmp";
Texture2D texture2D = Texture2D.FromFile(FlatRedBallServices.GraphicsDevice, "redball.bmp");
string contentManagerName = "SomeContentManager";
FlatRedBallServices.AddDisposable(fileName, texture2D, contentManagerName);

The GraphicsOptions property provides the static reference to a GraphicsOptions instance. For more information see the GraphicsOptions page.

Introduction

The IsLoaded method can tell you if a certain piece of content is already loaded and cached in RAM. Simple games (especially games which use Glue) usually do not need to worry about this - Glue can handle content loading and unloading intelligently. However, if you are using custom loading code, especially if you are loading content without using FlatRedBall methods (such as creating Textures dynamically or from a memory stream), you may want to cache the loaded content in a FlatRedBall ContentManager, then use the IsLoaded method to check if it has already been cached to prevent recreating the same content multiple times.

Usage

The IsLoaded method returns a bool whether the content is already loaded or not. To use this method you simply call IsLoaded passing in the key (also often referred to as "name") of the object you're looking for as well as the ContentManager name:

bool isLoaded = FlatRedBallServices.IsLoaded<Texture2D>("redball.bmp", ContentManagerName);

Note that the type of the content must be used as a generic type to the IsLoaded method. The reason for this is because two pieces of content may have the same name (for example a Scene and a Texture2D may both be named "SpaceShip"). The generic argument allows FlatRedBall to distinguish between the two.

FlatRedBallServices.Update performs all non-drawing FlatRedBall updates. This includes:

• Updating all managed object positions, velocities, rotations, and other velocity/rate variables

• Reading input

• Performing instructions

This method should be called in the Game's Update function, prior to any custom activity.

The RenderAll function performs rendering of all visual FlatRedBall objects on all Layers. This method is normally not manually called by code outside of FlatRedBall - it is automatically called by FlatRedBallServices.Draw - a method which is automatically included in all FlatRedBall templates. This method is exposed so that it can be called independent of FlatRedBallServices.UpdateDependencies for performance and customization reasons. The Render call is responsible for the following:

• Calling Renderer.Draw to perform the rendering. This call is made inside a lock on the Renderer.GraphicsDevice. The reason for this lock is to prevent the graphics device from being used in rendering while a separate thread is attempting to load a Texture2D. Since Glue easily allows the creation of loading screens, loading on separate threads is quite common.

• Resetting the textures on the device.

As mentioned above, this method is normally not called manually in games; however you can call it manually if you are debugging, or performing advanced rendering with render targets. The RenderAll function can be replaced with the following code:

lock (Renderer.Graphics.GraphicsDevice)
{
    Renderer.Draw(section);
}
Renderer.Texture = null;
FlatRedBallServices.GraphicsDevice.Textures[0] = null;

Introduction

The Owner is a Control that the FlatRedBall Engine renders to. This property is available only on the PC since the Xbox 360 does not render to a Control.

Eliminating the Border

The following code will result in a game window without any borders. Keep in mind that without the borders the close button will not be present, so you will need to close your application through Visual Studio, through the Task Manager, or by adding close code in your application.

Add the following using statement:

using System.Windows.Forms;

Add the following to initialize after initializing FlatRedBall:

((Form)FlatRedBallServices.Owner).FormBorderStyle = FormBorderStyle.None;

Reacting to Form Closing

The Owner can be casted to a Form, and the form provides a number of useful properties and events. The following code can be used to react to the user using the mouse to press on the X close button.

Add the following to Initialize after initializing FlatRedBall:

Form ownerAsForm = ((Form)FlatRedBallServices.Owner);
ownerAsForm .Closing += new System.ComponentModel.CancelEventHandler(GameForm_Closing);

Add the following at class scope:

private void GameForm_Closing(object sender, System.ComponentModel.CancelEventArgs e)
{
    // The following line cancels the close.
    e.Cancel = true;

    // Now you can do whatever you want like as the user if he's sure
    // To manually close, you can use the following line of code:
    // FlatRedBallServices.Game.Exit();
}

Detecting Active Form

Some applications, such as tools, should only have their logic called if they are active. In other words, if the user clicks a different window (such as a web browser or instant messenger window), then the game should skip certain logic. The following code detects whether the game's Form is active:

if(System.Windows.Forms.Form.ActiveForm == (Form)FlatRedBallServices.Owner)
{
   // The current form is active, so do whatever here.
}

Introduction

The WindowHandle is an IntPtr referencing the Form that is hosting the XNA game. This can be used to get access to the form to perform customization and handle events.

Accessing a Form

The following code can be used to get the current Form:

Disabling FRB when minimized

If your application uses the [STAThread] attribute on your program's Main function (often to interact with winforms), your FRB apps may not resume properly when minimized. To correct this you can simply disable the FRB engine from performing logic when its host window is minimized. To do this:

Add the following code to Initialize:

Add the following code to your Game class:

The Unload function can be used to unload all content associated with a content manager. The function's only parameter is the name of the content manager to unload. Keep in mind that most games will not need to manually unload content as this is done automatically when moving between Screens in Glue.

Introduction

The Random property in FlatRedBallServices provides access to a global random number generator. This property is of the standard System.Random type.

How to get Random Integers

The following code shows how to get a number between 0 and 3. Notice that the call is exclusive, meaning whatever number you pass in will not be part of the range. Therefore to get a number between 0 and 3, we pass 4.

// Returns {0, 1, 2, or 3}
int randomNumber = FlatRedBallServices.Random.Next(4);

The Next function with a single integer value has an implied lower bound of 0. You can also explicitly define the lower bound. For example, to get a number between 3 and 7 (possible values being 3, 4, 5, 6, 7), you would do the following:

// 3 is inclusive, 8 is exclusive, so possible values are {3, 4, 5, 6, or 7}
int randomNumber = FlatRedBallServices.Random.Next(3, 8);

How to get Random Floats

The Between function is the easiest way to get a random number. The following example shows how to get a random number between 0 and 100, where both 0 and 100 are possible values:

float randomValue = FlatRedBallServices.Random.Between(0, 100);

You can also use the NextDouble method, which is a standard function on the .NET Random object. The NextDouble method provides a random number between 0 and 1. This number can then be modified to get any range of random numbers. For example, to get a float between 0 and 100, you would do the following:

// Gets a number between 0 and 100...
float randomNumber = (float)FlatRedBallServices.Random.NextDouble() * 100;
// ...which may be used to position an object:
MyCharacter.X = randomNumber;

How to Perform an Action at a Certain Percentage Chance

Using Random.Between function can be used to perform code a certain percentage of time. The following example shows how to perform an action 15% of the time

var percent = 15;
var randomNumber = FlatRedBallServices.Random.Between(0, 100);
var shouldPerformAction = percent <= randomNumber;
if(shouldPerformAction)
{
  // do the action here
}

How to get Random Objects in a List

The In function returns a random object in the list. For example, the following code gets a random enemy in a list called EnemyList:

var enemy = FlatRedBallServices.Random.In(EnemyList);

The MultipleIn function returns a new list populated randomly by selecting items from the original list. The returned list will not return duplicates unless the original list contains duplicates. For example, the following code shows how to get 3 enemies from a list called EnemyList:

var randomEnemies = FlatRedBallServices.Random.MultipleIn(EnemyList, 3);