Synapse Library

Functions

queue_on_teleport

void syn.queue_on_teleport(script: string)

Queues script to be executed after the next teleport.

clear_teleport_queue

void syn.clear_teleport_queue()

Removes all queued scripts from the teleport queue.

get_thread_identity

int syn.get_thread_identity()

Returns the current thread's context level.

protect_gui

void syn.protect_gui(target: Instance)

protect_gui is deprecated. For backwards compatability, this function will cause target to be parented the return value of gethui() the next time it is parented.

unprotect_gui

void syn.unprotect_gui(target: Instance)

unprotect_gui is deprecated. For backwards compatability, this function will disable the parent-redirection done by protect_gui.

trampoline_call

(bool, ...any|string) syn.trampoline_call(target: function, call_stack: table, thread_options: table, ...any)

Proxy a call to a Lua function with the given call stack and thread options. call_stack is an array of tables, with each sub-table having fields described below.

The thread parameter allows you to preset the script, identity, and env fields with the values from that thread. This field is optional, and those fields can be overridden after the fact.

Note: These values do not need to correlate with actual information returned by debug.getinfo; they are fully customizable.

Note: The func parameter will override all other data you pass here aside from currentline!

Call Stack Entry	Description
currentline	The currently executing line of code.
env	The function's environment.
source	The 'source' field returned by `debug.getinfo`.
name	The function's name.
numparams	The number of parameters in the function.
is_vararg	Whether this function takes variadic arguments.
func	A function to copy all information from.

Thread Option Entry	Description
script	The script attached to the thread.
identity	The identity of the new state.
env	The global environment of the new thread.
thread	A thread used as the parent.

toast_notification

void syn.toast_notification(options: table)

Displays a toast notification in the internal UI. The options table follows the following format:

Option	Description	Default
Type	ToastType enum	Required
Duration	How long the notification should last, in seconds	5
Title	The notification's title	Required
Content	The notification's content	Required
IconColor	Overrides the icon color	Varies by `Type`

run_on_actor

bool syn.run_on_actor(actor: Instance, source: string, ...any)

Schedules code to be executed on an actor's Lua state.

request

table syn.request(params: table) [yields]

Makes a RESTful HTTP request.

Request Options

Option	Description	Default
Url	The request URL	Required
Method	The request method	"GET"
Headers	A map of header names to header values	{}
Cookies	A map of cookie names to cookie values	{}
Body	The request body. Cannot be used with GET or HEAD requests. It might be necessary to specify the `Content-Type` header when sending JSON or other formats.	nil

Synapse Headers

In addition to headers provided by the user, Synapse X adds the following:

Note: Syn-Fingerprint and Syn-User-Identifier have been deprecated in favor of the new public key verification system shown below.

Header	Value	Can Override
User-Agent	A string in the format "sx/<build_hash>".	Yes
Syn-Signature	Public-key authenticated headers, base64-encoded. See below for use.	No
Syn-Fingerprint	A string value which uniquely identifies the computer running Synapse X.	No
Syn-User-Identifier	A string value which uniquely identifies the current Synapse X user.	No

Response Table

syn.request returns the following table once the request is complete:

Key	Description
Success	Whether the request succeeded
StatusCode	The HTTP status code of the response
StatusMessage	A human-readable version of `StatusCode`
Headers	The response headers
Cookies	The response cookies
Body	The response body

Public Key Verification

Servers can verify a request was made by Synapse X via the public key verification system, along with syn.crypt.user.sign to verify extra data sent to the server.

To verify a Syn-Signature header, you must use libsodium with the crypto_sign_open function. Pass qgq26x4+4FWdLzRpGZytZfEQJlOeusryQC8ppC2BEVA= (Base64 encoded) as the public key. We will always alert developers and users if this key ever changes.

After signature verification succeeds, you will get a JSON encoded payload with the following fields:

Field	Description
authenticationTime	UNIX timestamp when the user authenticated this instance (UTC).
fingerprint	Same as the `Syn-Fingerprint` legacy header.
ipAddress	The IP address that was used to authenticate this instance. Please note this can change if the user was using a mobile network/similar. Can be IPv4 or IPv6.
userIdentifier	Same as the `Syn-User-Identifier` legacy header.
userPublicKey	The Base64 encoded public key for this user. You can use this to verify messages that were signed with the `syn.crypt.user.sign` function. To verify messages, use the libsodium crypto_sign_verify_detached function with this key as the public key.
userPromptPublicKey	The Base64 encoded prompt public key for this user. Like the above public key, this can be used to verify messages that were signed with the `syn.crypt.user.prompt.sign` function.

Please note that new fields can be added to this JSON payload at any time, so don't rely on the above for your JSON schemas. We will never remove fields without first alerting developers, though.

todo: add NodeJS, PHP, ASP.NET example code and probably move this whole section (Public Key Verification) to a page in the Developer Guide

Events

on_actor_state_created

syn.on_actor_state_created(actor: Instance)

Fired upon actor Lua state creation, before any scripts are ran.

Synapse X V3 Documentation