engine-overview

FlatRedBall2 Engine Overview

FlatRedBall2 is a 2D game engine built on KNI (an XNA-compatible framework for desktop and the browser). 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. A Layer (src/Rendering/Layer.cs) is only a draw-order bucket shared by every camera; its one flag, IsScreenSpace, affects Gum elements only, and Sprites, shapes and tilemaps ignore it
• 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