Introduction

The AddSafe method is a thread-safe way to add instructions to the engine. Typically "add" calls cannot be made on managers; however, the AddSafe method allows adding instructions from any thread.

Code Example

The AddSafe method takes an Instruction argument. The following code shows how to call AddSafe assuming you have a valid Instruction.

// Assumes instructionToAdd is a valid Instruction
InstructionManager.AddSafe(instructionToAdd);

AddSafe and calling code on the primary thread

The AddSafe method can be called with an action to execute. This makes calling code on the primary thread easy:

InstructionManager.AddSafe( ()=>
{
   // Do whatever you need to here
});

As mentioned above, objects cannot be added to managers on secondary threads. The following shows how to add a Sprite on the primary thread

InstructionManager.AddSafe(()=>SpriteManager.AddSprite("redball.bmp"));

Code may execute next frame

Since the InstructionManager only performs instruction execution one time per frame, your code may execute after instructions have been processed that frame. This means that your code may not execute until next frame.

Introduction

This method creates instructions for moving the argument PositionedObject through a list of points which is created from the list of IPositionables passed as the second argument. This method can be used in combination with the NodeNetwork class to automatically move objects along a path.

Code Example

The following creates five Sprites. The four in the corners represent points that the fifth will move through. Add the following using statements:

using FlatRedBall.Instructions;
using FlatRedBall.Math;

Add the following to Initialize after initializing FlatRedBall:

PositionedObjectList<Sprite> list = new PositionedObjectList<Sprite>();

Sprite sprite = SpriteManager.AddSprite("redball.bmp");
sprite.X = 5;
sprite.Y = 5;
list.Add(sprite);

sprite = SpriteManager.AddSprite("redball.bmp");
sprite.X = -5;
sprite.Y = -5;
list.Add(sprite);

sprite = SpriteManager.AddSprite("redball.bmp");
sprite.X = -5;
sprite.Y = 5;
list.Add(sprite);

sprite = SpriteManager.AddSprite("redball.bmp");
sprite.X = 5;
sprite.Y = -5;
list.Add(sprite);

sprite = SpriteManager.AddSprite("redball.bmp");
float velocity = 3;
InstructionManager.MoveThrough<Sprite>(sprite, list, velocity );

Introduction

The Pulse method creates a recurring set of instructions used to change the argument IScalable's Scale and Scale Velocity. The result is a pulsing effect.

Code Example

The following creates a Sprite which pulses using a set of defined parameters.

Add the following using statements:

 using FlatRedBall;
 using FlatRedBall.Instructions;

Add the following to Initialize after initializing FlatRedBall;

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

 float smallScaleX = 1;
 float smallScaleY = 1;
 float largeScaleX = 3;
 float largeScaleY = 3;
 double period = 1; // how many seconds the grow/shrink lasts

 InstructionManager.Pulse<Sprite>(
     sprite,
     smallScaleX,
     smallScaleY,
     largeScaleX,
     largeScaleY,
     period);

The Add method adds the argument instruction to the InstructionManager. The InstructionManager stores which are executed according to their .

For more information on how the InstructionManager handles instructions that are added to it, see the .

Introduction

The InstructionManager is a class that provides methods for performing common tasks with instructions.

Tile Based Movement

See the tile based movement tutorial.

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

Introduction

The Instructions property is an exposed InstructionList which the InstructionManager will check and execute if according to the TimeManager's CurrentTime property. Instructions which do not necessarily belong to an instance, or which are to be executed on an object which does not implement the IInstructable interface can be added to the InstructionManager's Instructions property for automatic execution.

Code Example

Instructions can be directly added or removed from the InstructionManager.Instructions list:

// Calls the EndGame method in 10 seconds:
var delegateInstruction = new DelegateInstruction( 
    () => EndGame(), 
    TimeManager.CurrentTime + 10);

InstructionManager.Instructions.Add(delegateInstruction);

Execution Details

The InstructionManager will execute Instructions if the InstructionManager's IsExecutingInstructions property is true (default). The InstructionManager will automatically check the time of instructions and execute them.

Common Usage

Instructions are a common part of the FlatRedBall game engine, and many FlatRedBall objects implement the IInstructable interface. If an instruction is instantiated which should operate on an IInstructable, then the instruction should be added to the IInstructable's Instructions property. This suggests that the IInstructable "owns" the instructions which will operate on it. Having each IInstructable contain Instructions which will operate on it can help improve debugging. Some objects, such as Screens do not implement the IInstructable interface, or are not automatically managed by a manager. It is common practice to place Instructions which will operate on these objects in the InstructionManager's Instructions list. Instructions in this list will also automatically be executed, and provide a centralized, easy to use list for instructions. However, in general, use the Instructions property for individual objects if available before using the InstructionManager's Instructions list.

Clearing all Instructions

You can clear all instructions by simply calling the Clear method on the Instructions object:

InstructionManager.Instructions.Clear();

The MoveTo function is a function which will take the argument PositionedObject and will set its Velocity so that it moves to the argument location in a set amount of time, as specified by the secondsToTake parameter. The MoveTo function will do two things:

1. It will modify the velocity values of the PositionedObject.

2. It will add instructions to the PositionedObject's Instructions list.

Introduction

The MoveToAccurate creates a set of Instructions for moving a PositionedObject to a given point in a set amount of time.

Code Example

The following code moves a Sprite to the position where the user clicks the Mouse. Note that this could be implemented with any PositionedObject, including any Glue entity. Add the following using statements to your Glue screen:

using FlatRedBall;
using FlatRedBall.Input;
using FlatRedBall.Instructions;

Add the following to your screen's CustomInitialize to show the mouse:

 // to show the cursor
 IsMouseVisible = true;

Add the following to your Screen's CustomActivity, assuming SpriteInstance is a Sprite in your Screen:

 void CustomActivity()
 {
     // The number of seconds to take to move to where the user
     // clicks.
     float secondsToTake = 2;

     // A button release is a "click".
     // Don't create new movement instructions if there are
     // already other movement instructions - things can get wacky.
     if (InputManager.Mouse.ButtonReleased(
             FlatRedBall.Input.Mouse.MouseButtons.LeftButton) &&
         SpriteInstance.Instructions.Count == 0)
     {
         // We could create the Instructions ourselves, but the
         // InstructionManager makes things easy.
         InstructionManager.MoveToAccurate(SpriteInstance,
             InputManager.Mouse.WorldXAt(SpriteInstance.Z),
             InputManager.Mouse.WorldYAt(SpriteInstance.Z),
             SpriteInstance.Z,
             secondsToTake);
     }
 }

Introduction

ObjectsIgnoringPausing contains a list of objects which do not implement PositionedObject which should be ignored in pausing. Objects which do implement PositionedObject should not be added to this list unless they have additional pausing behavior which is checked by external systems. In a default FlatRedBall project this is not the case.

For code examples on how to use ObjectsIgnoringPausing in combination with pausing your game using PauseThisScreen, see the Screen.PauseThisScreen page.

Introduction

The RotateToAccurate method creates and adds Instructions for rotating the argument PositionedObject to the argument rotation. The method takes three values as it can perform rotation on the X, Y, and Z rotation components.

Code Example

The following code creates and rotates a Sprite so that its rotation matches the angle from the Sprite to the Mouse when the user clicks the left button. Add the following using statements:

using FlatRedBall.Input;
using FlatRedBall.Instructions;

Add the following at class scope:

Sprite sprite;

Add the following in Initialize after initializing FlatRedBall:

sprite = SpriteManager.AddSprite("redball.bmp");
sprite.ScaleX = 4;

Add the following in Update:

if (InputManager.Mouse.ButtonReleased(FlatRedBall.Input.Mouse.MouseButtons.LeftButton))
{
    float angle = (float)(System.Math.Atan2(
        InputManager.Mouse.WorldYAt(0) - sprite.Y,
        InputManager.Mouse.WorldXAt(0) - sprite.X));
    float secondsToTake = 1;
    // Just in case there are other instructions around from the 
    // last call: 
    sprite.Instructions.Clear();

    // Adds instructions to the Sprite's Instructions list. 
    InstructionManager.RotateToAccurate(sprite, 0, 0, angle, secondsToTake); 
}

