Introduction

By default FlatRedBall templates display the FlatRedBall icon or the MonoGame icon depending on platform. This article discusses how to add icons to your project.

Desktop GL Windows

A Desktop GL application needs 2 files:

1. .ico - used to display the .exe icon

2. .bmp - used to display the icon on the Windows taskbar

To change the icon on your game's .exe:

1. Open the folder where your .csproj is located. This is the same folder as your Glue file (.glux)

2. Locate Icon.ico

3. Open the Icon.ico to edit it, or replace it with an existing .ico file. Note that the file must still be called Icon.ico.

If you have changed your .ico file you may still see the old icon in Windows Explorer. Windows caches .ico files so you need to clear the cache. For more information see the following link: https://neosmart.net/wiki/clear-icons-cache/ To change the icon in the taskbar and on the window:

1. Open the folder where your .csproj is located

2. Create or replace an Icon.bmp file

3. If not already added:

   1. Add the Icon.bmp to your Visual Studio game project - verify that the file is in the root of the folder

   2. Mark the Icon.bmp file as an Embedded Resource

For more information, see this GitHub discussion: https://github.com/MonoGame/MonoGame/issues/5411 Additional info for DesktopGL: https://github.com/MonoGame/MonoGame/issues/8035#issuecomment-1557429524 And... https://github.com/MonoGame/MonoGame/pull/8036

Introduction

FlatRedBall Web games can be uploaded to itch.io. This guide provides a walkthrough for uploading your game.

Uploading a Build

Once you have published your build through Visual Studio, you should have a folder similar to the following image:

Open the wwwroot and create a .zip file with the contents.

Next, log in to your itch.io account and select the option to Upload new project.

Fill in your project's information, but be sure to set Kind of project to HTML.

Click the Upload Files option and select your .zip file that you created earlier.

Check the This file will be played in the browser option.

You can specify the resolution for your project. Typically you should have your project run at a multiple of your native resolution so that pixels draw correctly. If your game uses a smaller resolution for a pixel aesthetic, you may want to set the resolution at two or three times the native size.

For example, consider a game which is set to a resolution of 398x224:

You can set the game to render at 300% scale by setting the size to 1194x672:

Introduction

FlatRedBall games are distributed similar to any other app for a given platform. In some cases (such as iPhone and Android), a dedicated store exists for distribution. In other cases such as PC games, distribution can be done in a number of ways.

Distributing Windows (Desktop GL) Games

The DesktopGL platform provides the most flexibility for distribution.

Distributing Debug Builds

The easiest way to distribute your game is to package it in a .zip file. When you build your game in Visual Studio, the output window displays the location where the built files are located:

Note that if you are building your game in Glue, the output directory may differ. The location will be displayed in the Build tab when you build and run your game in Glue:

To distribute this game, navigate to the folder where the game is built, select all files, and zip them. You may want to exclude .pdb files, as they can increase the size of your zip file.

This zip file can be sent to others such as testers or friends.

Distributing Release Build

To create a release build, switch your build configuration to Release. If you are linked against prebuilt .dlls or NuGet packages and you would like to include FlatRedBall release packages, see the Release Build page.

Verify that you can build and run your game.

Next, right-click on your game and select the Publish item.

Select Folder unless you know how to publish to the other options.

Once you finish publishing, you can zip the project.

Distributing FlatRedBall Web Games

To distribute a FlatRedBall Web project:

1. Open your project in Visual Studio

2. Switch your project to Release build

   1. If you are linking FlatRedBall nuget packages, instead consider linking to FlatRedBall Source so you can build the engine in release mode. FlatRedBall nuget packages distribute in debug configuration.

3. Select Build -> Publish YourProjectName
4. If asked, select the option to publish to a Folder unless you are familiar publishing with the other options

5. Confirm the folder where you would like to publish, then click Finish

6. Click the Publish button on the Publish tab
7. Wait for your project to finish building

After the project finishes building, click the Navigate link.

The project can be uploaded to any location through FTP. For information on uploading to itch.io, see the itch.io distribution page.

Introduction

By default FlatRedBall games are built to a bin folder which contains the game .exe file, referenced .dlls, and content. If you plan on distributing your game as a .zip file, users may be overwhelmed by the number of files after unzipping.

