entities-and-factories

Entities and Factories in FlatRedBall2

Entity is the base class for game objects. It owns position, velocity, acceleration, drag, and a list of child shapes for collision and rendering. Factory<T> manages creating, tracking, and destroying entity instances from within a Screen.

Rules

1. Always spawn through Factory<T> — never new MyEntity(). Bypassing the factory breaks Engine.GetFactory<T>() and collision relationships. This applies even when there is only one instance (e.g., one ball in Pong).
2. Override CustomInitialize for setup, CustomActivity for per-frame logic. Add shape children, create input handlers, and wire references in CustomInitialize. The constructor is too early — Engine is null until the factory injects it (see engine-overview).
3. Don't write properties whose only effect happens in CustomInitialize. They look configurable but silently fail when assigned after Create() returns. Three fixes by case: expose the child shape directly (forwarding), pass init-only data through Create(e => e.X = ...) so it's set before CustomInitialize runs, or write a reactive setter for state the gameplay legitimately mutates. See references/reactive-properties.md — this is the most common entity-design footgun in FRB2.
4. Don't create entities for static walls / floors / ceilings. Use TileShapes instead — see collision-relationships.
5. Entity (X,Y) should be the object's ground-contact point, not its sprite's visual center. Sprite always draws centered on its entity, so a sprite taller/wider than a point needs Sprite.X/Sprite.Y offset once its size is known. See platformer-movement (feet-at-origin) and top-down-movement (origin and draw order) for perspective-specific offsets. This code-only path is fine for a one-off entity. If the entity already has (or will get) an .achx, author the sprite offset and its collision shape together as frame data instead — see animation skill's per-frame shapes — so the offset lives in content, not CustomInitialize math.