SetByDerived
Introduction
The SetByDerived property enables base screens/entities to define objects which will be assigned (instantiated) in derived screens/entities. Keep in mind that both the base and derived Object type must be the same.
Why use SetByDerived
SetByDerived can be set to true in the following situations:
The object that you intend to create comes from a file that is defined in a derived class, such as the Map object in GameScreen
The object is not always present in all derived types, such as the presence of an optional Sprite on an entity
If your game was created using the new project wizard, then you probably have a GameScreen with a Map that has its SetByDerived as true.
In this case the GameScreen is defining that a Map object will exist, but the instantiation of the Map object should happen in derived (Level) screens. Typically this instantiation is done from a TMX file. In the following image, the Level1 Screen (which inherits from GameScreen) creates the Map using its Level1Map.tmx file.
SetByDerived True Makes an Object "null"
If you set the SetByDerived property on an object to true, that means that generated code will not instantiate that object in the Screen or Entity that contains this Object. This Screen or Entity must be used as a base Screen or Entity to actually create an object. For example, consider an Entity called Character which contains a Sprite Object with SetByDerived set to true. The Sprite will not be created if you add an instance of Character to another Screen or Entity. The Character must be used as a base for another Entity (such as an Entity called "Monster").
SetByDerived Creates Abstract Screens/Entities
If an object has SetByDerived marked as true, then FlatRedBall expects that this object must be instantiated in a derived class. Therefore, to prevent errors the code that is generated for the Screen or Entity is marked as abstract.
For example, a typical GameScreen in FlatRedBall is abstract because its Map object has the SetByDerived property to true. Your GameScreen.Generated.cs class header probably looks like the following code:
SetByDerived vs ExposedInDerived
These two properties may seem similar but each is used in a different scenario. SetByDerived is used if you want the derived screen/entity to control the creation of the object, such as assigning an object to the result of loading a file. ExposedInDerived is used if you want the derived screen/entity to have access to the object so that its properties can be changed, but the object is still ultimately instantiated in the base.
Example
The following shows how to create an Entity (Base) which defines a Sprite Object which will get SetByDerived. The Derived then re-defines the Sprite.
Creating a Base Entity
Right-click on the tree item
Select Add Entity
Name the entity Base
Check the Sprite checkbox to add a Sprite to the Base entity
Click OK
Creating a Derived Entity
Right-click on the Entities tree item
Select Add Entity
Name the entity Derived
Click OK
Click the Properties tab on the newly-created Derived entity
Set the BaseEntity property Entities\Base
Base and Derived are bad names! This example uses the names "Base" and "Derived" to clearly indicate the relationship between two Entities. In an actual game, avoid using names like Base and Derived. You should always name your Entities in a way to indicate what they are in the context of your game (such as Character or Enemy or PlayerShip). However, if you intend to use an Entity as a base type, it is a good idea to append "Base" at the end of the name (such as EnemyBase).
Setting SetByDerived to True
Expand the Base entity
Select SpriteInstance (which was created earlier when the Sprite checkbox was checked)
Select the Properties tab
Set the SpriteObject's SetByDerived to True
FlatRedBall automatically adds a SpriteInstance to the Derived entity.
Notice that objects which have their SetByDerived property to true appear blue in the tree view window, and objects which have their base implementation marked as SetByDerived appear yellow.
Specifying Properties on Derived Sprite
At this point the Derived entity will automatically create a Sprite for you (since it is an object in Glue). You can select this Sprite and assign variables on it, just like any other Sprite.
SetByDerived and Multiple Inheritance Levels
By default SetByDerived applies to only one level of inheritance, rather than cascading down through all levels of inheritance. For example, consider an example with three entities:
Base
Middle (which inherits from Base)
Derived (which inherits from Middle)
If Base defines SpriteInstance, and SpriteInstance has its SetByDerived to true, then the assignment to SpriteInstance will be done in Middle, and Derived will not be able to re-assign Sprite. Notice in the image above that SpriteInstance does not appear in the Derived entity.
However, the SetByDerived property can be set on the Middle SpriteInstance, and it will be assignable in Derived.
Last updated