This can be solved using the probing tag in the app.config file. This guide shows how to use probing to move your game's files into a data folder. Note for .NET 6 users - if your game targets .NET 6 and you include .dlls for .NET 6 so that the user does not need to install the runtimes, this method will not work.

Setting the probing Tag

First, we'll need to decide the name of the sub-folder we want to use for our libraries and data. A common name is data. To add this:

1. Open your project in Visual Studio

2. Open the app.config file.

3. Add the probing tag with the folder name as shown in the following snippet

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2"/>
  </startup>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <probing privatePath="data;"/>
    </assemblyBinding>
  </runtime>
</configuration>

The example above tells the app to look in a data folder for referenced libraries. Note that when picking a folder, you will want to pick one that doesn't already exist in your project's folder structure.

Moving Files to data

Now that the probing tag has been added, the game will look in the data folder for any libraries. Note that the game will continue to look in the main folder as well, so you are not required to move the libraries and content into the data folder until you are ready to distribute your game. Once you are ready, you will want to move every file into the data folder except for the main executable and the config file. Make sure to include your game's content folder and any of the files/folders required by MonoGame such as the x86 and x64 folders.

Once the files have been moved, the only remaining files will be the executable, the config file, and the data folder.

At this point there are only two files left in the root folder, but we can further simplify the folder by hiding the config file:

1. Right-click on the .config file

2. Select properties
3. Check the Hidden property
4. Click OK

Now the config file will be hidden. Note that if your settings are to show hidden files you may still see the file (with a half-transparent icon).

Introduction

By default FlatRedBall templates build the debug configuration. These templates are distributed with release and debug versions of the libraries being used in the project. Therefore, to switch between release and debug you should also switch which set of libraries you are referencing. The steps to switch between debug and release depend on whether the application is linking to prebuilt binaries or source.

Example - Switching DesktopGL Template to Release with Prebuilt Binaries

To switch a DesktopGL template to release:

1. Open your project in Visual Studio

2. Change the configuration from Debug to Relese
3. Expand your project in the Solution Explorer, and expand the References item

4. Right-click on one of the FlatRedBall projects and select Properties
5. In the Properties window, find the location where the FlatRedBall library is located

6. Once the properties window is open, identify all of the libraries which are being being referenced out of your game's Libraries folder.

   In the case of DesktopGL these are:

   1. FlatRedBall.Forms

   2. FlatRedBallDesktopGL

   3. GumCoreXnaPc

   4. StateInterpolation

7. Remove these references from your project by right clicking and selecting Remove
8. After you removed the references, right-click on your project and select Add Reference...
9. Click the Browse... button
10. Navigate to your project's folder. Select the Libraries/DesktopGL/Release folder

11. Add the libraries which were removed in the previous step from the Release folder

12. Click OK

If you are going to build your game in Debug mode, you should link Debug FlatRedBall .dlls. Similarly, if you are going to build your game in Release, you should link Release FlatRedBall .dlls. Mixing Debug and Release may result in compile errors, as FlatRedBall provides additional classes and members in Debug mode which code generation relies upon for improved diagnostics.

Example - Switching to Release With Source

If your project links to FlatRedBall Source, then you only need to switch the configuration of your project:

All libraries should switch to release automatically.

Introduction

FlatRedball games can be distributed on Steam with or without adding code to handle Steam integration. Steam integration can be added using the Steamworks.NET library. This includes support for achievements and responding to the Steam overlay being shown.

Adding Steamworks.NET Library

To add Steamworks.NET library to your project:

1. Go to the Steamworks.NET github releases page

2. Download the latest release standalone
3. Unzip the downloaded file

4. Link the Steamworks.NET.dll file in your project

   1. If you are targeting .NET 6, use the 64 bit version.
   2. If you are making a Desktop GL (.NET Framework) project, be sure to link to the x86 version as this version of FlatRedBall does not support 64 bit builds

5. Copy the steam_api64.dll or steam_api.dll file to the same folder as your game's .csproj (and .gluj) depending on whether you linked to the 64 bit version of Steamworks.NET.dll

6. Add the steam_api file to your project in Visual Studio and mark it as Copy if Newer so that the file ends up in your game's bin folder next to the built .exe.
7. Add your steam_appid.txt file to the folder where your game's exe is located.

8. When testing, be sure to have Steam running or else your tests won't work.

