Construct 3 icon

Construct 3

Documentation

WebSocket

Published 23 Aug, 2017
791 words
~3-5 mins

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 3 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.

Secure WebSockets and preview mode

Construct 3 runs and previews your games on a secure (HTTPS) site. Some browsers block connections from secure to insecure sites. This means if you use an insecure WebSocket (ws: rather than wss:) the connection may be blocked in Construct 3's preview mode.

On today's web, it is best practice to use secure connections for all services. Your site should also host your project on HTTPS, and any WebSockets you use should use secure connections as well. HTTPS hosting is actually required for many features to work, secure WebSockets are more likely to connect successfully, and obviously it makes your content much more secure, so this is a good idea anyway. In some browsers you may be able to temporarily unblock the use of insecure WebSockets by clicking a button in the browser or changing settings, but it is a much better idea to ensure all your services are secure. In future, browsers may block the use of insecure sites and connections entirely.

WebSockets and multiplayer games

It may be tempting to use WebSockets to design real-time multiplayer games. Despite the fact they communicate in real-time, WebSockets are not a suitable choice for latency-sensitive real-time games. 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 difficult to design around this without changing the transmission mode, which WebSockets do not support. Consider using the specially-designed Multiplayer plugin Paid plans only instead.

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.