FileVersion (.gluj)

Introduction

Modern FlatRedBall projects are saved as a collection of json files. The root file uses the .gluj (Glue JSON) extension. Screens use the .glsj (Glue Screen JSON) extension while entities use the .glej (Glue Entity JSON) extension. Note that older FlatRedBall projects use an XML format with the extension .glux and use only a single file for the entire project.

This document discusses details about the glue data files. Versions which display the green checkbox ✅ can typically be upgraded to without any additional modifications to the project. Versions which display the red exclamation ❗ typically require modifications to a project to prevent compile or logical errors.

Gluj Versions

The main Glue file (gluj for modern projects) contains a file version. This version is used by the FlatRedBall editor to determine which features to enable and disable. Generally new file versions are created whenever a feature is introduced which may break old projects. Old projects can be manually upgraded to a new version, but each upgrade may require manual changes. The property controlling the file version is FileVersion. For example, the following project is using file version 11:

"FileVersion": 11,

To upgrade to a new version, the gluj/glux file can be opened in a text editor and manually updated.

Important: Upgrades may require additional changes to a project as described below. Furthermore, upgrading may have unexpected consequences, so using version control to undo large changes is recommended. Upgrades should be performed one version at a time rather than multiple versions at once.

Version 1

This is the initial version which began tracking FileVersion.

Version 2 - Adds Game1.Generated.cs

This version introduces Game1.Generated.cs which enables additional code to be injected into Game1 without the risk of introducing errors in custom code.

❗ To update to this version you may need to remove portions of code from Game1.cs which are handled by Game1.Generated.cs. Review the generated code and compare it with your custom code.

Version 3 - Automatic List-Factory Association

This version automatically associates Lists in Screens with their corresponding factories. Older games may manually associate the lists with factories.

❗ To upgrade to this version, remove custom code which associates lists to factories to prevent double-adds. Also, note that you need to check your screens to make lists in the screens have AssociateWithFactory set to true on any items you wish to have associated with factories. This is default to true on newer projects, but older projects may not have this set to true automatically.

Version 4 - Gum GUE GetAnimation Method and FlatRedBall.Forms

This version introduces FlatRedBall.Forms and the GetAnimation method to Gum objects.

✅ To upgrade to this version, either link to the FlatRedBall Engine source code and update the repository, or update the pre-built binaries through the FlatRedBall Editor.

Version 5 - CSV (state) Inheritance support

CSVs can now inherit from other CSVs. This is used to allow derived platformer and top-down objects to access movement variables defined in their base classes.

✅ To upgrade to this version, either link to the FlatRedBall Engine source code and update the repository, or update the pre-built binaries through the FlatRedBall Editor.

Version 6 - Added nuget references in template csproj files

New FlatRedBall csproj files now have nuget packages as part of the csproj enabling the FlatRedBall Editor to modify these. As of version 6 this is only used to add Newtonsoft Json.Net for live editing.

❗ To upgrade to this version, manually add the Newtonsoft.Json nuget packages to your project.

Version 7 - Added edit mode

Edit mode is now enabled. This adds a lot of generated files enabling the editor to communicate with the game, and the game automatically opens a port for the editor to connect.

Version 8 - Screens and entities have partial CustomActivityEditMode

This adds a new function to screens and entities (partial).

✅ No changes are needed to upgrade to this version since these changes have no side effects on a game. The new methods are partial so no modifications are necessary to custom code.

Version 9 - Glue file changed from .glux to .gluj

FlatRedBall Editor now saves its files in json format rather than xml.

✅ To upgrade to this, open the glux file and change file version to 9, then open the FlatRedBall editor. Note that the glux file will not be deleted and will remain on disk. The editor prefers to load gluj if one exists, and if not, it falls back on glux.

Version 10 - Added IEntity base interface for entities

This adds code generation to implement the IEntity interface for all entities.

✅ To upgrade to this version, either link to the FlatRedBall Engine source code and update the repository, or update the pre-built binaries through the FlatRedBall Editor.

Version 11 - Separated Screens into glsj and entities into glej files

This version separates all screen and entity data into their own json files. This change reduces the chances of destructive merge conflicts.

