Integration Guide

This is how you integrate Machinations UP in your production

Unity 3D - Code Import & Prefab Setup

  • Copy the scripts into your Unity 3D project

  • Add the necessary prefabs inside one of your game's root scenes (the menu, or any scene where you store game-wide objects)

    • From MachinationsUP / Engines / Unity / Prefabs, drag the MachinationsGameLayer prefab into the scene's Hierarchy.

    • From MachinationsUP / ThirdParty / SocketIO / Prefabs, drag the SocketIO prefab into the Hierarchy.

  • Set up the User Key and Diagram Token in MachinationsGameLayer using the Unity Property Inspector. To do this, select the MachinationsGameLayer prefab in your scene's Hierarchy window.

Setting up the MachinationsGameLayer

🎬 The following video will take you through the steps above, and then some of the steps below too:

Script-side Integration

It's important to understand that the way we built UP is quite open to interpretation & modification. We are here to offer some best practices (and to perfect those best practices). But, all in all, it's you who will decide what to use from our libraries. Keep in mind that this is still an early product and many things are yet to be decided.

🧙♂ Now that you have the Machinations UP code in your project, let's see if the prefabs are correctly set up.

Upon starting your game, you should see some debug messages in the console. Search for messages containing "MGL" (that stands for Machinations Game Layer and if you're curious about what this class does, we encourage you to read about it in our UP developer documentation). Search for "Game Auth Request" and if you correctly set up your User Key & Diagram Token, you should see a "Success" there.

UP for Game Objects

  • You start by declaring a Machinations Game Object Manifest.

    • Here, you define all Game Object Properties that you wish to map to Diagram elements.

static readonly private MachinationsGameObjectManifest _manifest = new MachinationsGameObjectManifest
{
GameObjectName = "Ruby",
PropertiesToSync = new List<DiagramMapping>
{
new DiagramMapping
{
GameObjectPropertyName = M_HEALTH,
DiagramElementID = 19,
DefaultElementBase = new ElementBase(105)
},
new DiagramMapping
{
GameObjectPropertyName = M_SPEED,
DiagramElementID = 102,
DefaultElementBase = new ElementBase(25)
}
}
};
  • Then, you create a MachinationsGameObject (aka MGO) or a MachinationsGameAwareObject giving the Manifest as an argument. To get the values when the game starts up, you should do this in the Awake function of your Game Objects.

    • When you do this, the MachinationsGameLayer will automatically create ElementBinders for each Game Object Property you defined in your Manifest.

public void Awake ()
{
//Initialize MachinationsGameObject.
_mgao = new MachinationsGameAwareObject(_manifest);
}
  • IDEALLY, you will instantiate your MGO (MachinationsGameObject) in the Awake function of your Game Object. This will let the MachinationsGameLayer know about all objects it has to request from the back-end, which it does as soon as your first scene loads. If for some reason you want to delay initialization, then you may call:

    MachinationsGameLayer.PerformInitRequest();
  • You can then refer to the ElementBinders by querying the MachinationsGameObject.

  • Instead of your usual int variables, use the Value / BaseValue of MachinationElements.

public void ChangeHealth (int amount)
{
//ChangeValueTo will automatically clamp it to the max you set in the Diagram.
_mgao[M_HEALTH].ChangeValueTo(_mgao[M_HEALTH].Value + amount);
Debug.Log("Ruby Health changed by: " + amount + ". Health left: " + _mgao[M_HEALTH].Value);
//As you can see, we refer to the Binders by the string constant
//defined in the manifest.
if (_mgao[M_HEALTH].Value == 0)
Respawn();
}

You can toy around with a working example of this in the following GitHub repo:

🎬 You can also see this in action in the this video:

UP for Scriptable Objects

  • Just like with Game Objects, you start by declaring a Machinations Game Object Manifest.

  • You need to implement the IMachinationsScriptableObject interface. The MachinationsGameLayer will call methods in this interface during its life.

/// <summary>
/// Called when Machinations initialization has been completed.
/// </summary>
/// <param name="binders">The Binders for this Object.</param>
public void MGLInitCompleteSO (Dictionary<string, ElementBinder> binders)
{
_binders = binders;
MGLUpdateSO();
}
/// <summary>
/// Called by the <see cref="MachinationsGameLayer"/> when an element has been updated in the Machinations back-end.
/// </summary>
/// <param name="diagramMapping">The <see cref="DiagramMapping"/> of the modified element.</param>
/// <param name="elementBase">The <see cref="ElementBase"/> that was sent from the backend.</param>
public void MGLUpdateSO (DiagramMapping diagramMapping = null, ElementBase elementBase = null)
{
Health = _binders[M_HEALTH].Value;
Speed = _binders[M_SPEED].Value;
}
  • You need to implement Unity's OnEnable function inside your ScriptableObject. In it, you must enroll your ScriptableObjects to the MachinationsGameLayer, like so:

public void OnEnable ()
{
MachinationsGameLayer.EnrollScriptableObject(this, _manifest);
}
  • IDEALLY, you will enroll your MSO (MachinationsScriptableObject) in the OnEnable function of your Game Object. This will let the MachinationsGameLayer know about all objects it has to request from the back-end, which it does as soon as your first scene loads. If for some reason you want to delay initialization, then you may call:

    MachinationsGameLayer.PerformInitRequest();

You can toy around with a working example of this in the following GitHub repo:

🎬 Here it is in action: