What is Fluent?

Fluent interfaces allow game designers to write more fluid and readable code.  Through the use of method chaining, English like sentences can be written to express game functionality.  Fluent interfaces can be implemented in any object oriented programming language.  Below is an example of a line in the game design document, a standard implementation example and a fluent example:

Game Design Document:

“Do 5 damage to all enemy tanks within range 2 of an entity”

Standard Example:

foreach( var unit in player.UnitsWithinRange(2) )
{
    if(!unit.IsType(Enemy) || !unit.IsType(Tank))
        continue;

    unit.Damage(5);
}

Fluent Example:

player.UnitsWithinRange(2)
  .Where(UnitIs.Enemy)
  .Where(UnitIs.Tank)
  .DoDamage(5);

This fluent example closely matches the design document and is easier to read.  It also uses less language constructs like loops and conditions.  With Intellisense, designers are given a context sensitive list of operations they can perform.  Designers simply build up the expression that describes the original line in the game design document they are implementing.

How to implement Fluent Interfaces

Fluent interfaces are actually quite easy to implement.  Objects expose methods that return a reference to the object itself allowing method chaining.  The best way to describe this is by showing the implementation required for the examples above.

First, we create the object we will be working on (I’ve called it UnitsList in my examples).  This gives us the first part of the fluent call (Get.UnitsWithinRange(2)).

public class ScriptObject
{
    UnitsList UnitsWithinRange(int range)
    {
        return new UnitsList(range);
    }
}

The UnitsList object must have a set of methods that return references to the object itself allowing method chanining:

public class UnitsList
{
    public UnitsList Where(UnitIs condition)
    {
        this.conditions.Add(condition);
        return this;
    }

The fluent expressions are terminated by returning void from a function.  This lets the designer know they have no more options and often that the actual operation will be performed.

public class UnitsList
{
    public void DoDamage(int damage)
    {
        foreach( var unit in this.mainUnit.UnitsWithinRange(range) )
        {
            if(!PassesConditions(unit))
                continue;

            unit.Damage(damage);
        }
    }

    private bool PassesConditions(Unit unit)
    {
        foreach( var condition in conditions)
        {
            if(!unit.IsType(condition))
                return false;
        }
        return true;
    }
}

There are a couple of key things to notice:

1. This last code example looks a lot like the original standard example
2. A lot more “engine” code is required to setup a fluent interface than a standard interface

So, in effect, an extra layer of abstraction is being placed over the original code.  Rather than designers working on loops and conditions, they are calling (well named) methods.  This makes their life a lot easier and simplifies maintenance of their gameplay code.  It pushes the burden of maintenance down from the gameplay to the engine level and therefore on programmers, who are better suited to maintaining code.  If there is a change in the engine or game, this extra level of abstraction serves to buffer the designers and reduce the amount of code that needs to be written.

Good Interface Design

Care needs to be taken when designing the interfaces and exposing methods to the designers.  Rather than exposing all functions off a single object my recommendation is to define different objects for different situations.  The example provided starts with the player and retrieves a list of units around it.  Filters are then added before the final operation is performed on the resulting list.  By limiting the methods available to the designer to simple filters there is little risk of them making a mistake.  Also, the fact that the “DoDamage” function returns void stops them from chaining anything further.

Other Syntaxes

One small point is that designers can structure their fluent “sentences” in any way they please:

player.UnitsWithinRange(2).Where(UnitIs.Enemy).Where(UnitIs.Tank).DoDamage(5);

player.UnitsWithinRange(2)
  .Where(UnitIs.Enemy)
  .Where(UnitIs.Tank)
  .DoDamage(5);

There is no difference between the above two examples.  It’s simply a matter of coding style preferred by the writer.

Conclusion

What do you think of Fluent Interfaces?  Have you used a similar technique before?  Do you think the extra engine code and maintenance is too much hassle for the gain in clarity to designers?

As an experiment, try exposing a small set of functionality through a fluent interface and see whether your designers like working with it.

Advantages

There are a number of key advantages to using C# as a scripting language in your game engine.  I’ll list these first then describe how I achieve them.

• Designers use Visual Studio. Most designers are stuck using notepad (or similar) when writing their scripts.  With my technique, designers can use Visual Studio, gaining the full power of the IDE.  Including:
  • Intellisense. Letting them know what functions exist on all of the objects you’ve exposed, as well as documentation you’ve provided in code.
  • Compilation. Designers can compile their scripts while making changes to catch any compile-time problems.
  • Full Debugging Support. Another area lacking in most scripting languages is the debugging support.  Designers have access to all of Visual Studios debugging functionality to help them find and fix issues with their code.
• Run-Time Changes. Designers still have complete control to change their scripts at run-time.  Scripts can be reloaded automatically when files are changed, or (more likely) a “reset” button can be exposed in the game engine that allows them to reset the level and reload all scripts.
• Compile scripts into the executable for release. You have the option to use the scripts compiled into the executable if you prefer, protecting your files.
• Complete Access to game objects, or whatever you want designers to access. Designers are working in the same language you are developing in.  They have full access to the game objects or to a subset you decide on.  I use an interface and expose what I want them to use.
• FAST Run-time performance. The C# code is compiled not interpreted meaning the run-time performance is as good as the rest of the engine.  The slight performance bottleneck of reflecting the function can be removed by compiling scripts into executable if required.
• No Binding Required. Binding is automatic between the game engine and the script.  You don’t need to write any plumbing and exposing a new function is as easy as adding it to the engine.

How It Works

The setup is surprisingly easy, designers follow these steps and their up and running:

1. Add the script file to the Visual Studio project (preferably in its own directory)
2. Create an Init() function in the script class which will automatically be called by the engine
3. Create callbacks for events and implement the game logic
4. Run the game and make changes to scripts in real-time as needed

I use the run-time compilation functionality of the .NET framework to compile and run the code on- the-fly.  This has a small performance hit during compilation however the run-time performance is excellent.

Some Examples

Below are a few examples I put together today to show the power of the system.

The first script below creates an entity at the beginning of the game and then sets up a callback that will fire every 5 seconds.  The TestScript object’s lifetime is until the scripting system is reset allowing stateful object creation.

public class TestScript : BaseScript
{
    int team = 1;
    int xPos = 15;
    int yPos = 2;

