Web Socket communication

The Machinations API is based on socket.io. Our API accepts & returns JSON-encoded request/responses and uses the WebSocket Protocol. This allows for low-latency and efficient data transfer of large quantities of events and updates.

You can use any socket client that can work through WebSockets, but you should be aware that our server uses socket.io to provide responses, so it is easiest if you also use a socket.io compatible client.

Below, we will describe the protocol using examples for NodeJS. We also have a functional and open source implementation in the form of our C# Unity Plugin, which features a full implementation of the Machinations API using WebSocketSharp for communication.

Authentication

You need to copy your User Key from your Machinations account, under your (top right) Profile Picture > Account Settings > Profile:

Machinations Auth — The bottom section of your Profile contains your User API Key.

Keep your credentials secure. Do not share your secret API keys in publicly accessible spaces such as GitHub, client-side code, and so forth. All requests must be made over WSS (WebSocket Secure). Calls made over plain WS will fail. API requests without the User Key will also fail.

Besides your User Key, when you connect to Machinations, you will also need to provide a Diagram Token. You can obtain this by opening the Share dialogue from the diagram’s header bar.

And then generate a token on the dedicated section under the sharing options:

To be sure: you should never send your account password for authentication when using the API.

Now that you’re armed with the required connection parameters, let’s connect to the API.

Connecting & getting all Diagram Elements

We’ll be using NodeJS to walk you through using the API, as it is small, easy to install and doesn’t require many dependencies.

Here’s a minimal package.json that is required for you to install the required client libraries:

{
	"name": "simple-machinationsio-client",
	"version": "1.0.0",
	"description": "",
	"type": "module",
	"main": "simplestConnection.js",
	"scripts":
	{
		"start": "node src/simplestConnection.js"
	},
	"author": "",
	"license": "ISC",
	"dependencies":
	{
		"socket.io-client": "4.5.1"
	}
}

Now npm install this package.jsonand create the file `/src/simplestConnection.js`:

import io from "socket.io-client";

const connectionURL = "api.machinations.io";
const userToken = "YOUR_USER_TOKEN";
const diagramToken = "YOUR_DIAGRAM_TOKEN";

const CONSTANTS = {
  SEND: {
    AUTHORIZE: "api-authorize",
    INIT: "game-init",
    EVENT: "game-event",
    GAME_UPDATE_DIAGRAM_ELEMENTS: "game-update-diagram-elements",
    GAME_GET_ALL_ELEMENTS: "get-all-elements",
  },
  RECEIVE: {
    ERROR: "api-error",
    AUTH_DENY: "api-auth-deny",
    AUTH_SUCCESS: "api-auth-success",
    INIT: "game-init",
    EVENT: "diagram-elements-updated",
  },
};
const serverAddress = `wss://${connectionURL}/?&token=${userToken}`;
console.log("Conneting via: " + serverAddress);

const options = {
  rejectUnauthorized: true,
  reconnect: true,
  transports: ["websocket"],
};
let socket;

socket = io(serverAddress, options);
socket.connect(serverAddress);

const authorize = { diagramToken: diagramToken, gameName: "Your Game Name" };
socket.on("connect", () => {
  console.log("Connecting...");
  socket.emit(CONSTANTS.SEND.AUTHORIZE, authorize);
});
socket.on(CONSTANTS.RECEIVE.AUTH_SUCCESS, (msg) => {
  console.log(CONSTANTS.RECEIVE.AUTH_SUCCESS, msg);
  const gameData = {
    diagramToken: diagramToken,
  };
  setTimeout(() => {
    console.log("Requesting Init...");
    socket.emit(CONSTANTS.SEND.INIT, gameData);
  }, 1000);
});

socket.on(CONSTANTS.RECEIVE.AUTH_DENY, (msg) => {
  console.log(CONSTANTS.RECEIVE.AUTH_DENY, msg);
});