Adding SteamManager

Once the Steamworks library is added to your project, you can interact directly with the library to award achievements and respond to the tab overlay being shown. If you would like to work directly with this library, you can find additional information on the Steamworks github page. The documentation is focused on Unity but many of the concepts apply. Alternatively, the following SteamManager class can be used to set up a project quickly. Note that this is provided to help get a project set up quickly. Future versions of FlatRedBall may provide more integrated solutions such as code gen:

    #region Achievement Class

    abstract class AchievementBase
    {

    }

    class BoolAchievement : AchievementBase
    {
        string AchievementName;
        Func<bool> GetCurrentValue;

        public BoolAchievement(string achievementName, Func<bool> getCurrentValue)
        {
            AchievementName = achievementName;
            GetCurrentValue = getCurrentValue;

        }

        public void TryApply()
        {
            if(GetCurrentValue())
            {
                SteamManager.Self.AwardAchievement(AchievementName);
            }
        }
    }

    class NumericAchievement : AchievementBase
    {
        string ProgressStat;
        Func<long> GetCurrentValue;

        public NumericAchievement(string progressStat, Func<long> getCurrentValue)
        {
            ProgressStat = progressStat;
            GetCurrentValue = getCurrentValue;
        }

        public void TryApply()
        {
            SteamManager.Self.SetStat(ProgressStat, GetCurrentValue());
        }
    }

    #endregion

    #region Achievements list
    class Achievements
    {

        //// start level select screen
        //public static NumericAchievement ExampleAchievement = new NumericAchievement(
        //    "star_one_count", // This is the variable of the achievement
        //    () => MyGameObject.GetCurrentValue() // This is value that the player has obtained so far, like the number of powerups collected
        //    );

    }

    #endregion

    #region SteamManager
    class SteamManager : IManager
    {
        static SteamManager self;
        public static SteamManager Self
        {
            get
            {
                if (self == null) self = new SteamManager();
                return self;
            }
        }

        static bool isInitialized;
        static AppId_t appId;

        static Callback<GameOverlayActivated_t> gameOverlayActivatedCallback;
        static Callback<UserStatsReceived_t> userStatsReceivedCallback;
        static Callback<UserStatsStored_t> userStatsStoredCallback;
        static Callback<UserAchievementStored_t> userAchievementStoredCallback;

        public static Action<bool> SteamOverlayVisibilityChanged;

        public void Initialize()
        {
            // this requires steam_appid.txt in the bin folder, and also that Steam is running
            isInitialized = Steamworks.SteamAPI.Init();


            if (isInitialized)
            {
                //var name = Steamworks.SteamFriends.GetPersonaName();

                appId = Steamworks.SteamUtils.GetAppID();

                SteamUserStats.RequestCurrentStats();

                gameOverlayActivatedCallback = Callback<GameOverlayActivated_t>.Create(HandleOverlayActivated);
                userStatsReceivedCallback = Callback<UserStatsReceived_t>.Create(HandleUserStatsReceived);
                userStatsStoredCallback = Callback<UserStatsStored_t>.Create(HandleUserStatsStored);
                userAchievementStoredCallback = Callback<UserAchievementStored_t>.Create(HandleUserAchievementStored);

                // Example: Gets an achievement by ID
                //var achievement = SteamUserStats.GetAchievementName(2);
                // Example: Gets the number of achievemtns the user has been awarded:
                //var achievementCount = SteamUserStats.GetNumAchievements();
            }
        }

        public void AwardAchievement(string achievementId)
        {
            if (isInitialized)
            {
                SteamUserStats.SetAchievement(achievementId);
            }
        }

        public void SetStat(string statId, long value)
        {
            if (isInitialized)
            {
                var clamped = (int)(Math.Min(value, int.MaxValue));
                SteamUserStats.SetStat(statId, clamped);
            }
        }

        private static void HandleUserAchievementStored(UserAchievementStored_t param)
        {

        }

        private static void HandleUserStatsStored(UserStatsStored_t param)
        {

        }

        private static void HandleUserStatsReceived(UserStatsReceived_t param)
        {

        }

        private static void HandleOverlayActivated(GameOverlayActivated_t param)
        {
            SteamOverlayVisibilityChanged?.Invoke(param.m_bActive > 0);
        }

        public void Update()
        {
            if(isInitialized)
            {
                Steamworks.SteamAPI.RunCallbacks();

            }
#if DEBUG
            // If you want to test awarding achievements, try this:
            //var keyboard = FlatRedBall.Input.InputManager.Keyboard;


            //if (keyboard.KeyDown(Microsoft.Xna.Framework.Input.Keys.LeftShift))
            //{

            //    if (keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.D1))
            //    {
            //        ResetAllStats();
            //    }

            //    if (keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.D2))
            //    {
                    //AwardAchievement(Achievements.Destroy1_5Base);
                    //AwardAchievement(Achievements.Research15Creatures);
                    //AwardAchievement(Achievements.Research30Creatures);
                    //AwardAchievement(Achievements.Research45Creatures);
            //    }

            //}
#endif
        }

        internal static void StoreStats()
        {
            if (isInitialized)
            {
                SteamUserStats.StoreStats();
            }
        }


#if DEBUG
        private static void ResetAllStats()
        {
            const bool resetAchievements = true;
            SteamUserStats.ResetAllStats(resetAchievements);
        }
#endif

        internal void Exit()
        {
            SteamAPI.Shutdown();
        }

        void IManager.UpdateDependencies(){}
    }

    #endregion