Introduction

The PauseEngine method can be used to freeze all velocity, rate, and acceleration, properties as well as delay all Instructions that belong to objects managed by engine managers. Calling PauseEngine and UnpauseEngine will temporarily stop then resume nearly all behavior for objects which are managed by the FlatRedBall, and in many cases is all that is necessary to implement pause functionality.

The PauseEngine method is used by the PauseThisScreen method in the Screen class.

Keep in mind that calling PauseEngine does NOT stop the management of objects by the engine. In other words, if an object with a non-zero velocity is stopped by calling PauseEngine, but its velocity is then set to a non-zero value before calling UnpauseEngine, the object will resume movement.

This allows select objects to continue managed behavior despite other objects being paused. For example, pausing may freeze the behavior of all objects except a pause menu which should continue to behave as normally. Once the game is unpaused and the pause menu is removed, calling UnpauseEngine resumes the behavior of all objects.

Also keep in mind that any behavior which is not dependent on properties managed by the engine or dependent on Instructions must be manually controlled when implementing Pausing functionality.

Code Sample

The following code creates an Emitter which emits Sprites. The sprites have velocity, rate, and acceleration methods set. Despite the complex behavior of the Sprites, a simple call to PauseEngine stops all behavior. Similarly, calling UnpauseEngine resumes all behavior as expected.

Notice that the TimedEmit is a method which is explicitly called in the Update method. Since it is not managed by the engine, it must manually be called only when the program is not stopped.

Add the following using statements:

using FlatRedBall.Graphics.Particle;
using FlatRedBall.Instructions;
using FlatRedBall.Input;

Add the following at class scope:

Emitter mEmitter;
bool mIsPaused = false;

Add the following in Initialize after initializing FlatRedBall:

mEmitter = SpriteManager.AddEmitter("redball.bmp", "ContentManagerName");

mEmitter.TimedEmission = true;
mEmitter.SecondFrequency = .06f;
mEmitter.EmissionSettings.AlphaRate = -.1f;
mEmitter.RemovalEvent = Emitter.RemovalEventType.Alpha0;
mEmitter.EmissionSettings.RadialVelocity = 12;
mEmitter.EmissionSettings.YAcceleration = -3;
mEmitter.ParticleBlueprint.CustomBehavior += BounceAgainstEdges;

Add the following in Update:

if (mIsPaused == false)
{
    mEmitter.TimedEmit();
}

if (mIsPaused == false && InputManager.Keyboard.KeyPushed(Keys.P))
{
    InstructionManager.PauseEngine();
    mIsPaused = true;
}
else if (mIsPaused == true && InputManager.Keyboard.KeyPushed(Keys.U))
{
    InstructionManager.UnpauseEngine();
    mIsPaused = false;
}

Define the BounceAgainstEdges CustomBehavior at class scope:

void BounceAgainstEdges(Sprite sprite)
{
    if (sprite.X + sprite.ScaleX > SpriteManager.Camera.RelativeXEdgeAt(0) &&
        sprite.XVelocity > 0)
    {
        sprite.XVelocity *= -1;
    }
    if (sprite.X - sprite.ScaleX < -SpriteManager.Camera.RelativeXEdgeAt(0) &&
        sprite.XVelocity < 0)
    {
        sprite.XVelocity *= -1;
    }
    if (sprite.Y - sprite.ScaleY < -SpriteManager.Camera.RelativeYEdgeAt(0) &&
        sprite.YVelocity < 0)
    {
        sprite.YVelocity *= -1;
    }
}

PauseEngine and Screens

The PauseEngine method was written to work well with Screens. The PauseEngine does not turn off engine management - this is done so that any menu that appears while paused (allowing the user to restart or unpause) will still have its usual updates called. Therefore, the order for pausing and unpausing should be as follows:

• Call PauseEngine

• Add the Popup Screen

• <User Unpauses>

• Remove the Pause Screen

• Call UnpauseEngine

The removal of the PauseEngine and calling of UnpauseEngine does not necessarily have to be performed in this order, but it is conceptually clean to treat these events as a stack and "remove off of the top".