1 of 4

IInstructable

Introduction

The IInstructable interface specifies that an object can store instructions in an InstructionList. Most FlatRedBall classes which implement the IInstructable interface have managers which handle execution. allow the setting of properties at a predetermined time in the future without any explicit management.

Using Instructions

The FlatRedBall Engine provides a generic which can be used to set any property. The following code moves a Sprite in a square when the space bar is pushed.

Calling instructions on the object that will be modified

Instructions must be called on the object that will be modified. You cannot use the "dot" operator to set properties of embedded items. For example, the following is not valid:

Instead you should pass the instance as the first argument and have the property as the second argument:

InstructionManager

IInstructable Members

Call

Introduction

The "Call" function is a function which can be used to delay the execution of code. The Call function is conceptually similar to the , but it is more flexible, allowing you to use lambda expressions, anonymous delegates, and regular functions. The Call function is a great way to perform delayed actions and "scripting". Internally the Call function creates a and adds it to the calling IInstructable. Most IInstructable implementations, such as Sprites, shapes, and Entities have automatic code to execute their instructions. Therefore, simply calling the Call.After methods will result in these objects performing the desired action at the given time. Custom implementations of IInstructable need to call their own instructions every-frame for instructions added through Call.

Note: This is an extension method. To use this, you will need to add:

Code Example

The following code shows how to call Emit on an Emitter after 2 seconds:

Since all Entities are IInstructables, you can also call custom methods on Emitters as follows:

Entities can even destroy themselves after a certain amount of time:

You can also use lambda expressions inside Call:

Lambdas can be used to call methods which require parameters:

You can use larger lambda statements:

Screens are also IInstructables meaning you can use the Call function on Screens:

Example Usage

Call can be used to cascade actions. For example, consider an Entity which has a number of things which need to happen when it dies. The "Die" function may look like this:

Note that the functions used in the Call function are omitted to keep the example short. This example assumes that FlashRed, PlayDieSound, and StartFadingOut are functions with no parameters, and that they are defined in the same class as PerformDieActions. Destroy is defined for you by Glue in every Entity.

Call and Glue

Entities and Screens both implement IInstructable automatically, meaning you don't have to do any modification to your code to be able to use the Call function. Keep in mind that since the Call function is an "extension method", you will need to use the "this" prefix to have access to the Call function if you intend to use Call on a Screen/Entity inside of its own custom code.

Call creates Instructions

The Call function is a shorthand way to call a function through instructions. The Call function itself doesn't introduce any new functionality that isn't already available to the IInstructable interface; it just simplifies the syntax. Therefore, when you use the Call method, internally this creates an instruction. This can be verified:

Instruction owner vs. called function owner

The simplest scenario for using Call is within an IInstructable-implementing object (such as an Entity). For example:

In this case, the object containing the code (this) will hold the instruction, and the Destroy function will be called on "this" as well. However, you can call code that belongs to other objects. For example, if you have a list of Entities which should be destroyed in one second:

In this case, the objectAtI is both the object that will contain the instruction, and it will also be the object that will be destroyed. If possible, it is recommended that the object that owns the function passed to Call should also be the object that is performing the call. In other words:

Of course, this may not always be possible. For example, an Entity may contain an object which is not IInstructable. In that case, the Entity should "own" the instructions. In other words, this is okay:

Cnstructions

Introduction

The Instructions member in an IInstructable represents all of the instructions which have been created and added to the IInstructable. Instructions can be added to the InstructionList a number of ways:

Through a direct add, such as by calling:

ObjectInstance.Instructions.Add(SomeInstruction);

Through InstructionManager helper methods, such as by calling:
```
InstructionManager.MoveToAccurate(ObjectInstance...
```
Through the "fluent instruction" for instructions, such as by calling:
```
ObjectInstance.Set("X").To(3.0f).After(1.0f);
```

Clear

Instructions.Clear will remove all instructions which are held by an object. Clear can be used to cancel any existing instructions. For example, the following code will set an IInstructable to move to the X value ater 3 seconds, but then cancel that instruction and move it instead after 2 seconds.

// This will set X to 4.0f after 3 seconds
ObjectInstance.Set("X").To(4.0f).After(3);
// This will cancel the movement:
ObjectInstance.Instructions.Clear();
// This will set the X to 5.0f after 2 seconds:
ObjectInstance.Set("X").To(5.0f).After(2);

Set

Introduction

The Set method is an extension method for IInstructables which simplifies the creation of property and field setting instructions. Using the Set method enables the creation of instructions which will automatically be added to the calling IInstructable's InstructionList.

Note: This is an extension method. To use this, you will need to add:

using FlatRedBall.Instructions;

Code Example

The following code can be used to change a Sprite's X value to 4 after 1 second:

// Make sure to set the value to 4.0f and not 4 or 4.0 - the type matters and it must be a float
spriteInstance.Set("X").To(4.0f).After(1);

Since all Entities in Glue are also IInstructables, then any public property can be set on an Entity through reflection:

this.Set("SomeIntValue").To(3).After(2);

Note: Instructions should only set public fields and properties. The reason for this is because some platforms (such as Windows Phone) only allow the setting of public properties.

Cnstructions

Introduction

Through a direct add, such as by calling:

ObjectInstance.Instructions.Add(SomeInstruction);

Through InstructionManager helper methods, such as by calling:
```
InstructionManager.MoveToAccurate(ObjectInstance...
```
Through the "fluent instruction" for instructions, such as by calling:
```
ObjectInstance.Set("X").To(3.0f).After(1.0f);
```

Clear

// This will set X to 4.0f after 3 seconds
ObjectInstance.Set("X").To(4.0f).After(3);
// This will cancel the movement:
ObjectInstance.Instructions.Clear();
// This will set the X to 5.0f after 2 seconds:
ObjectInstance.Set("X").To(5.0f).After(2);

Call

Introduction

Note: This is an extension method. To use this, you will need to add:

Code Example

The following code shows how to call Emit on an Emitter after 2 seconds:

Since all Entities are IInstructables, you can also call custom methods on Emitters as follows:

Entities can even destroy themselves after a certain amount of time:

You can also use lambda expressions inside Call:

Lambdas can be used to call methods which require parameters:

You can use larger lambda statements:

Screens are also IInstructables meaning you can use the Call function on Screens:

// To move another screen after 5 seconds, you could add the following in your Screen's
// CustomInitialize:
this.Call( () => MoveToScreen(typeof(ScreenToGoTo)) ).After(5);

Example Usage

Call can be used to cascade actions. For example, consider an Entity which has a number of things which need to happen when it dies. The "Die" function may look like this:

public void PerformDieActions()
{
   this.Call(FlashRed).After(1);
   this.Call(PlayDieSound).After(1.2);
   this.Call(StartFadingOut).After(1.5);
   this.Call(Destroy).After(2);
}

Call and Glue

Call creates Instructions

// Assuming "this" is an IInstructable (like an Entity)
this.Instructions.Clear(); // Instruction count will now be 0
this.Call(SomeFunction).After(1);
if(this.Instructions.Count != 1)
{
    throw new Exception("This will not ever be hit");
}

Instruction owner vs. called function owner

The simplest scenario for using Call is within an IInstructable-implementing object (such as an Entity). For example:

this.Call(Destroy).After(1);

for(int i = 0; i < ListOfEntities; i++)
{
    var objectAtI = ListOfEntities[i];
    objectAtI.Call(objectAtI.Destroy).After(1);
}

 This should be the same...
 |        as this                
 |              |
 V              V
 objectAtI.Call(objectAtI.Destroy).After(1);

// assuming "this" is an IInstructable, but someNonIInstructableObject is not
this.Call(someNonIInstructableObject.MethodToCall).After(1);

IInstructable

Introduction

Using Instructions

The FlatRedBall Engine provides a generic which can be used to set any property. The following code moves a Sprite in a square when the space bar is pushed.

Calling instructions on the object that will be modified

Instructions must be called on the object that will be modified. You cannot use the "dot" operator to set properties of embedded items. For example, the following is not valid:

// assume myScene is a valid Scene
Instruction instructionToExecute = 
    new Instruction<Scene, float>(   // NO NO NO - this is setting a property on a Sprite, not Scene
                myScene, 
                "Sprites[0].YVelocity", // NO NO NO - No [] or . allowed
                velocityToSet, 
                timeToExecuteAt);

Instead you should pass the instance as the first argument and have the property as the second argument:

Instruction instructionToExecute = 
    new Instruction<Sprite, float>(   
                myScene.Sprites[0], 
                "YVelocity",
                velocityToSet, 
                timeToExecuteAt);

InstructionManager

The provides methods for performing common behavior on different objects. See the for more information.

IInstructable Members

Did this article leave any questions unanswered? Post any question in our for a rapid response.

// Add this using statement
using FlatRedBall.Instructions;

// Declare the Sprite instance at class scope
Sprite sprite;

// Replace Initialize with the following:
protected override void Initialize()
{
    FlatRedBallServices.InitializeFlatRedBall(this, this.graphics);

    base.Initialize();

    sprite = SpriteManager.AddSprite("redball.bmp");
}

// Replace Update with the following.
protected override void Update(GameTime gameTime)
{
    FlatRedBallServices.Update(gameTime);

    if (InputManager.Keyboard.KeyPushed(Keys.Space) && 
        sprite.Instructions.Count == 0)
    {
        float secondsToTake = 4.0f;
        float squareWidth = 10;

        float velocity = squareWidth * 4.0f / secondsToTake;

        // Move right.
        sprite.Instructions.Add(
            new Instruction<Sprite, float>(
                sprite, "XVelocity", velocity, 
                TimeManager.CurrentTime + 0));

        // Stop moving to the right.
        sprite.Instructions.Add(
            new Instruction<Sprite, float>(
                sprite, "XVelocity", 0, 
                TimeManager.CurrentTime + secondsToTake / 4.0f));
        // Move down.
        sprite.Instructions.Add(
            new Instruction<Sprite, float>(
                sprite, "YVelocity", -velocity, 
                TimeManager.CurrentTime + secondsToTake / 4.0f));

        // Stop moving down.
        sprite.Instructions.Add(
            new Instruction<Sprite, float>(
                sprite, "YVelocity", 0, 
                TimeManager.CurrentTime + 2 * secondsToTake / 4.0f));
        // Move left.
        sprite.Instructions.Add(
            new Instruction<Sprite, float>(
                sprite, "XVelocity", -velocity, 
                TimeManager.CurrentTime + 2 * secondsToTake / 4.0f));

        // Stop moving left;
        sprite.Instructions.Add(
            new Instruction<Sprite, float>(
                sprite, "XVelocity", 0, 
                TimeManager.CurrentTime + 3 * secondsToTake / 4.0f));
        // Move up.
        sprite.Instructions.Add(
            new Instruction<Sprite, float>(
                sprite, "YVelocity", velocity, 
                TimeManager.CurrentTime + 3 * secondsToTake / 4.0f));

        // Stop moving up at the end.
        sprite.Instructions.Add(
            new Instruction<Sprite, float>(
                sprite, "YVelocity", 0, 
                TimeManager.CurrentTime + 4 * secondsToTake / 4.0f));
    }

    base.Update(gameTime);
}