steam_appid.txt

The steam_appid.txt file is a text file which is added to the same location as your game's .exe file. It is a text file which should contain only your app ID (which is a 7 digit number at the time of this writing, but may increase to 8 or 9 digits in the future). Note that creating the file in Visual Studio may add a byte order mark which makes your file unreadable by the Steam api, so create the file as a plain text file through Windows Explorer.

SteamManager Setup

To use the SteamManager:

1. Add SteamManager.Self.Initialize(); to Game1 constructor

2. Add SteamManager.Self.Update(); to Game1 Update

3. Add SteamManager.Self.Exit(); to Game1 OnExiting (you may need to manually override this method in your game)

Handling SteamManager Steam Overlay

Normally games should be paused when the Steam overlay is shown. Games which use GameScreen as their base class for all levels can respond to the SteamManager's SteamOverlayVisibilityChanged event by pausing. For example, the following code snippet could be used to pause the game:

void CustomInitialize()
{
   ...
   SteamManager.SteamOverlayVisibilityChanged += HandleSteamOverlayVisibilityChange;
}

private void HandleSteamOverlayVisibilityChange(bool isSteamOverlayVisible)
{
    if(isSteamOverlayVisible && !IsPaused)
    {
        // This will pause the screen, but you may want to call your own custom pause function to handle showing menus
        // or other game-specific logic
        PauseThisScreen();
    }
}

void CustomDestroy()
{
    SteamManager.SteamOverlayVisibilityChanged -= HandleSteamOverlayVisibilityChange;
}

Defining Achievements

Steam achievements are handled in two places:

1. The achievements must be defined in the Steam dashboard for your game

2. Achievement logic must be added to your game

If using the SteamManager, the second point is fairly easy to do:

1. Find the Achievements class in the code above

2. Follow the example achievement to create your own achievement. Note that this pattern requires access to the game data, such as the profile information which may have values controlling whether an achievement has been fulfilled

3. In game code, call TryApply on achievements which may be achieved in response to certain game events. You may choose to award achievements the moment they are awarded, or at certain points of the game execution (such as the end of a level)

For example, consider an achievement which is awarded when the player has collected all possible power-ups in a game. This may be checked in the collision function between PlayerList and PowerUpList as follows:

Achievements.PowerUpCollection.TryApply();

The TryApply method performs a local check for awarding before sending anything to Steam, so making these calls frequently will typically not cause performance problems. Of course, be aware of situations where the checking of an achievement requires time intensive checks, such as loading files from disk or performing a large number of calculations.

.NET 6 Self Contained Builds

If your game uses .NET 6 or newer, then it can be published as a self-contained app which includes all of the .NET 6 runtime files. While this increases the size of your game, it enables your game to run on any machine regardless of whether .NET 6 runtime is installed. Furthermore, it allows your game to run on SteamDeck. To do this, first add the following highlighted text to your csproj under the PropertyGroup tag.

Once you have done this, you can publish your application using the dotnet publish command or you can grab the files from the bin folder that Visual Studio creates.