Introduction

The AddUnloadMethod allows you add custom logic to be executed when a ContentManager is unloaded. This is most often used to null-out static references to content contained in a particular ContentMangaer. This functionality is used heavily in Glue generated code, but it can also be used to null-out static objects in custom code.

Code Example

The following code shows how to create a static Texture2D in custom code, and how to properly unload it. This code would be part of the custom code of a Screen or Entity. For this example we'll assume an Entity called Character.

// At class scope
static Texture2D mCustomTexture;

// In CustomInitialize:
if(mCustomTexture == null)
{
   mCustomTexture = FlatRedBallServices.Load("TextureName.png", ContentManagerName);
   ContentManager contentManager = FlatRedBallServices.GetContentManagerByName(ContentManagerName);
   contentManager.AddUnloadMethod("CustomUnloadForCharacter", CustomUnloadStaticContent);
}

// Finally define the CustomUnloadStaticContent method
static void CustomUnloadStaticContent()
{
    mCustomTexture = null;
}

Introduction

The Load method is used to obtain a reference to an object which is created from a file on disk. Common examples of are Texture2D (usually from a .png file), SoundEffect (usually from a .wav file), and AnimationChainList (usually from a .achx file). The Load method caches a file when successfully loaded, and subsequent calls to the Load method will return the cached reference.

Texture2D

The Load method can be used to load a Texture2D from an image file.

Exceptions

System.InvalidOperationException: This image format is not supported ---> System.ArgumentException: Handle must be valid. Parameter name: array

This exception can occur if your game is attempting to load a texture that is larger than is supported on the hardware running your game. For example, at the time of this writing many Android devices support 4096x4096 textures, but phones which only support 2048x2048 are still somewhat common. If the phone does not support loading the texture due to dimensions the app will throw a System.InvalidOperationException .

Introduction

AnimationChainListSaves are the "save" object type for AnimationChainLists. AnimatiohChainListSaves can be used to create and load .achx files. For general information on common FlatRedBall types, see the FlatRedBall File Types wiki entry.

The AnimationChainListSave class is a standardized way to save an AnimationChainList. Using the AnimationChainListSave class has the following benefits:

1. Requires very little code to use

2. Resulting files are 100% compatible with the FRBDK or any other application that can load .achx files.

Loading a .achx file

You can load load a AnimationChainListSave as follows:

AnimationChainListSave saveInstance = AnimationChainListSave.FromFile("fileName.achx");

Saving a .achx file

The following code saves a .achx file named MyAnimationChainList.achx. It assumes that animationChainList is a valid AnimationChainList.

Add the following using statements:

using FlatRedBall.Content.AnimationChain;
using FlatRedBall.Graphics.Animation;

Assumes animationChainList is a valid AnimationChainList:

 AnimationChainListSave save =
    AnimationChainListSave.FromAnimationChainList(animationChainList);
 string fileName = "MyAnimationChainList.achx";
 save.Save(fileName);

Saving a loaded AnimationChainListSave

Of course, you can save a loaded AnimationChainListSave:

string fileName = "fileName.achx";
// load it
AnimationChainListSave saveInstance = AnimationChainListSave.FromFile(fileName);
// and save it
saveInstance.Save(fileName);

Of course, the code above does nothing; however, you can do things to the saveInstance between the load and save calls:

 string fileName = "fileName.achx";
// load it
AnimationChainListSave saveInstance = AnimationChainListSave.FromFile(fileName);
foreach(AnimationChainSave chainSave in saveInstance.AnimationChains)
{
   // Do whatever to the chainSave
   // You can even loop through the frames:
   foreach(AnimationFrameSave frameSave in chainSave.Frames)
   {
       // do whatever you want to frames
   }
}
// and save it
saveInstance.Save(fileName);

In fact, you can do pretty much anything to an AnimationChainListSave instance and it will result in a valid .achx file when saving it out. This enables you to easily create tools to create and modify .achx files.

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

FlatRedBall supports having any number of ContentManagers living concurrently. This section will explain some situations where multiple content managers may be useful.

Overlapping content

Multiple content managers may be used if two content managers can exist at the same time, usually for async or time-sliced loading. For example, consider a game where the user transitions from one screen to another. The content managers lay live as follows:

|----------Screen 1 Content Manager --------|
                                 |---------Screen 2 Content Manager-------|
             Async loading starts^          ^Async loading finishes

Content managers can also be used to provide transitions between Screens - this is typically how Loading screens operate:

|-----Screen 1 Content Manager -----| |-----Screen 2 Content Manager|       
                            |Loading Screen-|

Varied lifespans

Content managers can be used if you have content which has a predefined lifespan and will be removed before the current Screen is destroyed. This may look like this:

|-------------Screen 1 Content Manager -----------|
               |---Object ContentManager---|
Start of object^                           ^End of object

Note that deleting the object may not help much to reduce maximum memory usage - the peak will likely be hit while both content managers are alive.

Individual Asset Handling

If you need to load and unload individual assets, you may consider using multiple content managers. This is useful for tools. Keep in mind that if you are performing from-file content loading, you do not necessarily need to even use content managers. The ContentManager class is intended to be used as a convenient way to cache, group, and unload a collection of content, so situations where you load and unload individual files may not benefit from working with a ContentManager.

Introduction

The CameraSave class is a class that can store information about a FlatRedBall.Camera which can be saved and loaded to/from disk. The CameraSave class appears in the SpriteEditorScene class.

Setting a Camera's properties from a CameraSave instance

The most common use of the CameraSave class is in the SpriteEditorScene class.

The following code loads a SpriteEditorScene from a .scnx file and sets the default Camera's properties to match the CameraSave.

// This assumes that Content\MyScene.scnx is a valid .scnx file
SpriteEditorScene ses = SpriteEditorScene.FromFile(@"Content\MyScene.scnx");
// We'll use the default Camera:
Camera cameraToSet = SpriteManager.Camera;
// Now simply apply the properties as follows:
ses.Camera.SetCamera(cameraToSet);

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

A SpriteEditorScene is a "ready to save" or "just loaded" Scene. It is used to load a Scene from a .scnx file and it can be used to write .scnx files easily. The FlatRedBallServices class internally uses the SpriteEditorScene class when you use it to load Scenes.

You will not need to use the SpriteEditorScene class in most cases because you can load .scnx files through the FlatRedBallServices.Load method as shown here.

Loading a .scnx into a Scene

Using the SpriteEditorScene can give you additional information and control over how Scenes are created. In most cases you will want to use the FlatRedBallServices' Load method.

The following code shows how to load a .scnx file using the SpriteEditorScene instead of the FlatRedBallServices method:

Add the following using statement:

using FlatRedBall.Content;

Add the following to initialize after initializing FlatRedBall:

string fileName = "SplashScreen\SplashScreen.scnx";
string contentManagerName = "ContentManagerName";
SpriteEditorScene saveObject = SpriteEditorScene.FromFile(fileName);
Scene scene = saveObject.ToScene(contentManagerName );

scene.AddToManagers();

The SpriteEditorScene.FromFile method loads and returns an instance of a SpriteEditorScene which is loaded from the argument .scnx. This SpriteEditorScene is then converted to a Scene by calling the ToScene method. The ToScene method takes a content manager name. For more information on content managers, see the FlatRedBall content manager entry.

Next, the Scene adds all of its contained objects to the appropriate managers through the AddToManagers method. Prior to calling AddToManagers all objects referenced by the Scene are stored in memory but they are not managed or drawn.

Loading a .scnx into a SpriteEditorScene

The example above which loads a .scnx into a Scene has the following compound line:

SpriteEditorScene.FromFile(fileName).ToScene(contentManagerName );

This could be broken up into:

SpriteEditorScene spriteEditorScene = SpriteEditorScene.FromFile(fileName);
Scene scene = spriteEditorScene.ToScene(contentManagerName);

The SpriteEditorScene is an "intermediary" type that is used to create a Scene; however there are situations where you may want to use the intermediary SpriteEditorScene in your game.

For example, consider a situation where you want to position Entities inside the SpriteEditor. Unfortunately the spriteEditor only supports the creation of .scnx files; however, you can load the .scnx into a SpriteEditorScene then instantiate Entities according to the position of Sprites in your .scnx. The following example shows what this code would look like assuming you have an Entity called Coin;

