Machinations UP – Technical Integration Guidelines

Before you proceed to integrate Machinations Up in your project, it is recommended that you are familiar with its Core Concepts. It is, however, not mandatory to do so. Whatever you choose, this guide will help you connect your game to your Machinations diagram.

This guide assumes that you are familiar with Unity and its main concepts.

Adding the necessary files to a Game Project

The first step of the integration is to add Up‘s script assets to your game. Go ahead and copy the “MachinationsUP” directory into the root of your game’s “Scripts” directory.

Now, it’s time to include Up into your game by adding & configuring its two prefabs:

  • Inside the Unity Editor, bottom pane, select the “Project” tab.
  • Navigate to YOUR-PROJECT\Scripts\SocketIO\Prefabs.
  • Click the SocketIO prefab.
  • In the right pane, in “Inspector”, locate the text field labeled Url. By default, it is set to ws://127.0.0.1:4568/socket.io/?EIO=4&transport=websocket. You need to change the IP address and the port for the Machinations back-end. This data is accessible through your Machinations account. Hit ENTER to confirm.
  • Drag the prefab into your Stage’s Hierarchy.
  • Navigate to YOUR-PROJECT/Scripts/Machinations/Engines/Unity/Prefabs.
  • Click the MachinationsGameLayer prefab. In the right pane, in “Inspector”, locate the text field labeled Machinations API Key and set it to the correct value for your Machinations account. Hit ENTER.
  • Locate the text field labeled Game Name and give it a value. This value will be used to pick the appropriate Machinations Diagram during the game’s runtime.
  • Drag the prefab into your Stage’s Hierarchy.

You can now switch to your favorite editor and begin the scripting-side integration.

Bringing Machinations diagram values into a Game Project

Machinations -\> Game synchronization means that you will bring values from the Machinations diagram into variables inside your Game.

Machinations Up allows you to synchronize any variable within any script inside your Game. Stage properties, game engine settings, anything that is being read from a variable can be synchronized.

However, since games built with Unity revolve around Game Objects, we will focus on this scenario. Your Game Objects usually have variables for gameplay properties such as Hit Pointsor Damage which a game design is based on and can be imported from your Machinations diagram.

There are two ways to handle synchronization, based on Game State :

  • Game State unaware (get values from a single diagram)
  • Game State aware (multiple diagrams may be involved)

Through Game State , we understand a constant set of rules that a game currently plays on. Many games switch between different rules based on Game State. For example, in the game Civilization, you have one set of rules on the strategy map and another in the city screen. Or, in Quake you have one set of rules when playing Deathmatch and another one in Capture the Flag. Game State awareness allows you to connect each of your Game States (and even Game Object States) to a different diagram.

Game State Unaware

This is the simplest way to connect a game to Machinations. We will now refer to the code of the example game where you can see Machinations Up in action.

Within the ExampleGames/RubyAdventure2DBeginner directory, the class Enemy is used to manage enemies in our example game.

We will import the enemy’s health from Machinations:

To do this, the following steps are required:

  1. Declare a MachinationsGameObject:

private MachinationsGameObject _mgo;

  1. Declare strings for the properties we want to get from Machinations:

private const string M_HEALTH = “Health”;

  1. Declare a Manifest that will contain what we want to get from Machinations:

static readonly private MachinationsGameObjectManifest _manifest = new MachinationsGameObjectManifest

_ {_

_ GameObjectName = “Enemy”,_

_ GameObjectPropertyNames = new List<string> {M_HEALTH}_

_ };_

  1. In the Game Object’s Awake function, initialize the Machinations Game Object:

_mgo = new MachinationsGameObject(_manifest);

And that’s it. We will now have our Machinations value inside _mgo[M_HEALTH].Value.

_mgo[M_HEALTH] will return you the MachinationsElementBinder corresponding to the enemy’s health. If you prefer, you can also store _mgo[M_HEALTH] into its own variable such as enemyHealth.

When you want to modify the Enemy’s health, you should use the methods available to you in MachinationsElementBinder: ChangeValueWith and ChangeValueTo. This will ensure that the value stays within the Min & Max bounds defined by your Machinations Diagram.

Now let’s move on to more complex scenarios.

Game State Aware

To explore how Machinations Objects can be Game State Aware, let’s look at the player’s character in our example game.

Within the ExampleGames/RubyAdventure2DBeginner directory, the class RubyController is used to manage the player’s character.

We will import both the character’s health and its speed from Machinations. Even more, we will do so based on Game State. For now, there is only one Game State in our example game, but this doesn’t impact the structure of the code nor the concepts you will have to be familiar with.

Game Aware Integration consists of the following steps:

  1. Declare a MachinationsGameAwareObject:

private MachinationsGameAwareObject _mgao;

  1. Declare strings for the properties we want to get from Machinations:

private const string M_HEALTH = “Health”;

private const string M_SPEED = “Speed”;

  1. Declare a Manifest that will contain what we want to get from Machinations:

static readonly private MachinationsGameObjectManifest _manifest = new MachinationsGameObjectManifest

_ {_

_ GameObjectName = “Ruby”,_

_ GameObjectPropertyNames = new List<string> {M_HEALTH, M_SPEED},_

_ CommonStatesAssociations = new List<StatesAssociation>_

_ {_

_ new StatesAssociation(“Exploring”, new List<GameStates>() {GameStates.Exploring})_

_ }_

_ };_

  1. In the Game Object’s Awake function, initialize the Machinations Game Object:

_mgo = new MachinationsGameObject(_manifest);

The first change compared to Game State Unaware Synchronization is that we use the class MachinationsGame Aware Object.

Then, a new member has appeared in the Manifest: CommonStatesAssociations. This is the simplest way to associate a Machination Game Object’s Properties to a Game State. More StatesAssociation elements can be added for each desired Game State Combination.

The word “common” in CommonStatesAssociations means that the StatesAssociations defined here will apply to all Game Object Property Names that the Game Object uses.

The MachinationsGameObjectManifest class also supports defining StatesAssociationsPerPropertyName should you want more control over this mapping.

More importantly, Game State Awareness cannot work unless your game Engine notifies Machinations about Game State Changes.

All MachinationsGameAwareObject as well as the MachinationsGameLayer implement two interfaces:

IGameLifecycleSubscriber – Your game logic/engine should notify _MachinationsGameAwareObject_sof Game State Changes.

IGameObjectLifecycleSubscriber – Your game logic/engine should notify _MachinationsGameAwareObject_sof Game Object State Changes.

Your game can notify MachinationsGameAwareObjects individually about State changes, or, can notify MachinationsGameLayer, which will automatically notify MachinationsGameAwareObjects that are registered with it.

Once your game or game objects switch State, Machinations Up will automatically select values from the appropriate diagram. Note that it is still your responsibility to update your game objects with those values.