✅ To upgrade to this version, either link to the FlatRedBall Engine source code and update the repository, or update the pre-built binaries through the FlatRedBall Editor. Versions manually converting to this should first upgrade to version 9. Once a project is on version 9 or higher, it can safely be upgraded to version 11 and FlatRedBall will automatically break apart the main json file into separate Screen/Entity json files.

Version 12 - Automatic AnimateSelf Call on Gum Screens

This version automatically adds the AnimateSelf call on Gum screens. For example, a project may have the following added to Screen Activity methods:

if (!IsPaused)
{
    MainMenuGum?.AnimateSelf();
}

❗ Projects updating to this version should remove custom calls to their GumScreen's AnimateSelf, or explicit AnimateSelf calls on any component instances owned by Gum screens, otherwise animation logic will run multiple times per frame.

Version 13 - Removal of Game1 Generated Camera and StartUp Screen

This version removes the generation of startup screen and camera setup from Game1.cs into Game1.Generated.cs. Projects upgrading to this version should remove code from Game1.cs Initialialize which sets the startup screen and which calls CameraSetup.SetupCamera. For example, before a change, Game1 Initialize may appear as shown in the following snippet:

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

    FlatRedBallServices.InitializeFlatRedBall(this, graphics);

    GlobalContent.Initialize();

                CameraSetup.SetupCamera(SpriteManager.Camera, graphics);
    Type startScreenType = typeof(CrankyChibiCthulu.Screens.VicLevel1);

    var commandLineArgs = Environment.GetCommandLineArgs();
    if (commandLineArgs.Length > 0)
    {
        var thisAssembly = this.GetType().Assembly;
        // see if any of these are screens:
        foreach (var item in commandLineArgs)
        {
            var type = thisAssembly.GetType(item);

            if (type != null)
            {
                startScreenType = type;
                break;
            }
        }
    }

    // Call this before starting the screens, so that plugins can initialize their systems.
    GeneratedInitialize();

    if (startScreenType != null)
    {
        FlatRedBall.Screens.ScreenManager.Start(startScreenType);
    }


    base.Initialize();
}

After the change, Game1 Initialize may appear as shown in the following snippet

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

    FlatRedBallServices.InitializeFlatRedBall(this, graphics);

    GlobalContent.Initialize();

    GeneratedInitialize();

    base.Initialize();
}

This change brings the following benefits:

  • Changes to the StartUp screen no longer modify custom code, reducing the chances of having merge conflicts

  • This change enables generated code to handle parameters for camera and resolution setup, which will be used when the game is started embedded in the game window

  • Establishes a pattern for additional startup functionality which will be added in future versions.

❗ To update to this version, modify Game1.cs as shown in the code snippet above.

Version 14 - Remove LocalizationManager.Translate Calls on Variables

FlatRedBall Editor supports localization through CSV files. If a localization file is added, then it will attempt to localize string variables. The current implementation is problematic for a few reasons:

  1. It is inconsistent - some variables are assigned and some aren't. Of course, this inconsistency could be fixed, but it would take some time.

  2. Sometimes variables should not be localized. It is common to create string variables for types which are enums at runtime, but are not available in the FRB Editor. When a localization file is added, all of these values will get set to localized values, and this can break a game in unexpected ways.

  3. Localization may not be desirable on some strings. For example, text objects which display health or currency should not be localized.

  4. Localization has no support for string interpolation. This requires code to perform properly.

  5. The Gum tool supports localization files. This is where most games should perform their localization, not in the FlatRedBall editor.

Rather than completely shutting off localization in the FRB Editor, a new version is being added since it introduces a breaking change.

❗ To update to this version, you must manually add calls to LocalizationManager.Translate wherever generated code was doing so. This can be done by doing a search in generated code and identifying where this occurs. Once this version is enabled, all generated code will not contain LocalizationManager.Translate calls, so these must be done manually in code as necessary. Note that the call to LocalizationManager.AddDatabase will still be done by generated code if a localization CSV has been added to the editor in Global Content. For more information on localization, see the LocalizationManager page.

Version 15 - Sprite Has UseAnimationTextur