SpriteEditorScene spriteEditorScene = SpriteEditorScene.FromFile(fileName);
foreach(SpriteSave spriteSave in spriteEditorScene.SpriteList)
{
   Coin coin = new Coin(ContentManagerName);
   coin.X = spriteSave.X;
   coin.Y = spriteSave.Y;
   // perhaps you might add the Coin to a List here:
   CoinList.Add(coin);
}

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

Saving a .scnx

FlatRedBall provides code to save .scnx files from FlatRedBall applications. This allows the saving of .scnx files for custom scene building and debugging. Any .scnx file created with FlatRedBall will be loadable in the SpriteEditor.

To save a Scene, you must first create a SpriteEditorScene instance. You can create a SpriteEditorScene either from a Scene instance, or by manually creating the objects.

The easiest way to save a .scnx file is to first create a Scene, then use the SpriteEditorScene's static FromScene method.

For example, the following code creates and saves a .scnx file.

// Assuming myScene is a valid Scene
SpriteEditorScene spriteEditorScene = SpriteEditorScene.FromScene(myScene);
spriteEditorScene.Save("fileName.scnx");

Manually constructing a .scnx

If you would like more control over how your .scnx is created, you can manually construct SpriteEditorScenes to be saved. To do this:

• Instantiate a SpriteEditorScene

• Create "Save" objects which represent FlatRedBall objects (Sprites, SpriteGrids, SpriteFrames, Texts) and set their properties and fields appropriately.

• Add the "Save" objects to the SpriteEditorScene.

• Save the SpriteEditorScene (which serializes it to an XML file).

Saving Sprites

The following code creates 20 Sprites and saves them to a .scnx file.

Add the following using statement:

using FlatRedBall.Content.Scene;

In Initialize:

SpriteEditorScene spriteEditorScene = new SpriteEditorScene();

for (int i = 0; i < 20; i++)
{
    Sprite sprite = SpriteManager.AddSprite("redball.bmp");
    sprite.X = -17 + i * 1.4f;
    sprite.Y = -10 + i;
    sprite.Z = -25 + i * 2;

    sprite.RotationZ = i / 10.0f;

    SpriteSave spriteSave = new SpriteSave();

    spriteSave.X = sprite.X;
    spriteSave.Y = sprite.Y;
    spriteSave.Z = sprite.Z;
    spriteSave.RotationZ = sprite.RotationZ;
    spriteSave.Texture = "redball.bmp";

    spriteEditorScene.SpriteList.Add(spriteSave);
}
spriteEditorScene.Save("fromCode.scnx");

First the SpriteEditorScene instance is created. Next 20 Sprites are created. These Sprites will both appear in the application when it runs as well as saved in the SpriteEditorScene. Next, each Sprite is represented by a SpriteSave which has its properties set then is added to the SpriteEditorScene.

Once all Sprites have been created the Scene is saved to a .scnx file. Be sure to use a .scnx extension so the SpriteEditor recognizes this file as a valid scene.

Saving SpriteGrids

The following code creates a SpriteGrid with a different Texture2D displayed by the center Sprite.

Add the following using statements:

using FlatRedBall.Content.Scene;
using FlatRedBall.Content.SpriteGrid;

In Initialize:

 SpriteEditorScene spriteEditorScene = new SpriteEditorScene();

 Sprite blueprint = new Sprite();
 blueprint.Texture = FlatRedBallServices.Load<Texture2D>("redball.bmp", "Global");
 SpriteGrid spriteGrid = new SpriteGrid(SpriteManager.Camera, SpriteGrid.Plane.XY, blueprint);

 spriteGrid.XLeftBound = -10;
 spriteGrid.XRightBound = 10;
 spriteGrid.YTopBound = 10;
 spriteGrid.YBottomBound = -10;

 spriteGrid.PaintSprite(0, 0, 0,
     FlatRedBallServices.Load<Texture2D>(@"Assets\Scenes\frblogo.png"));

 spriteGrid.PopulateGrid();

 SpriteGridSave spriteGridSave = SpriteGridSave.FromSpriteGrid(spriteGrid);

 spriteEditorScene.SpriteGridList.Add(spriteGridSave);

 spriteEditorScene.Save("spriteGridFromCode.scnx");