    public void Init()
    {
        script.CreateEntity("Healer", team, xPos, yPos);
        script.CallEveryXSeconds(MyCallback, 5);
    }

    public void MyCallback()
    {
        script.CreateEntity("Tank", team, xPos, yPos++);
    }
}

The next script shows how simple customizing a game entity can be.  Whenever an effect is added or removed from a game entity, the following two functions are called allowing designers complete control over gameplay.  Notice the designer is given access only to what they need while still having complete control to change any settings or values of the entity.  An interface could be used to restrict what operations can be performed on entities as required.

class SpeedUpEffect
{
    public void AddEffect(GameEntity entity)
    {
        entity.Speed += 1;
    }

    public void RemoveEffect(GameEntity entity)
    {
        entity.Speed -= 1;
    }
}

Conclusion

As I said, I was amazed both at how simple all of this was to set up (only a few hours) and how powerful the system is.  If anyone is interested I’d be happy to share the source code for how I achieved this.  As I continue development of my engine I will be experimenting more with this scripting system and will release more information as I develop it.

Introduction

The Model View Controller pattern isolates gameplay logic from input and rendering.  This “Separation of Concerns” allows each layer to be developed, tested and maintained independently.  Graphics programmers work solely on rendering, gameplay programmers or designers work on gameplay and whoever’s left can work on input.

Model – Gameplay (game entities, eg. Player, Sword)
View – Rendering
Controller – Input and non-gameplay flow (menu’s etc)

The controller takes input from the player and changes the model.  The controller then passes the model (and any other relevant information) to the view to be rendered.

Advantages

Cleaner Code.  Large teams can work independently on each layer of the application without conflict.  Clear interfaces are used to define communication across layer boundaries.  As the engine grows, this separation of concerns helps to minimize complexity.

Better Cross Platform Support.  Gameplay is separate and not reliant on platform specific technology.  Rendering and input (both heavily platform specific) are separate and can easily be changed.

Decoupled Rendering.  In most engines the game world and renderer are tightly coupled.  MVC decouples the game world (and input) from the rendering.  Rather than calling “Render” of each game entity the rendering system uses the model when rendering.  This also simplifies the process of adding multi-threaded support to the game or renderer.

I’ve used this technique in my latest engine and it feels so much more natural.  Rather than blurring the line between gameplay and rendering they are distinct and the renderer is responsible for bringing them together.

Scripting/Designers.  All changes made to the model by the controller are through a known interface.  This interface can be exposed to designers/modders through a scripting language giving them greater flexibility and control.

Conclusion

I won’t go into implementation details right now.  If anyone is interested, I’ll put together a blog on implementation and look at releasing the MVC framework I created in XNA.  Let me know your thoughts, where you see there might be problems and if you’re interested in me discussing this further.