Introduction

FlatRedBall supports creating games which run on Android devices. Aside from Android-specific capabilities, FlatRedBall Android development is nearly identical to developing games for other platforms. As of April 2024 FlatRedBall Android projects use .NET 8 which provides access to a much wider set of features and nuget packages compared to the previous Xamarin-based version.

Prerequisites

FlatRedBall Android game development requires a Windows PC just like regular PC game development as well as Visual Studio 2022 or newer.

Primary Android vs. synced Android projects

As mentioned in the Multi-Platform page, the recommended approach for creating full game projects is to create a primary desktop project with a synced Android project. However, if you are evaluating FlatRedBall, or creating a small test project, you may want to create a primary Android project. Both approaches are discussed below.

Creating a primary Android project

Creating an Android project is essentially identical to creating any other platform:

1. Open the FlatRedBall Editor

2. Select File->New Project

3. Enter a project name

4. Set the Platform to Android .NET

5. Click Create project!

Select the desired project type in the wizard, or close the wizard to begin with an empty project. Click the Visual Studio icon to open the project in Visual Studio:

Now that the project is in Visual Studio, you can develop an Android game the same as if you were making a PC game, including using the FRB Editor. To launch the game:

1. Select the target device

   1. If you have a physical phone, you can connect it to your computer. You need to enable your phone for development by turning on developer mode. For more information see the Microsoft page for setting up an Android device: https://learn.microsoft.com/en-us/dotnet/maui/android/device/setup?view=net-maui-8.0

   2. If you do not have a physical phone, or if you prefer to use an Android emulator, see the following page on how to set up an Android emulator: https://learn.microsoft.com/en-us/dotnet/maui/android/emulator/?view=net-maui-8.0

2. Verify that the Play button in Visual Studio has the desired emulator or device selected. Note that if a physical Android device is connected to your computer and is set up for debugging, then Visual Studio will detect it as a deployment option.

3. Press the Play button

Creating a synced Android project

Synced Android projects are created just like any other synced project. The first step is to create a regular Windows Desktop project. Once the project is created a new synced Android project can be created as follows:

1. Open FlatRedBall

2. Select Project->View Projects

3. Click the New Synced Project button

4. Select the Android option

5. Enter a project name

6. Click Make my project!

The project will take a moment to download and be created, but once it is, you should see the Android project listed in the Androids project list. Since your FlatRedBall project now has multiple platforms, you can choose which project to open through the Projects tab.

Releasing an Android Project

To create an Android APK, whether for internal testing or for final release, see the Microsoft release documentation.

Troubleshooting

Unfortunately deploying to Android can be fickle at times, and sometimes no errors are provided.

App crashes immediately

If your app crashes immediately without a call stack, then you may want to try the following:

• Does the app work on Android hardware? Sometimes an app will not work on emulator but will work on hardware

• Have you tried creating a .NET MAUI? MAUI projects can be created with templates which are part of Visual Studio, so they are likely to eliminate common problems in template setup. If a MAUI project doesn't work, then that might mean that prerequisites are not properly installed.

FlatRedBall supports developing games on multiple platforms. As of the time of this writing the following platforms are supported:

• Desktop

  • Windows

  • Mac

  • Linux

• Android

• iOS

• Consoles (Switch, Xbox) through the use of FNA and Native AOT compilation

• Web

Selecting Platforms

Your project's platform is selected when first creating a new project. A newly-created project selects a primary platform, which defines the primary project.

The primary project should be a desktop-based project (either MonoGame .NET Desktop GL or FNA at the time of this writing) even if you intend to target other platforms such as Android or consoles. Selecting a Desktop project as the primary project provides a number of benefits:

• Superior debugging

• C# Edit-and-continue

• FlatRedBall Editor Live Edit support

• Faster compilation and deployment

• Ability to add new platforms at any time

Adding Additional Platforms Using Synced Projects

FlatRedBall provides the concept of synced projects - these are projects which are created by the FlatRedBall Editor which are kept synced with the primary project. In other words, whenever a new Entity, Screen, or file is added through the FlatRedBall Editor, the synced project is updated to include the same code and content files. The FRB Editor also updates the files as necessary for each platform. For example, on PC a file may be set to copy to the output folder, while on Android it is set to an Android Asset.