SpriteEditorScene Members

• FlatRedBall.Content.SpriteEditorScene.Camera

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

The IsAssetLoadedByName method returns whether a file of a given type is already loaded and stored in RAM by the given ContentManager.

Code Example

The following code can be used to check if a file Background.png is loaded as a Texture2D in the current screen's content manager:

var contentManagerName = this.ContentManagerName;
var contentManager = FlatRedBallServices.GetContentManagerByName(contentManagerName);
bool isAlreadyLoaded = contentManager.IsAssetLoadedByName<Texture2D>("content/background.png");

Name Details

IsAssetLoadedByDetail processes the assetName parameter before checking if it has been loaded. Specifically, the following modifications are made:

1. If the argument is relative (such as content/background.png ), then it is converted to an absolute path (such as c:/MyGame/bin/debug/content/background.png ).

2. The file is standardized using the FileManager.Standardize method.

3. The content type is appended to the file name. This allows the same file to be loaded into multiple types.

For example, loading "content\Background.png" may result in the string "c:/folder/content/background.pngTexture2D" being stored in the ContentManager.

The SpriteEditorScene's Camera property is a CameraSave which stores information about the FlatRedBall.Camera.

This property is by default not used when loading a .scnx file by the engine. It is primarily used to store the position of the Camera in tools like the SpriteEditor and TileEditor. However, this member can be accessed to set a Camera's properties to match what has been saved.

For information on how to use the SpriteEditorScene's Camera property, see the CameraSave page.

Introduction

The ShapeCollectionSave class is a "save" class. Save classes are classes which allow you to load XML files to runtime objects as well as to save data contained in runtime objects to XML files. For more information on Save files, check this article.

You do not need to use the ShapeCollectionSave class in most cases since the FlatRedBallServices' Load method can load ShapeCollections. If you are simply looking to load a ShapeCollection, see this page.

You can use ShapeCollectionSave if you are making a tool that works with the .shcx file format.

Loading a .shcx file

You can load load a ShapeCollectionSave as follows:

ShapeCollectionSave saveInstance = ShapeCollectionSave.FromFile("fileName.shcx");

Saving a .shcx file

Sha'eCollectionSaves can be saved through the Save method. Therefore, the process of saving an existing ShapeCollectionSave is very simple:

string fileName = "c:/folder/fileName.shcx"; // The .shcx extension is the standard extension for ShapeCollectionSaves
shapeCollectionSaveInstance.Save(fileName);

The more complicated process is to construct the ShapeCollectionSave. You can construct a ShapeCollectionSave by creating a ShapeCollectionSave from an existing ShapeCollection or manually (by instantiating and adding instances to it).

Creating a ShapeCollectionSave from a ShapeCollection

The following code saves a .shcxfile named MyShapeCollection.shcx. It assumes that shapeCollection is a valid .

Add the following using statements:

using FlatRedBall.Math.Geometry;
using FlatRedBall.Content.Math.Geometry;

Assumes shapeCollection is a valid ShapeCollection:

 ShapeCollectionSave save =
    ShapeCollectionSave.FromShapeCollection(shapeCollection);
 string fileName = "MyShapeCollection.shcx";
 save.Save(fileName);

Creating a ShapeCollectionSave manually

The steps for creating a ShapeCollectionSave manually are:

1. Instantiate a ShapeCollectionSave

2. Add "save" instances to the ShapeCollectionSave (such as PolygonSave and CircleSave)

3. Save using the Save method.

Creating a ShapeCollection from a ShapeCollectionSave

You can convert ShapeCollectionSaves into runtime ShapeCollections: Add the following using statements:

using FlatRedBall.Math.Geometry;
using FlatRedBall.Content.Math.Geometry;

Assumes "save" is a valid ShapeCollectionSave:

ShapeCollection newShapeCollection = save.ToShapeCollection();
// You can make the ShapeCollection visible if desired:
newShapeCollection.AddToManagers();

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

FileAliases is used to create aliases for files. The most common use case for FileAliases is to allow systems which expect to load files with extension to be able to access files that have been loaded by the content pipeline (which have no alias).

