WebSocket plugin

The WebSocket plugin is a simple wrapper around the standardised WebSocket protocol. It allows for low-overhead bi-directional communication in real-time. Since WebSockets are standards-based, it should be compatible with any standards-compliant WebSocket server.

Using the WebSocket plugin requires a WebSocket server. Construct 2 does not provide a server nor can the WebSocket plugin be used to make a server. If you don't already have a WebSocket server set up, you will need to create one yourself using a technology like node.js with WebSocket support. This can be a significant undertaking and require server-side programming knowledge.

Note the WebSocket plugin currently also only supports text messages, and not binary messages.

WebSockets and multiplayer games

It may be tempting to use WebSockets to design real-time multiplayer games. Unfortunately, despite the fact they communicate in real-time, WebSockets are not currently a suitable choice for this. The underlying transport uses reliable transmission, meaning a single dropped packet can hold up all transmission until the packet is retransmitted successfully. For games with demanding real-time requirements, this can cause unplayable levels of latency. It is usually impossible to design around this without changing the transmission mode, which WebSockets do not support.

On the other hand, WebSockets should be suitable for games without such a demanding real-time requirement, like turn-based games. It should also be useful for application services, like chat rooms. Note this will still require you to create your own WebSocket server.

WebSocket properties

The WebSocket object has no properties.

WebSocket conditions

Is connecting
True if currently in the process of establishing a connection to a server. The connection is not yet successfully established; there may still be an error.

Is open
True if a connection has been successfully established and the communication channel is currently open.

Is supported
Use before attempting any connections to verify the current browser or platform supports WebSockets.

On closed
Triggered when the connection is closed, either deliberately or due to an error. The CloseCode and CloseReason expressions can indicate why the connection was closed.

On error
Triggered when an error occurs in the WebSocket connection. Use the ErrorMsg expression to get the error message text.

On opened
Triggered when the connection is successfully established and the communication channel is now open.

On message
Triggered when a text message arrives from the server over an open connection. Use the MessageText expression to retrieve the content of the message.

WebSocket actions

Close
Close any active connection. No more messages can be sent or will be received after closing.

Connect
Connect to a WebSocket server. WebSocket server addresses typically start with ws:// for non-secure transmission and wss:// for secure transmission. Note some network configurations may require secure transmission in order to function correctly.

The Protocol parameter may be optionally set to a required sub-protocol (sent with the Sec-WebSocket-Protocol header in the WebSocket handshake). If the server does not indicate it supports the chosen sub-protocol, the connection will fail to be established. This can be used to prevent the client connecting to WebSocket servers that do not understand your application's specific messages.

Send text
Send a text string to the server. This is ignored if the connection is not currently open.

WebSocket expressions

CloseCode
In the On closed trigger, returns the numeric code of the close reason. This can be one of the standard-specified return values, or a user-defined value.

CloseReason
In the On closed trigger, returns a string describing the reason the connection was closed. This is optional and may be empty.

ErrorMsg
In On error, the error message text.

MessageText
In On message, the text content of the message just received from the server.

Tags: