Skip to content

WebSocket API

Jump to bottom
Euphoriahh edited this page Oct 31, 2023 · 2 revisions

WebSocket API

For advanced/power users, Synapse X contains a easy to use WebSocket API to allow third party plugins to interface with Synapse X. The documentation for the API is below:

Introduction

This guide is going to be advanced and go into technical details on how this system fully works. If you are a regular user of Synapse X and do not wish to create plugins to interface with Synapse X, this guide is probably not for you.

For regular users though, this guide will allow developers to make plugins which can improve your user experience by a ton. Expect a lot of developers to make your life a lot easier with this.

You can even execute scripts from the browser, and create all sorts of cool things via this API. See below for more details.

Security

Security concerns are a big problem for the Synapse X WebSocket API. Since this API allows applications to arbitrarily execute scripts, some security features were implemented to prevent abuse of this API.

All applications that use this API must be whitelisted. Whitelists for the API are split into two categories:

  • Prompt Whitelists: This will prompt the user when they connect to your WebSocket for the first time of your application name and developer name. The user can decide to allow the continue the connection or not.
  • No Prompt Whitelists: These on the other hand, do not require the user to authroize the connection to be able to use the WebSocket. These are reserved for trusted developers only.

Note: Applications running on the end users machine (ex: native applications) are presumed to be trusted by default and do not require whitelisting.

You can contact me on Discord about whitelisting your application. Please be prepared to show your application to me before getting whitelisted.

Abusing the API with your whitelist will result in you being blacklisted from both the API and Synapse X itself.

Libraries

The WebSocket API uses WebSockets, meaning you will have to use a WebSocket library to connect. Some libraries for different languages are below:

You can also test the API directly via browser from this Google Chrome extension - it is pre-whitelisted.