FileAliases can be added in code generation by the FlatRedBall Editor or manually in code.

Code Example - Manually Adding a Content Pipeline Extension

For this example, assume that a PNG has been added to the Content directory using the content pipeline. At runtime, this file would be loaded using the following code:

var texture = SomeContentManager.Load<Texture2D>("Content/MyPngFile");

Assuming that MyPngFile is built using the content pipeline, then the file MyPngFile.xnb should be included in the Content folder.

Some systems, such as Tiled or Gum, may expect that PNG files are loaded with their extension so they attempt to load the file using an extension such as "Content/MyPngFile.png". We can add a file alias to FlatRedBall to enable loading the file as shown in the following code. Note that the aliases use the FilePath type, so it's important to include the relative directory which is typically the .exe's directory:

var relativeDirectory = FileManager.RelativeDirectory;
SomeContentManager.FileAliases[relativeDirectory + "Content/MyPngFile.png"] = 
    relativeDirectory + "Content/MyPngFile.png";

Since Gum and Tiled both route their file loading through FlatRedBall, then the alias will be used. Also, note that each ContentManager has its own FileAliases dictionary, so this code must be applied to the proper ContentManager.

The LoadFromGlobalIfExists is a static variable in the ContentManager class which controls whether FlatRedBall will search in the Global content manager for content even if a file is being loaded from a non-global content manager. The default value is true.

Introduction

ContentLoadBatch is designed to make loading multiple assets more simple. It does this by allowing you to group together all of the resources associated with a single event (ex. all of the Textures for a single level) to be loaded at once. ContentLoadBatch also provides a method for loading these assets in a separate thread on both the PC and Xbox360, making asynchronous loading less to worry about.

Content Tutorial

FlatRedBall Content Manager

Using ContentLoadBatch

Order of Operation

Loading and Unloading assets using ContentLoadBatch consists of four primary steps.

1. Add the filename of each asset to the ContentLoadBatch object.

2. Call the ContentLoadBatch's Load() method to load the content.

3. Use the object's Get method to retrieve the loaded asset.

4. Call ContentLoadBatch's Unload() method to unload the provided Content Manager when you are finished with the loaded assets.

The ContentLoadBatch is meant to operate in this order and will throw exceptions if you, for example, try to call Get() to retrieve an asset after calling contentLoadBatch.Unload().

Code Example

Before running this example, be sure to follow the following steps to ensure the sample runs as intended.

• Download this file (FrblogoHighRes.png) and then drag it into the Content section of the Solution Explorer. It's a larger version of what already exists there, so go ahead and overwrite the file that's currently in the project.

• Select Frblogo.png in the Solution Explorer to view its properties. Change the Build Action to “Noneâ€?, and next to Copy to Output Directory select “Copy if Newer.â€?

The following is an example that demonstrates how to use ContentLoadBatch for both regular and asynchronous asset loading, and demonstrates the difference between the two. Press 1 to load the logo through regular loading, and press 2 to load the logo asynchronously. Pressing 3 will simply remove the logo from the screen.

//Add this in the Game1 class scope
       ContentLoadBatch contentBatch;
       Sprite redBall;
       Sprite background;

       private void LoadFinished()
       {
           background.Texture = contentBatch.Get<Texture2D>(@"Content\Frblogo.png");
       }

//Replace Initialize with this
       protected override void Initialize()
       {

           FlatRedBallServices.InitializeFlatRedBall(this, this.graphics);
           base.Initialize();

           background = new Sprite();
           background.ScaleX = 10;
           background.ScaleY = 5;
           SpriteManager.AddSprite(background);

           redBall = SpriteManager.AddSprite(@"redball.bmp", "Global");
           redBall.X = -10;
           redBall.XVelocity = 20;

           redBall.Y = 0;
           redBall.YVelocity = 20;

           contentBatch = new ContentLoadBatch();
           contentBatch.Add<Texture2D>(@"Content\Frblogo.png");
       }