socket.on(CONSTANTS.RECEIVE.INIT, (msg) => {
  console.dir(msg);
});

socket.on(CONSTANTS.RECEIVE.ERROR, (msg) => {
  console.log(CONSTANTS.RECEIVE.ERROR, msg);
});

socket.on("error", (msg) => {
  console.log("error", msg);
});

You can now run npm start or `node src/simplestConnection.js`.

The result of running the above code with the proper User Key & Diagram Token should be you seeing something like this:

Conneting via: wss://api.machinations.io/?&token=5ef95969-b27a-4cd7-8855-41104790fd59
Connecting...
api-auth-success { AuthResult: 'You are authorized ! Success !' }
Requesting Init...
{
    diagramElements: [...
... followed by a listing of all elements (pools, resource connections, registers, etc.) in the diagram you took the Diagram Token from.

The output of the console also clearly shows you the structure of the JSON objects you will be receiving.

Listening to Diagram Element Update events

Once you are connected to your diagram, you will be notified of changes done to the values of Elements. Add the following code to your simplestConnection.js file:

socket.on(CONSTANTS.RECEIVE.EVENT, (msg) => {
    console.log(CONSTANTS.RECEIVE.EVENT, msg);
});

If you are running the file, stop the process. Run the file via Node. Since a socket connection is open, the process will keep running. Go to your diagram and change the value of a Pool.

Back to your console, you should see something like:

diagram-elements-updated { diagramElements: [ { id: '676', resources: 2003 } ] }

A natural observation is that there’s an id there. We’ll cover that in the next section.

Updating a Diagram Element

Now we’re getting to the fun stuff. Let’s update a diagram element. This is done by sending the `game-update-diagram-elements` event. A key parameter here is the Diagram Element ID, which is used to identify what diagram element you’d like to modify. Of course, you’d probably like to know how exactly do you know what is the ID of one of your diagram elements. Here’s where you can find it:

This is where you can fetch your Diagram Element ID

Now go to simplestConnection.js and change the function where you handle CONSTANTS.RECEIVE.INIT. Replace the event code with:

socket.on(CONSTANTS.RECEIVE.INIT, (msg) => {
  console.dir(msg);

  setTimeout(() => {
    console.log("Sending a diagram element update...");

    const updateData = {
      diagramToken,
      machinationsIDs: [{ id: 676, type: "resources", timeStamp: 12384732487, parameter: "number", value: 2200 }],
    };

    socket.emit(CONSTANTS.SEND.GAME_UPDATE_DIAGRAM_ELEMENTS, updateData);
  }, 3000);
});

As you can see, we’re passing an array of machinationsIDs. These are the Diagram Element IDs that we will update in this call. Indeed, it is possible to update multiple elements at once. Replace the id with one of your element ids and re-run the file. You should see the value of that particular element change in your diagram.

Available Properties

id – Integer (node id)
type – String (available types: “Source”, “Drain”, “Pool”, “Gate”, “Trader”, “Delay”, “Converter”, “Register”, “End Condition”, “State Connection”, “Resource Connection”, “Text”, “Group”)
label – String (machations.io label / machinations.io nodes label)
activation – String ( machinations.io activation see activation modes )
action – String (machinations.io action)
resources – Integer (machinations.io resources)
capacity – Integer (machinations.io capacity)
overflow – String (machinations.io overflow)
limits – Integers (machinations.io registers limits)
transfer – String (connection transfer)

Error Codes:

415050 – Invalid or missing User Key
415051 – Error while validating User Key
415070 – Missing diagram Token
415071 – Invalid diagram Token
415072 – Error during validating diagram Token
415073 – Parameter diagramToken not present in the JSON request
415090 – Web socket not authenticated
415091 – Web socket not authorized
4150110 – Diagram parse error
415130 – Parameter gameData not present in the JSON request
415131 – Parameter machinationsIDs not present in the JSON request

Fireside Chat, Episode 1 w/ Joris Dormans