Web Socket communication
The Machinations API is based on socket.io. Our API accepts & returns JSON-encoded request/responses and uses the WebSocket Protocol. The API is in active development, and we’re always gathering feedback, looking for new use cases.
Behind the API there is a software layer connecting your Machinations Public Diagrams to allow your socket.io client to get diagram changes.
You can use any web socket client compatible with socket.io. Below, you can find examples for NodeJS. Our C# Unity Plugin, for example, features a full implementation of the Machinations API and it uses WebSocketSharp.
Authentication
You need to copy your User Key from your Machinations account, under your Profile Picture > Settings > Account Details.
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.
Provide your User Key as a parameter of connection to Machinations. You do not need to provide a password. Instead, you will need to provide a Diagram Token. You can obtain this by clicking on the Diagram’s title…
And then pressing the Generate Token button. Copy the token and use it with the code below.
This is a fully functional connection example in NodeJS
Node.JS
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 |
const io = require('socket.io-client'); const options = { rejectUnauthorized: false, reconnect: false, forceNew: true, transports: ['websocket'] } const CONSTANTS = { SEND: { AUTHORIZE: 'api-authorize', INIT: 'game-init', EVENT: 'game-event', }, RECEIVE: { ERROR: 'api-error', AUTH_DENY: 'api-auth-deny', AUTH_SUCCESS: 'api-auth-success', INIT: 'game-init', EVENT: 'diagram-elements-updated', }, } const connectionURL = 'api.machinations.io'; const token = 'YOUR MACHINATIONS TOKEN HERE'; const diagramToken = 'YOUR DIAGRAM TOKEN HERE'; const serverAdd = `wss://${connectionURL}?userkey=${token}`; console.log(serverAdd); const socket = io(serverAdd, options); const authorize = { diagramToken: diagramToken, gameName: "Some Game" }; socket.on("connect", () => { console.log(' CONNECT '); socket.emit(CONSTANTS.SEND.AUTHORIZE, authorize); console.log(socket.id, authorize) }); socket.on(CONSTANTS.RECEIVE.AUTH_SUCCESS, (msg) => { console.log(CONSTANTS.RECEIVE.AUTH_SUCCESS, msg); const gameData = { diagramToken: diagramToken }; setTimeout(() => { socket.emit(CONSTANTS.SEND.INIT, gameData) }, 3000); }); socket.on(CONSTANTS.RECEIVE.AUTH_DENY, (msg) => { console.log(CONSTANTS.RECEIVE.AUTH_DENY, msg); }); socket.on(CONSTANTS.RECEIVE.INIT, (msg) => { console.log(CONSTANTS.RECEIVE.INIT, msg); }); |
C# (specific to Unity Socket IO Component)
|
1 2 3 4 5 6 7 8 9 10 |
using WebSocketSharp; using WebSocketSharp.Net; ... ws = new WebSocket(url + (string.IsNullOrEmpty(_userKey) ? "" : "&token=" + _userKey)); //The implementation is up to the developer, based on this docs. //Alternatively, for a fully functional C# implementation, please check: //https://github.com/machinationsio/up-unity-example-tanks-scriptable-objects ... |
In case of an invalid User Key, the client receives an error response and the connection is terminated.
Through the authenticated socket, clients can send/receive messages using the JSON format.
Connection to the Machinations Diagram
Make sure you handle the following Machinations responses:
- deny response:
|
1 2 3 4 5 |
// you do not have a valid token or user has no rights // user is identified based on user key socket.on('api-auth-deny', (msg) => { } |
- success response
|
1 2 3 4 |
// socket.on('api-auth-success', (msg) => { } |
Message format: JSON-schema
Connect Diagram Elements
From your Machinations diagram, get the Node ID and properties from the Properties Panel, by selecting the Node.
Based on the Node ID & Properties, the client is able to gate the current value & changes of properties during diagram edit.
Initialization request
The initialization request can be sent at any time and the communication list will be changed.
Example: node.js
|
1 2 3 4 5 6 7 8 9 10 |
socket.on('api-auth-success', (msg) => { const gameData = { diagramToken: diagraToken, machinationsIDs:[ {id: 19, props: ['label', 'activation','action', 'resources', 'capacity' , 'overflow']}, {id: 74, props: ['label', 'activation', 'action', 'resources', 'capacity', 'overflow'] }, ] }; socket.emit('game-init', gameData); }); |
- Machinations will respond with the properties values:
Example: node.js
|
1 2 3 4 |
// socket.on('game-init', (msg) => { // nodes properties values }); |
Example: JSON-schema response
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
{ diagramElements: [ { id:'19', type: 'Pool', label: 23, activation: 'passive', action: 'pull-all', resources: 281, capacity: -1, overflow: 'block' }, { id: '74', type: 'Pool', label: 'Speed', activation: 'passive', action: 'push-any', resources: 48, capacity: 296, overflow: 'block' } ] } |
- While the socket is open, the client will receive, from Machinations, any properties changes but only the ones reflected on the init list.
Example: node.js
|
1 2 3 |
socket.on('diagram-elements-updated', (msg) => { // nodes properties updates }); |
Example: JSON-schema response
|
1 2 3 4 |
// { diagramElements: [ { id: '19', resources: 283 } ] } ... { diagramElements: [ { id: '74', resources: 50 } ] } |
Communication Node & Properties List
- An array of elements (node id & properties) set up at initialization request (‘game-init’)
- The client will receive a property update (‘diagram-elements-updated’ event type) only if the property(& node id) is on the list
- This list can be changed with an initialization request (‘game-init’), at any time
Example of a JSON-schema
|
1 2 3 4 5 6 7 |
// [ {id: 62, props: ['label', 'activation']}, {id: 65, props: ['label', 'transfer', 'limitis']}, {id: 19, props: ['label', 'activation','action', 'resources', 'capacity' , 'overflow']}, {id: 74, props: ['label', 'activation', 'action', 'resources', 'capacity', 'overflow'] }, ] |
Sending values to Machinations
You use the game-update-diagram-elements event to send values to Machinations. The message should respect the following format:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
"game-update-diagram-elements", { "diagramToken":"087ec358-b709-4f67-a5c1-b2abc5b0bd6", "machinationsIDs":[ {"id":225, "type":"resources", "timeStamp":12384732487, "parameter":"number", "previous":21, "value":2} ] } |
Named versions
This request asks for the list of named versions for a diagram. The diagram will be identified by diagramToken.
|
1 |
socket.emit('get-versions', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' }); |
The response has the following format:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ versions: [ { name:'My latest version', timestamp: 523456789, }, { name:'Some other version', timestamp: 456789123, } ] } |
Get all diagram elements
This request asks for a list of all elements in a diagram. The diagram will be identified by diagramToken.
|
1 |
socket.emit('get-all-elements', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' }); |
The response has the following format:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
{ diagramElements: [ { id:'19', type: 'Pool', label: 23, activation: 'passive', action: 'pull-all', resources: 281, capacity: -1, overflow: 'block' }, { id: '74', type: 'Pool', label: 'Speed', activation: 'passive', action: 'push-any', resources: 48, capacity: 296, overflow: 'block' } ] } |
Events types
- Send (socket.emit …)
- ‘api-authorize’ – Authorizing diagram connection
- ‘game-init’ – Request Nodes properties from a diagram
- ‘get-versions’ – Request version history from a diagram.
- Receive (socket.on …)
- api-auth-deny’ – Authorization denied. You do not have a valid Token or user has no rights (user is identified based on the User Key)
- ‘api-auth-success’ – Successful authorization
- ‘game-init’ – Response at initialization request
- ‘diagram-elements-updated’ – Sent when an element from the communication list is changed on machinations.io‘s side
- ‘api-error’ – Machinations API error
- ‘error’ – Socket.io error
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
diagramTokennot present in the JSON request - 415090 – Web socket not authenticated
- 415091 – Web socket not authorized
- 4150110 – Diagram parse error
- 415130 – Parameter
gameDatanot present in the JSON request - 415131 – Parameter
machinationsIDsnot present in the JSON request