Engine Overview

FlatRedBall2 Engine Overview

FlatRedBall2 is a 2D game engine built on MonoGame. It provides physics, collision, rendering, input, and UI (via Gum) out of the box. Game code creates Screens, Entities, and wires them together.

What the Engine Does Automatically

• Physics: pos += vel*dt + acc*(dt^2/2), vel += acc*dt, vel -= vel*drag*dt — every frame, for every entity
• Collision resolution: All registered CollisionRelationship pairs are tested and resolved after physics
• Rendering: Everything added via screen.Add(renderable) is drawn, sorted by Layer + Z
• Input polling: Input updates keyboard, mouse, and gamepad state each frame
• Gum UI updates: Click/hover/focus events routed to all active Gum elements
• Screen transitions: Old screen torn down, new screen initialized — entities, factories, Gum elements all cleaned up automatically
• Camera: Initialized from window viewport; transforms world coordinates to screen

What Game Code Must Implement

• Entity subclasses — override CustomInitialize (add shapes, input) and CustomActivity (per-frame logic)
• Screen subclasses — override CustomInitialize (create factories, entities, collision relationships, UI)
• Collision relationships — call AddCollisionRelationship in screen's CustomInitialize
• Game1.cs — initialize FlatRedBallService.Default, call Update/Draw each frame
• Save/load — the engine offers nothing here; use standard .NET (System.IO + System.Text.Json, or your serializer of choice). There is no FRB2 save API to search for.

Frame Loop Order

Each frame runs in this order:

1. Screen transition (if pending) — old screen destroyed, new screen initialized
2. Input update — keyboard, mouse, gamepad polled
3. Gum update — UI input events routed
4. Physics — entity positions updated from velocity/acceleration/drag
5. Collision — registered relationships resolved; positions corrected
6. Entity CustomActivity — each entity's per-frame logic
7. Screen CustomActivity — screen-level logic (sees post-collision, post-entity state)
8. Draw — all registered renderables drawn

Bootstrapping a Game

Game1.cs wires the MonoGame loop to FRB: FlatRedBallService.Default.Initialize<TScreen>(this) in Initialize (sizes the window, initializes, starts the screen — or Initialize(this, "…gluj") to boot a whole Glue project), then Update/Draw each frame. The complete template — including the GraphicsProfile.HiDef setup that crashes at startup if omitted — lives in sample-project-setup; don't hand-roll it.

Key Design Rules

• Y+ is up in world space. Camera flips Y for screen rendering.
• Always use Factory<T> to create entities — never new MyEntity(). Factory sets Engine, registers with the screen, and enables GetFactory<T>().
• No static state (engine infrastructure only) — only FlatRedBallService.Default is static. Everything else is accessed via Engine on entities or directly on screens. Game code may use static singletons for global game data (e.g., GameData.Current holding a monster roster or player save state) — this rule prohibits engine-layer statics, not application-layer ones.
• Shapes default to IsVisible = false — always set IsVisible = true.
• Entity.Engine: Use CustomInitialize, not the constructor — Engine is null until Factory injects it.
• Use Gum for all UI — HUD, health bars, menus, win/lose screens, any text display. Shapes are for world-space game objects (collision geometry, projectiles, platforms). If you reach for a shape to build UI, stop and use Gum instead.

What a Screen Looks Like

A screen creates its Factory<T> instances in CustomInitialize, spawns entities with Create(), and wires AddCollisionRelationship over those factories — the gestalt the per-topic skills show piecewise:

public class GameScreen : Screen
{
    private Factory<Player> _playerFactory = null!;
    private Factory<Wall> _wallFactory = null!;

    public override void CustomInitialize()
    {
        _playerFactory = new Factory<Player>(this);
        _wallFactory = new Factory<Wall>(this);
        _playerFactory.Create();

        AddCollisionRelationship<Player, Wall>(_playerFactory, _wallFactory)
            .MoveFirstOnCollision();
    }
}

Sub-Systems (accessed via Engine.*)

Which Skill to Read Next