Files which are manually added to a project (either synced or primary) are considered platform-specific and are not automatically synced. Of course, you are free to link these files manually through Visual Studio.

Conditional Compilation Symbols

FlatRedBall attempts to be as cross platform as possible. From time to time you may encounter code which is only available on one platform, especially if you are using 3rd party nuget packages. Therefore, you may need to exclude certain code from platforms.

For example, the following code could be used to perform logic which is specific to web or desktop:

The following compilation symbols are available:

• ANDROID

• FNA (not a platform, but can still be checked)

• DESKTOP_GL

• IOS

• WEB

You can also add your own conditional compilation symbols to the .csproj, and may are available automatically through .NET such as NET8_0_OR_GREATER

Introduction

Synced Projects provide a way to create and keep multiple projects in sync when working with multiple platforms. Typically the main project is a DesktopGL project, and synced projects would be for other platforms such as Android or Web.

To open a project, click on the icon for the IDE for a given project. For example, the following icon can be used to open the TownRaiser XNA 4 Project:

New Synced Project

New platforms can be added to an existing project at any point in development by adding a new synced project. To add a new synced project to an existing Glue project:

1. Open the Projects tab

2. Click the New Synced Project button

3. The FlatRedBall Project Creator will appear. Select the desired platform (such as Windows UWP)

4. Enter a name for the project. Typically the name matches the original project's name with the platform appended. For example, TownRaiserUwp.

5. Click the Make My Project! button.

After creating the new synced project, it appears in the Projects tab.

Since FlatRedBall is designed to be syntactically identical across all platforms, most new synced projects will compile and run with little or no modifications.

Synced Project Behavior

New Synced Projects are created using a standard FlatRedBall template for the given platform. In other words, a synced project references FlatRedBall for the given platform in the same way as a new project.

Synced projects can reference pre-built FlatRedBall .dlls (directly or using NuGet), or they can be linked to FlatRedBall source. The following screenshot shows a FlatRedBall Web project linking to the FlatRedBall Engine.

Synced projects automatically link all source files from the original project. This includes custom and generated code for screens, entities, and global content.

Content files are also linked by the synced project.

NuGet packages are not automatically synced across projects so if you have manually added a NuGet package to your main project, you may also need to add the same package or an alternative package to your synced projects.

To create FlatRedBall Android projects, you must:

1. Install Visual Studio as explained on the FlatRedBall Downloads page.

2. In the Visual Studio Installer, check Mobile development with .NET
3. If it isn't already installed, click the button to install

4. Wait for the installation to finish.

Once you have finished installing, you can verify that you have Xamarin installed:

1. Open Visual Studio

2. Select Create a new project

3. Search for Xamarin to make sure that Xamarin is installed. If you see search results for Android or iOS development, then it is installed

Introduction

This tutorial will walk you through the steps of creating a FlatRedBall iOS project on the PC then copying it to the Mac. Note that unlike most other FlatRedBall platforms, FlatRedBall iOS requires commercial software and a computer running OSX along with a computer running Windows.

Specifically, the requirements are:

• A computer running Windows. This computer will have the typical FlatRedBall installation and will run Glue.

Same-network is preferred

Be sure that you can open a Windows Explorer window to view your Mac files on the PC before proceeding. If you cannot, attempt the following:

Enabling Windows File Sharing

Make sure that Windows file sharing is enabled on your mac. To do this:

1. Click the Apple icon in the top left of the screen and select "System Preferences"

3. Click "Options..."

5. Click Done

Navigating to the Mac using its IP

1. Open a Windows explorer window

2. In the address bar type your Mac's IP as reported in the sharing window. For example, in this picture the IP is 192.168.0.15, so the address bar would have
3. You may be asked to log in. Use the login name as specified in the Windows File Sharing screen (including spacing). For example, the username as specified in this window is

Creating a FlatRedBall iOS project on Windows

Creating the project for iOS is identical to creating projects for other platforms:

• Start Glue

• Select File->New Project

• Select FlatRedBall iOS as the project type

• Enter the name that you want for your project

• Click OK

The next step is to set up Glue to copy the project over to your OSX computer.

Glue Project Copier

Once you can access the file system on OSX, you can tell Glue to copy the project over to the desired location. To do this:

If you have a large project, you may notice that the copy process can be lengthy. Don't worry, the project copier checks the dates on files when performing copying. This means that subsequent copies will go much faster!

Running the project

At this point the project is fully copied to the OSX computer and it can be run there. This assumes that you have the proper Xamarin software installed.

To do this:

1. Open Xamarin Studio

Making changes in Glue

Making changes on OSX

Since the projects are copied from Windows to OSX, if you make changes on the OSX side of things - such as by modifying .cs files, then you will need to migrate those changes back to PC.

This can be done through the Glue plugin by swapping the "Copy From" and "Copy To" folder. Note that the "Custom Folder" radio must be checked to enter a value in the "Copy From" section.

Keep in mind that the entire folder structure is copied when the "Copy Projects!" button is checked, so changes from the "From" folder will overwrite changes in the "To" folder. We recommend taking advantage of version control software to back up your project to prevent unintentional overwriting of data.

Introduction

FlatRedBall support development for iOS (iPhone and iPad) using .NET 8 (as of March 2024).

Creating a New iOS Project

To create a new iOS project, launch the FlatRedBall Editor, create a new project, and select iOS as your target platform.

Troubleshooting

The MinimumOSVersion value in the Info.plist (11.0) does not match the SupportedOSPlatformVersion value (11.2)

You may see the following when deploying your project:

The MinimumOSVersion value in the Info.plist (11.0) does not match 
the SupportedOSPlatformVersion value (11.2) in the project file 
(if there is no SupportedOSPlatformVersion value in the project 
file, then a default value has been assumed). Either change the 
value in the Info.plist to match the SupportedOSPlatformVersion 
value, or remove the value in the Info.plist (and add a 
SupportedOSPlatformVersion value to the project file if it doesn't 
already exist).

Verify that your Info.plist Deployment Target matches your csproj's SupportedOSPlatformVersion.

Additional Information

• If you have a NullReferenceException in Microsoft.Xna.Framework.Audio.OpenALSoundController.Update, and you are playing on the simulator, verify that audio is working properly on your Mac.

• For information on errors playing SoundEffects and SounEffectInstances see the SoundEffectInstance page.

Introduction

FlatRedBall iOS projects (including Glue projects) can be developed in Visual Studio and deployed to an iOS device through a networked Mac using Xamarin Build Host. This is the fastest way to develop iOS gams but it does require a Xamarin Business License (which is more expensive than Xamarin Indie License).

This article shows how to use Xamarin Build Host to deploy a FlatRedBal iOS game.

Xamarin Build Host Setup

Before deploying you must have your Mac and PC computers configured for Xamarin Build Host. Xamarin provides a guide for getting Xamarin Build Host set up here: http://developer.xamarin.com/guides/ios/getting_started/installation/windows/introduction_to_xamarin_ios_for_visual_studio/

Creating an iOS Project in Glue

Creating a FlatRedBall iOS project through Glue is nearly identical to creating a PC project:

1. Open Glue

2. Select File->"New Project"

3. Select "iOS" as the project type

4. Enter a name

5. Click "Make my project!"

Once the project has finished downloading it can be opened in Visual Studio. Visual Studio should display UI for the Xamarin Build Host:

Running the project

As shown in the Xamarin guide above, running the app simply requires running from Visual Studio just like normal. Of course, the app will run on simulator or physical iOS device depending on your settings:

Introduction

Android builds can be distributed using a digital store (such as Google or Android), or can be manually distributed by distributing a .apk.

Before you perform any distribution, you must create a release build of your app.

Creating a Release Build

The following will walk you through creating a release build. Release builds can be created for any FlatRedBall Android project, including synced Glue projects. This walkthrough assumes that you have an Android project which you have been able to successfully deploy to device through Xamarin Studio or Visual Studio.