The rest of this tutorial will use WebSocket-Sharp (C#) and WebSockets (Node) for examples.

Connecting

The Synapse X WebSocket API is not enabled by default, and requires you to manually enable it in theme-wpf.json. You can find the toggle for it in Main.WebSocket.Enabled.

After enabling the Synapse X WebSocket, you can then connect via the following base URL: ws://localhost:24892. "Services" (explained in the next section) are extensions of this base URL, and are separate.

Services

The Synapse X WebSocket API currently has 4 services: Execute, Editor, Attach, and Custom. Each service can be accessed by appending the service name to the end of the URL: (ex: ws://localhost:24892/execute)

You can then connect to the service by using that completed URL as the WebSocket URL. After authentication completes, your WebSocket will be opened and you can execute commands.

Execute Service

ws://localhost:24892/execute

The execute service is the most simple service of the Synapse X WebSocket API. Sending data to the service will simply execute it in Synapse X. After execution completes, a response code will be sent back to you.

Response Codes:

  • OK: This means that the script was successfully sent to Synapse X for execution. This does NOT mean though that the script did not error during compilation or execution though - that is currently unsupported.
  • NOT_READY: This means that you did not attach Synapse yet, and execution has failed. Consider using the Attach Service before using the Execute service.

Examples:

  • Node:
const WebSocket = require("ws");

const ws = new WebSocket("ws://localhost:24892/execute");

ws.on("open", function open() 
{
  ws.send("print'Hello world!'");
});

ws.on("message", function incoming(data)
{
  console.log(data); //Response Code - "OK" in most cases
});
  • C#:
using System;
using WebSocketSharp;

namespace TestWebSocket
{
    public class Program
    {
        public static void Main(string[] args)
        {
            using (var ws = new WebSocket("ws://localhost:24892/execute"))
            {
                ws.OnMessage += (sender, e) =>
                    Console.WriteLine(e.Data); //Response Code - usually "OK"

                ws.Connect();
                ws.Send("print'Hello world!'");

                Console.ReadKey(true);
            }
        }
    }
}

Editor Service

ws://localhost:24892/editor

The editor service has the same interface of the execute service, except it will set the data sent to the editor instead of being executed. Examples are the same, except the NOT_READY response code is never sent for the editor service.

Attach Service

ws://localhost:24892/attach

The attach service is the most complex service of the 4 current services. It contains 2 specific commands: ATTACH, and IS_READY.

Commands:

  • IS_READY: This will send a response code of TRUE or FALSE if Synapse X is attached or not.
  • ATTACH: This will queue a set of response events to be sent as attaching progresses. It also sends a response code of either ATTEMPTING or ALREADY_ATTACHED.

Response Events:

  • INJECTING: This signals Synapse X is currently injecting.
  • CHECK_WL: This signals Synapse X is currently checking the whitelist.
  • SCANNING: This signals Synapse X is currently scanning/waiting for the game to load. This is also fired if the user teleports.
  • READY: This signals Synapse X is ready and script execution can start.
  • REATTACH_READY: This signals Synapse X has detected a teleport and is ready to execute scripts again.
  • INTERRUPT: This signals Synapse X failed to attach. (crash during init/user closed out before attaching completed)
  • FAILED_TO_FIND: This means Synapse X did not find a process to attach to.
  • ALREADY_ATTACHED: This means Synapse X is already attached.
  • ATTEMPTING: This means Synapse X is currently attempting an attach.
  • NOT_LATEST_VERSION: This means Synapse X is not on the latest version - the user has to restart Synapse X.

Examples:

  • Node: (requires npm i alert-node for example)
const WebSocket = require("ws");
const Alert = require("alert-node");

const ws = new WebSocket("ws://localhost:24892/attach");

ws.on("open", function open() 
{
  ws.send("ATTACH");
});

ws.on("message", function incoming(data)
{
  //This will be called back multiple times during the attaching process
  
  console.log(data);

  if (data == "READY")
  {
    Alert("Synapse has attached!");
  }
  else if (data == "ALREADY_ATTACHED")
  {
    Alert("Synapse is already attached!");
  }
  else if(data == "INTERRUPT")
  {
    Alert("Synapse has failed to attach!");
  }
});
  • C#: (requires reference to System.Windows.Forms)
using System;
using System.Windows.Forms;
using WebSocketSharp;

namespace TestWebSocket
{
    public class Program
    {
        [STAThread]
        public static void Main(string[] args)
        {
            using (var ws = new WebSocket("ws://localhost:24892/attach"))
            {
                ws.OnMessage += (sender, e) =>
                {
                    Console.WriteLine(e.Data);

                    switch (e.Data)
                    {
                        case "READY":
                            MessageBox.Show("Synapse has attached!");
                            Environment.Exit(0);
                            break;
                        case "ALREADY_ATTACHED":
                            MessageBox.Show("Synapse is already attached!");
                            Environment.Exit(0);
                            break;
                        case "INTERRUPT":
                            MessageBox.Show("Synapse has failed to attach!");
                            Environment.Exit(0);
                            break;
                    }
                };

                ws.Connect();
                ws.Send("ATTACH");

                Console.ReadKey();
            }
        }
    }
}

Custom Service

ws://localhost:24892/custom?channel=CHANNEL_NAME

The custom service allows you to communicate between Synapse X scripts and your own applications. There is no commands or response codes for this service, all communication is handled on your side.

Examples:

  • Node:
const WebSocket = require("ws");

const ws = new WebSocket("ws://localhost:24892/custom?channel=metoothx");

ws.on("open", function open() 
{
  ws.send("Hello world!");
});

ws.on("message", function incoming(data)
{
  console.log(data);
});
  • C#:
using System;

namespace TestWebSocket
{
    public class Program
    {
        [STAThread]
        public static void Main(string[] args)
        {
            using (var ws = new WebSocket("ws://localhost:24892/custom?channel=metoothx"))
            {
                ws.OnMessage += (sender, e) =>
                {
                    Console.WriteLine(e.Data);
                };

                ws.Connect();
                ws.Send("Hello world!");

                Console.ReadKey();
            }
        }
    }
}
  • Lua: (NOTES: WebSockets do not stay during teleports, you must re-execute for every teleport! The 'open_web_socket' function is not defined if the user does not enable WebSockets also.)
local Socket = syn.open_web_socket("metoothx") --"metoothx" is the channel name
Socket:Connect(function(msg)
* print(msg) --Hello world!
end)

while wait(5) do
* Socket:Send("aaaaaaa") --Will be sent back every 5 seconds
end

Notes

  • Connecting to multiple services requires multiple WebSocket connections. Example below:
const WebSocket = require("ws");
const Alert = require("alert-node");

const ws = new WebSocket("ws://localhost:24892/attach");
const ws2 = new WebSocket("ws://localhost:24892/execute");

ws.on("open", function open() 
{
  ws.send("ATTACH");
});

ws.on("message", function incoming(data)
{
  //This will be called back multiple times during the attaching process
  
  console.log(data);

  if (data == "READY")
  {
* Alert("Synapse has attached!");
* //You can then execute after attaching completes.
* ws2.send("print'Hello world!'");
  }
  else if (data == "ALREADY_ATTACHED")
  {
* Alert("Synapse is already attached!");
  }
  else if(data == "INTERRUPT")
  {
* Alert("Synapse has failed to attach!");
  }
});
  • If the user declines to authorize your application, your connection will be closed and you will be blocked from connecting again until the user relaunches Synapse X.

Enjoy using the WebSocket API! Have fun!

Sources:

Clone this wiki locally