Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

WebSocketPeer

Inherits: PacketPeer < RefCounted < Object

A WebSocket connection.

Description

This class represents WebSocket connection, and can be used as a WebSocket client (RFC 6455-compliant) or as a remote peer of a WebSocket server.

You can send WebSocket binary frames using PacketPeer.put_packet, and WebSocket text frames using send (prefer text frames when interacting with text-based API). You can check the frame type of the last packet via was_string_packet.

To start a WebSocket client, first call connect_to_url, then regularly call poll (e.g. during Node process). You can query the socket state via get_ready_state, get the number of pending packets using PacketPeer.get_available_packet_count, and retrieve them via PacketPeer.get_packet.

GDScript

extends Node
var socket = WebSocketPeer.new()
func _ready():
    socket.connect_to_url("wss://example.com")
func _process(delta):
    socket.poll()
    var state = socket.get_ready_state()
    if state == WebSocketPeer.STATE_OPEN:
        while socket.get_available_packet_count():
            print("Packet: ", socket.get_packet())
    elif state == WebSocketPeer.STATE_CLOSING:
        # Keep polling to achieve proper close.
        pass
    elif state == WebSocketPeer.STATE_CLOSED:
        var code = socket.get_close_code()
        var reason = socket.get_close_reason()
        print("WebSocket closed with code: %d, reason %s. Clean: %s" % [code, reason, code != -1])
        set_process(false) # Stop processing.

To use the peer as part of a WebSocket server refer to accept_stream and the online tutorial.

Properties

Methods

Enumerations

enum WriteMode:

WriteMode WRITE_MODE_TEXT = 0

Specifies that WebSockets messages should be transferred as text payload (only valid UTF-8 is allowed).

WriteMode WRITE_MODE_BINARY = 1

Specifies that WebSockets messages should be transferred as binary payload (any byte combination is allowed).

enum State:

State STATE_CONNECTING = 0

Socket has been created. The connection is not yet open.

State STATE_OPEN = 1

The connection is open and ready to communicate.

State STATE_CLOSING = 2

The connection is in the process of closing. This means a close request has been sent to the remote peer but confirmation has not been received.

State STATE_CLOSED = 3

The connection is closed or couldn’t be opened.

Property Descriptions

PackedStringArray handshake_headers = PackedStringArray()

• void set_handshake_headers ( PackedStringArray value )

• PackedStringArray get_handshake_headers ( )

The extra HTTP headers to be sent during the WebSocket handshake.

Note: Not supported in Web exports due to browsers’ restrictions.

int inbound_buffer_size = 65535

• void set_inbound_buffer_size ( int value )

• int get_inbound_buffer_size ( )

The size of the input buffer in bytes (roughly the maximum amount of memory that will be allocated for the inbound packets).

int max_queued_packets = 2048

• void set_max_queued_packets ( int value )

• int get_max_queued_packets ( )

The maximum amount of packets that will be allowed in the queues (both inbound and outbound).

int outbound_buffer_size = 65535

• void set_outbound_buffer_size ( int value )

• int get_outbound_buffer_size ( )

The size of the input buffer in bytes (roughly the maximum amount of memory that will be allocated for the outbound packets).

PackedStringArray supported_protocols = PackedStringArray()

• void set_supported_protocols ( PackedStringArray value )

• PackedStringArray get_supported_protocols ( )

The WebSocket sub-protocols allowed during the WebSocket handshake.

Method Descriptions

Error accept_stream ( StreamPeer stream )

Accepts a peer connection performing the HTTP handshake as a WebSocket server. The stream must be a valid TCP stream retrieved via TCPServer.take_connection, or a TLS stream accepted via StreamPeerTLS.accept_stream.

Note: Not supported in Web exports due to browsers’ restrictions.

void close ( int code=1000, String reason=”” )

Closes this WebSocket connection. code is the status code for the closure (see RFC 6455 section 7.4 for a list of valid status codes). reason is the human readable reason for closing the connection (can be any UTF-8 string that’s smaller than 123 bytes). If code is negative, the connection will be closed immediately without notifying the remote peer.

Note: To achieve a clean close, you will need to keep polling until STATE_CLOSED is reached.

Note: The Web export might not support all status codes. Please refer to browser-specific documentation for more details.

Error connect_to_url ( String url, TLSOptions tls_client_options=null )

Connects to the given URL. TLS certificates will be verified against the hostname when connecting using the wss:// protocol. You can pass the optional tls_client_options parameter to customize the trusted certification authorities, or disable the common name verification. See TLSOptions.client and TLSOptions.client_unsafe.

Note: To avoid mixed content warnings or errors in Web, you may have to use a url that starts with wss:// (secure) instead of ws://. When doing so, make sure to use the fully qualified domain name that matches the one defined in the server’s TLS certificate. Do not connect directly via the IP address for wss:// connections, as it won’t match with the TLS certificate.

int get_close_code ( ) const

Returns the received WebSocket close frame status code, or -1 when the connection was not cleanly closed. Only call this method when get_ready_state returns STATE_CLOSED.

String get_close_reason ( ) const

Returns the received WebSocket close frame status reason string. Only call this method when get_ready_state returns STATE_CLOSED.

String get_connected_host ( ) const

Returns the IP address of the connected peer.

Note: Not available in the Web export.

int get_connected_port ( ) const

Returns the remote port of the connected peer.

Note: Not available in the Web export.

int get_current_outbound_buffered_amount ( ) const

Returns the current amount of data in the outbound websocket buffer. Note: Web exports use WebSocket.bufferedAmount, while other platforms use an internal buffer.

State get_ready_state ( ) const

Returns the ready state of the connection. See State.

String get_requested_url ( ) const

Returns the URL requested by this peer. The URL is derived from the url passed to connect_to_url or from the HTTP headers when acting as server (i.e. when using accept_stream).

String get_selected_protocol ( ) const

Returns the selected WebSocket sub-protocol for this connection or an empty string if the sub-protocol has not been selected yet.

void poll ( )

Updates the connection state and receive incoming packets. Call this function regularly to keep it in a clean state.

Error send ( PackedByteArray message, WriteMode write_mode=1 )

Sends the given message using the desired write_mode. When sending a String, prefer using send_text.

Error send_text ( String message )

Sends the given message using WebSocket text mode. Prefer this method over PacketPeer.put_packet when interacting with third-party text-based API (e.g. when using JSON formatted messages).

void set_no_delay ( bool enabled )

Disable Nagle’s algorithm on the underling TCP socket (default). See StreamPeerTCP.set_no_delay for more information.

Note: Not available in the Web export.

bool was_string_packet ( ) const

Returns true if the last received packet was sent as a text payload. See WriteMode.