Switching to a Release Build

If using Xamarin Studio, change the configuration to release:

Release builds are required for distributed .apk files.

Linking the Release FlatRedBall DLLs

Distributed builds also require linking against the release build of FlatRedBall. If using the .dll files which are distributed with the FlatRedBall templates (default), then your project will already have the release files downloaded.

These can be found in your project's Libraries folder:

To link the release files in Xamarin Studio:

1. Right-click on your game project's References

2. Select "Edit References..."

3. Select the ".Net Assembly" tab

4. Un-check the FlatRedBallAndroid.dll file

5. Click the "Browse..."

6. Navigate to the <project folder>/Libraries/Android/Release folder

7. Select FlatRedBallAndroid.dll and click Open

8. Verify that the release build of FlatRedBall is added and click OK

Once this library has been added, build and run your project to make sure everything is working fine.

Setting Supported Architecture

The project needs to specify the architectures it will support. Unless you are concerned about file size, you should support all architectures. To do so:

1. Right-click on your project

2. Select "Options"

3. Select the "Android Build" option

4. Click the "Advanced" tab

5. Check the desired supported architectures:

Creating an APK

The .apk file is what you need to distribute to test it on other phones. In Xamarin Studio:

1. Select "Project" -> "Create Android Package..."

2. Enter a name in the "File:" text box for the desired .apk file name

3. Click OK

Distributing the APK File

Once the .apk file has been created it can be distributed through any digital means, such as google drive, drop box, or sending the file through email.

Android Linking

Xamarin's Android compiler includes a feature which allows selective inclusion of libraries, classes, and members. This feature can reduce the size of a game, but also can introduce crashes which can be difficult to diagnose - at least unless you know what to look for.

The most common type of crash occurs when deserializing XML files, such as emitter .emix files. If your program runs fine in debug but crashes in release, then it may be related to Xamarin's linking behavior. You can verify that this is the case by looking at the output window. For example, the following error appears when trying to load a .emix file.

There was an error reflecting type 'FlatRedBall.Content.Particle.EmitterSaveList'. ---> 
System.InvalidOperationException: There was an error reflecting field 'emitters'. ---> 
System.InvalidOperationException: There was an error reflecting type 'FlatRedBall.Content.Particle.EmitterSave'. ---> 
System.InvalidOperationException: There was an error reflecting field 'ParticleBlueprint'. ---> 
System.InvalidOperationException: There was an error reflecting type 'FlatRedBall.Content.Particle.ParticleBlueprintSave'. ---> 
System.InvalidOperationException: FlatRedBall.Content.Particle.ParticleBlueprintSave cannot be serialized because it does not have a default public constructor

One way to solve this problem is to adjust the linking behavior, which can be done as follows:

1. Right-click on the project in the Solution Pad

2. Select "Options"

3. Select the "Android Build" category

4. Click the "Linker" tab

5. Change "Link all assemblies" to either "Link SDK Assemblies only" or "Don't link"

6. Try running again and see if the crash occurs

The downside to this solution is that these will increase the size of your APK file.

For more information on linking, see this article.

Introduction

iOS development requires the use of Provisioning Profiles to deploy to iOS hardware, either for development or for final distribution. This section will discuss how to create and use provisioning profiles.

Troubleshooting

The provisioning profile is error prone due to its complexity. If you are unable to get things to work here are some things to try:

Verify Bundle Identifier

Provisioning profiles are tied to a certain bundle identifier. Verify that the bundle identifier of your app matches the bundle identifier in the provisioning profile.

Introduction

FlatRedBall can be used to develop games for the Nintendo Switch. To develop games for the Nintendo Switch, your game should be using the FNA platform. To deploy to the Nintendo Switch you must:

• Target .NET 7 or newer

• Verify that your project compiles and runs using Native AOT

FNA vs MonoGame

Both FNA and MonoGame can technically be used to develop games for the Nintendo Switch; however, the FNA path has a number of benefits:

1. FNA allows the use of modern .NET versions (7+). MonoGame requires translating code to C++ using BRUTE which does not support modern .NET and C# features. This is currently being worked on by the MonoGame team, but as of May 2024 there is no AOT solution.