//Replace Update with this
       protected override void Update(GameTime gameTime)
       {
           FlatRedBallServices.Update(gameTime);
           FlatRedBall.Screens.ScreenManager.Activity();

           if (InputManager.Keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.D1))
           {
               if (background.Texture != null)
                   background.Texture = null;

               if (contentBatch.HasFinishedLoading)
                   contentBatch.Unload();

               if (!contentBatch.IsLoading)
               {
                   contentBatch.Load("BackgroundManager");
                   background.Texture = contentBatch.Get<Texture2D>(@"Content\Frblogo.png");
               }

           }
           else if (InputManager.Keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.D2))
           {

               if (background.Texture != null)
                   background.Texture = null;

               if (contentBatch.HasFinishedLoading)
                   contentBatch.Unload();

               if (!contentBatch.IsLoading)
                   contentBatch.LoadAsync("BackgroundManager", LoadFinished);
           }
           else if (InputManager.Keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.D3))
           {
               background.Texture = null;

               if (contentBatch.HasFinishedLoading)
                   contentBatch.Unload();
           }

           if (redBall.X >= 10) redBall.XVelocity = -20;
           else if (redBall.X <= -10) redBall.XVelocity = 20;

           if (redBall.Y >= 10) redBall.YVelocity = -20;
           else if (redBall.Y <= -10) redBall.YVelocity = 20;

           base.Update(gameTime);
       }

When you run this example, the result should be a blank screen with a single moving ball. Pressing 1 to load the FlatRedBall logo pauses the ball's motion while loading, and pressing 2 loads the image in a separate thread without interrupting the ball's motion.

ContentLoadBatch.Load() vs FlatRedBallServices.Load()

Before ContentLoadBatch, the most common way of loading assets would have been to use multiple calls to FlatRedBall.FlatRedBallServices.Load(). For example, if you wanted to simply load a Texture and apply it in your code, you could do something like the following:

Texture2D ballTexture = FlatRedBallServices.Load<Texture2D>(“redball.bmp”, “ContentManagerName”);
Sprite ballSprite = new Sprite();
ballSprite.Texture = ballTexture;

This method works great for loading just a few assets, or for when you absolutely have to load something on the fly. However, more often than not all of the assets for a scenario will be loaded at once before the user views it. The above code could have to be repeated dozens of times to load additional textures, sounds and other assets.

Alternatively, you can add the filenames of all assets to be loaded to a ContentLoadBatch and then load them all with one call to ContentLoadBatch.Load() or ContentLoadBatch.LoadAsync(). This allows for a more organized approach to managing content for different scenarios. All benefits of using FlatRedBall.FlatRedBallServices.Load, including content caching for previously loaded resources, are maintained as well.

Related Reading

• FlatRedBall Content Manager

• FlatRedBall.FlatRedBallServices.Load

• FlatRedBall XNA Content Pipeline

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

Content managers provide functionality for organizing and caching game assets. They can be thought of as a "bucket of assets". When you create an asset through the Content Manager, you give it a name (usually its file name) and decide which Content Manager it goes into. Later if the same name appears, the FlatRedBall Engine will return a reference to that asset instead of loading it from disk. Although MonoGame has a content manager class by the qualified name of Microsoft.Xna.Framework.Content.ContentManager, you do not have to ever explicitly interact with this class when using FlatRedBall. Instead, you simply work with content managers through the FlatRedBallServices class.

Content Manager and the FlatRedBallEditor

If you are using the FlatRedBall Editor, you may not have to directly interact with the ContentManager object. For example, if you add a .png file to the FlatRedBall Editor, it will automatically load the file in generated code using the ContentManager. However, if you would like to work with content in code, or if your game requires advanced handling of content then you may need to work with the ContentManager in custom code.

What is "caching"?

Computer memory can exist in a variety of locations: On the hard disk, in RAM, or even on the hard disks of other computers which you can access through the Internet (as you are currently doing when viewing this page). Not all types of memory can be accessed with the same speeds. Getting data through the Internet is very slow compared to data that is sitting on your local hard disk, and accessing data on the hard disk is much slower than accessing data in RAM. When the same data needs to be accessed multiple times, making a copy of it and moving it to faster memory can help improve performance. Content such as Textures and Models are copied from the hard disk to RAM to speed up future access to this memory - as well as to prevent duplicate memory in RAM.

What is a Content Manager?

