gluj/glux

Introduction

FlatRedBall Glue projects are saved in either gluj (Glue JSON) or glux (Glue Xml) files. Furthermore, new projects also save their screens in glsj (Glue Screen JSON) and entities in glej (Glue Entity JSON) files.

This document discusses details about the glue data files.

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.

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. If so, games which upgrade to this version should remove custom code which associates the two to prevent double-adds.

Version 4 – Gum GUE GetAnimation Method and FlatRedBall.Forms

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

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.

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.

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). Upgrading to this version should have no side effects on a game as the method itself is 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. Projects which use pre-built .dlls should upgrade the .dlls before moving to this version. Projects which reference FlatRedBall source code can safely upgrade to this version as long as the code is updated.

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. 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.

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. Localization is being added directly to Gum where most localization should happen.

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 UseAnimationTextureFlip Property

The UseAnimationTextureFlip property was added to the FlatRedBall Source on April 1 2022. The FRB Editor needs to know if this property exists in the engine so it can be shown in the property grid. If not, then it should not be shown.

To update to this version, either link your game against FRB source and update the source, or update libraries to get the latest libraries which include Sprite.UseAnimationTextureFlip.

Version 16 – Remove IsScrollableEntityList

The IsScrollableEntityList property is an old property which has not been maintained or tested for many years. It is likely broken and similarly, modern projects probably do not use this property. Furthermore, this property mainly existed to support lists which are now handled by FlatRedBall.Forms. Therefore, this is being removed from the UI in Version 16. Earlier file versions will still display this property, but it may not work correctly.

To upgrade to this version, verify that you do not rely on this functionality. No other work is needed.

Version 17 – ScreenManager has PersistentPolygons

The FlatRedBall engine now has a PersistentPolygons list which can be used to keep Polygons persistent across screens without throwing errors. This is used by the edit-mode to display the selection. If this is false, then the polygon is not made persistent, and edit mode can crash when switching between screens. However, this is only needed if running in edit mode. Games which do not develop in edit mode do not need this.

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 18 – Sprite has TolerateMissingAnimations

Normally when assigning a Sprite’s CurrentChainName, if the animation is not present the code throws an exception. This can be problematic when in edit mode. This version allows the generation of Sprite.HasTolerateMissingAnimations to false when going into edit mode so that the game does not crash when assigning missing animation names.

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 19 – AnimationLayer has Name and IPlatformer is Generated

AnimationLayer has Name

This version results in the PlatformerAnimationController generating AnimationLayers and assigning their Name property. Older versions of the FlatRedBall engine did not include a Name property.

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.

IPlatformer is Generated

This version also generates the IPlatformer interface into projects. This is used to apply the new Platformer AnimationController. Projects which do not use the Platformer entity type will not be impacted by this change.

To upgrade to this version, make sure you do not have an existing IPlatformer interface in your project. If so, you may get class/namespace conflicts.

Version 20 – New Default FlatRedBall.Forms Components

This version introduces a new set of FlatRedBall.Forms controls.

These controls provide more flexibility, and the defaults are cleaner and look better overall. New FlatRedBall projects will automatically add these controls when Gum/Forms is added (usually through the wizard).

Upgrading to this version is safe under a number of conditions:

  1. If you do not intend to use FlatRedBall.Forms at all, then you can safely upgrade to this version.
  2. If you have not yet added FlatRedBall.Forms to your game project, you can upgrade to this version first, and then add FlatRedBall.Forms through the Gum tab by selecting the .gumx file.
  3. If you have already added FlatRedBall.Forms to your project, you can upgrade to this version if you do not intend to re-create all of the default forms controls. Upgrading to this version will not do anything to your project unless you re-add all controls through the Gum tab.
  4. If you have already added FlatRedBall.Forms to your project and would like to replace existing .Forms controls, you can delete all default controls from your project and then re-add all Forms controls through the Gum tab. You may also be able to add all controls without deleting your existing default controls, but this has not been tested, so do so with the ability to undo your changes using version control.

Version 21 – Support for IStackable

This version introduces support for the IStackable interface.

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 22 – ICollidable has ItemsCollidedAgainst and LastFrameItemsCollidedAgainst

This version adds two new properties to ICollidable to make it easier to track collision every frame. These properties will be filled automatically by CollisionRelationships and can be used in an entity’s CustomActivity.

Since these properties are being added to the FlatRedBall Engine, games which compile directly against the engine have two options:

  1. Increase the .gluj file version to 22. This tells the FlatRedBall Editor to codegen these properties.
  2. Manually add these properties in custom code to entities. This is a fallback if upgrading a file version is inconvenient.

Note that this is a breaking change to projects linking against the engine, so one of these two changes must be performed.

If projects would like to upgrade to this version, keeping the engine and FlatRedBall Editor (Glue) together will prevent compile errors.

Version 23 – CollisionRelationship Supports ArePhysicsAppliedAutomatically and DoCollisionPhysics

This version adds the ability for CollisionRelationship physics to be defined in the FlatRedBall Editor in the Collision Physics UI, but to have those physics only apply if DoCollisionPhysics is called in code.

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 24 – Gum Supports StackSpacing

This version adds code generation support for the StackSpacing property in Gum.

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.