2. As of December 2023, FlatRedBall MonoGame has yet to run on the Nintendo Switch. FlatREdBall FNA demos have been successfully deployed to switch.

3. The MonoGame team which was responsible for console support has been less active since 2021. The FNA team continues to be active as of December 2023.

4. More games have been deployed to consoles recently using FNA rather than MonoGame as of December 2023.

5. Internally, the FlatRedBall team is testing FNA and will provide support to any games which run into problems with FNA.

Introduction

FlatRedBall supports web projects using Blazor Web Assembly and WebGL. Web projects use C# just like other FlatRedBall platforms. Web projects can use the FlatRedBall Editor, almost all FlatRedBall features, and support synced projects.

FlatRedBall Web uses the Kni framwork, which is an XNA-like framework supporting Blazor WASM projects. Fortunately, this means that FlatRedBall and XNA code should work the same on Web as on other platforms, reducing the amount of code changes needed when migrating from other platforms to Web.

Installing Kni

Before creating a FlatRedBall Web project, you must install Kni. The latest binaries can be found on the Kni release page: https://github.com/kniEngine/kni/releases

Creating a FlatRedBall Web Project

FlatRedBall Web projects can be created as standalone (primary) projects, or as synced projects. For more information on how to create a synced project, see the View Projects page. In other words, you can create a new project (File -> New Project) or you can add a new web synced project.

Whether you create a new project or use a synced project, you can select Web as the target for your new project.

Once you have created a Web project you can use the FlatRedBall Editor as if it's a regular Desktop project. For known limitations see the section below.

To run your project:

1. Open the project in Visual Studio
2. Press the button to begin debugging your project in Visual Studio

3. A browser should appear running your game project

Debugging

FlatRedBall Web projects can be debugged in a number of ways:

• To output to the browser console, use System.Console.WriteLine just like a normal console application. Note that output from this method appears in both the browser's console as well as Visual Studio's output window.

• Breakpoints should function the same as normal FlatRedBall projects; however, as of .NET 8 at times stepover will step over a large block of code or may even freeze the application. This may be improved in future versions of .NET.

Exceptions in Update

Exceptions in the Update of your game (which includes all generated and CustomActivity calls) may not result in Visual Studio breaking on exceptions. Instead, this can result in your game displaying a purple window. To solve this problem you can wrap your Game's Update call in a try/catch. If you are concerned about modifying your game for other platforms, you can do this only in web, as shown in the following block of code:

// In Game1.cs
        protected override void Update(GameTime gameTime)
        {
#if WEB
            try
            {
#endif
                FlatRedBallServices.Update(gameTime);
                FlatRedBall.Screens.ScreenManager.Activity();
                GeneratedUpdate(gameTime);
                base.Update(gameTime);
#if WEB
            }
            catch(Exception e)
            {
                System.Console.WriteLine(e);
                throw;
            }
#endif
        }

You can place a breakpoint in the catch block to also stop execution when an exception occurs.

Cannot read properties of null (reading 'getAttribute')

This exception can occur when running FlatRedBall Web projects.

You can disable JavaScript exceptions to silence this error.

If you do encounter this problem, you can press F5 or continue execution and the game will run normally. This exception will not cause any problems for deployed games.

Known Limitations

As of August 2024 FlatRedBall Web is a new platform. The following are known limitations of the platform. Over time more limitations will be discovered, while some may be solved. For more information please check the FlatRedBall Discord server.

Gamepad

• Switch controllers are not supported. Xbox One controllers have been tested and work correctly

• Setting controller vibration is not supported

Audio

• The user must interact with the browser before audio plays. We recommend a loading/title screen that asks the user to click to continue

File IO

• Local saving and loading of files cannot be performed with the standard System.IO.File operations

Camera/Resolution

• The browser determines the size of the game. Unlike regular DesktopGL projects, FlatRedBall cannot forcefully change the browser size. Of course, FlatRedBall properly reacts to resolution changes on a browser including maintaining the internal resolution and aspect ratio.

Debugging