Content managers simplify the loading of new assets as well as help organize existing assets. Content managers in FlatRedBall store references to a variety of assets. The most common type of reference held by content managers is of type Texture2D. Any FlatRedBall method which can potentially load a Texture2D works with FlatRedBall's internal content managers. Content managers are also useful for organizing data. Any data which has the same lifespan - such as textures, geometry, and sound files in a given level - should belong to the same content manager. When the level ends, simply removing that content manager unloads all memory associated with the level. Content managers make memory management and game state changes much easier.

Using Content Managers

If you have programed a FlatRedBall application which displays a texture (such as the red ball texture on a Sprite) then you have worked with content managers - although you may not realize it. Any method which takes a string file name for a Texture2D also takes a string for a content manager name. Some methods have overloads which do not require a content manager string argument, but those simply use the default "Global" content manager. You may be familiar with the SpriteManager's AddSprite method:

Sprite someSprite = SpriteManager.AddSprite("redball.bmp");

This method has an overload which allows the content manager to be specified. Calling the one-argument version is the same as passing "Global" as the second argument:

Sprite someSprite = SpriteManager.AddSprite("redball.bmp", "Global");

The Global content manager is used by default by all methods which load Texture2D's when a content manager is not explicitly supplied in the argument list. To specify a different content manager, simply provide the string of the new name - there is no need to instantiate any instances as this is all handled internally. Loading the same asset using the same content manager does not result in multiple copies of the asset in memory and the hard disk is only accessed once. The following code creates only one copy of the redball.bmp texture in memory.

SpriteManager.AddSprite("redball.bmp"); // in Global by default
SpriteManager.AddSprite("redball.bmp", "Global");
FlatRedBallServices.Load<Texture2D>("redball.bmp", "Global");

While the following creates three separate copies of the redball.bmp texture and also the hard disk is accessed three times:

SpriteManager.AddSprite("redball.bmp", "Some Content Manager");
SpriteManager.AddSprite("redball.bmp", "Other Content Manager");
SpriteManager.AddSprite("redball.bmp", "other content manager"); // case sensitive!

Or another way to look at it is:

Texture2D firstTexture = SpriteManager.AddSprite("redball.bmp", "Some Content Manager");
Texture2D secondTexture = SpriteManager.AddSprite("redball.bmp", "Other Content Manager");
Texture2D thirdTexture = SpriteManager.AddSprite("redball.bmp", "other content manager"); // case sensitive!

if(firstTexture == secondTexture)
{
   // This won't get hit
}

if(secondTexture == thirdTexture)
{
   // This also won't get hit.
}

Content Manager Code Sample

The following code simulates the creation and destruction of 3 levels. Levels can be loaded and unloaded by pressing the 1, 2, and 3 keys. The text object which is created displays the loaded content and the Sprites themselves display the loaded Sprites.

 // Add this using statement:
 using FlatRedBall.Graphics;

 // in class scope
 Text debugText;

 bool[] mLevelLoaded;
 SpriteList mLevel1Sprites;
 SpriteList mLevel2Sprites;
 SpriteList mLevel3Sprites;

 // replace Initialize with this:
 protected override void Initialize()
 {
     FlatRedBallServices.InitializeFlatRedBall(this, this.graphics);

     base.Initialize();

     debugText = TextManager.AddText("");
     debugText.Y = 13;
     debugText.X = -16;
     debugText.Scale = debugText.Spacing = .5f;

     mLevelLoaded = new bool[3];

     mLevelLoaded[0] = false;
     mLevelLoaded[1] = false;
     mLevelLoaded[2] = false;

     mLevel1Sprites = new SpriteList();
     mLevel2Sprites = new SpriteList();
     mLevel3Sprites = new SpriteList();

 }

 // replace Update with the following:
 protected override void Update(GameTime gameTime)
 {
     FlatRedBallServices.Update(gameTime);

     if(InputManager.Keyboard.KeyPushed(Keys.D1))
     {
         if(mLevelLoaded[0] == false)
         {
             Sprite sprite = SpriteManager.AddSprite("redball.bmp", "Level1");
             sprite.X = 5;
             mLevel1Sprites.Add(sprite);
             
             mLevelLoaded[0] = true;
         }
         else
         {
             mLevelLoaded[0] = false;
             FlatRedBallServices.Unload("Level1");
             SpriteManager.RemoveSpriteList(mLevel1Sprites);
         }
     }
     else if(InputManager.Keyboard.KeyPushed(Keys.D2))
     {
         if(mLevelLoaded[1] == false)
         {
             Sprite sprite = SpriteManager.AddSprite("redball.bmp", "Level2");
             sprite.X = 1;
             mLevel2Sprites.Add(sprite);

             sprite = SpriteManager.AddSprite("redball.bmp", "Level2");
             sprite.Y = 5;
             sprite.X = -2;
             mLevel2Sprites.Add(sprite);
             
             mLevelLoaded[1] = true;
         }
         else
         {
             mLevelLoaded[1] = false;
             FlatRedBallServices.Unload("Level2");
             SpriteManager.RemoveSpriteList(mLevel2Sprites);
         }
     }
     else if(InputManager.Keyboard.KeyPushed(Keys.D3))
     {
         if(mLevelLoaded[2] == false)
         {
             Sprite sprite = SpriteManager.AddSprite("redball.bmp", "Level3");
             sprite.X = -3;
             mLevel3Sprites.Add(sprite);
             
             sprite = SpriteManager.AddSprite("redball.bmp", "Level3");
             sprite.Y = 2;
             sprite.X = 4;
             mLevel3Sprites.Add(sprite);

             sprite = SpriteManager.AddSprite("redball.bmp", "Level3");
             sprite.Y = 6;
             sprite.X = -4;
             mLevel3Sprites.Add(sprite);

             mLevelLoaded[2] = true;
         }
         else
         {
             mLevelLoaded[2] = false;
             FlatRedBallServices.Unload("Level3");
             SpriteManager.RemoveSpriteList(mLevel3Sprites);
         }
     }

     debugText.DisplayText = FlatRedBallServices.GetContentManagerInformation();

     base.Update(gameTime);
 }

Which content manager should I use?

Even if you understand the concept that content managers can be thought of as a "bucket of asset", you may be wondering which content manager to put assets in. The following lists a few conditions to help you decide.

• Is your content going to live forever? You may be creating a game with a particular object (such as a Texture2D or a second Camera) that you never want to unload. If this is the case, then you may want to use the global content manager. You can use the FlatRedBallServices.GlobalContentManager property as the value passed to any method that accepts a content manager.

• Are you just debugging? If you are writing code that will not ship with the final game, or if you're just testing something out, then it really doesn't matter what you use. Passing any string will create a new content manager to store the asset. Of course, creating content managers without paying attention to their names can create a buildup of assets if content managers are not cleaned up properly.

• Are you using Screens? The base Screen class defines a property called ContentManagerName. If the object that you're creating should be destroyed when the Screen is destroyed, then you should use the Screen's ContentManagerName.

• Are you creating an object which will be destroyed at some time in the future? If you are not using Screens but still want to perform your own content management (and destruction) then you should place your object in the same content manager as other objects which will be destroyed at the same time. Of course, we encourage the use of Screens as they have been created for this reason and they simplify the management of assets.

Additional Information

• Texture caching example - Shows an example of how Content Managers cache content.

• FlatRedBall.FlatRedBallServices.AddDisposable - AddDisposable can be used to add IDisposables to Content Managers.

• FlatRedBall Content Manager:Multiple Content Managers - Discusses the purpose of having multiple content managers.

Introduction

The PolygonSave class is a "save" object which corresponds to the runtime object.

For more information on the save pattern, see

Creating a PolygonSave

The following code shows how to create a PolygonSave from a Polygon:

Creating a Polygon from a PolygonSave

The following code shows how to create a Polygon from a PolygonSave:

Did this article leave any questions unanswered? Post any question in our for a rapid response.

Introduction

The SceneSave class is a class responsible for loading .scnx files and providing the information in a way that can be used to construct runtime objects. SceneSaves can also be used to save .scnx files easily.

SceneSave vs. SpriteEditorScene

SceneSave is a class that is a replacement for SpriteEditorScene. It is functionally identical, but follows the "Save" naming convention present in the rest of the engine. During this transition you can look at the for information on how to work with SceneSave.

Did this article leave any questions unanswered? Post any question in our for a rapid response.