Index · Object → RefCounted → PacketPeer → WebSocketPeer

WebSocketPeer

A WebSocket connection.

Class 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().

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

var handshake_headers: PackedStringArray = PackedStringArray()

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

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

var heartbeat_interval: float = 0.0

The interval (in seconds) at which the peer will automatically send WebSocket "ping" control frames. When set to 0, no "ping" control frames will be sent.

Note: Has no effect in Web exports due to browser restrictions.

var inbound_buffer_size: int = 65535

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

var max_queued_packets: int = 4096

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

var outbound_buffer_size: int = 65535

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

var supported_protocols: PackedStringArray = PackedStringArray()

The WebSocket sub-protocols allowed during the WebSocket handshake.

Inherited from PacketPeer (1)

Methods

func accept_stream(stream: StreamPeer) -> Error

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.

func close(code: int = 1000, reason: String = "") -> void

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). If code is negative, the connection will be closed immediately without notifying the remote peer.

reason is the human-readable reason for closing the connection. It can be any UTF-8 string that's smaller than 123 bytes.

Note: To achieve a clean closure, 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.

func connect_to_url(url: String, tls_client_options: TLSOptions = null) -> Error

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: This method is non-blocking, and will return OK before the connection is established as long as the provided parameters are valid and the peer is not in an invalid state (e.g. already connected). Regularly call poll() (e.g. during Node process) and check the result of get_ready_state() to know whether the connection succeeds or fails.

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.

func get_close_code() -> int

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.

func get_close_reason() -> String

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

func get_connected_host() -> String

Returns the IP address of the connected peer.

Note: Not available in the Web export.

func get_connected_port() -> int

Returns the remote port of the connected peer.

Note: Not available in the Web export.

func get_current_outbound_buffered_amount() -> int

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

func get_ready_state() -> WebSocketPeer.State

Returns the ready state of the connection.

func get_requested_url() -> String

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()).

func get_selected_protocol() -> String

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

func poll() -> void

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

func send(message: PackedByteArray, write_mode: WebSocketPeer.WriteMode = 1) -> Error

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

func send_text(message: String) -> Error

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

func set_no_delay(enabled: bool) -> void

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

Note: Not available in the Web export.

func was_string_packet() -> bool

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

Inherited from PacketPeer (6)
func get_packet_error() -> Error
func get_var(allow_objects: bool = false) -> Variant
func put_packet(buffer: PackedByteArray) -> Error
func put_var(var: Variant, full_objects: bool = false) -> Error
Inherited from RefCounted (4)
func init_ref() -> bool
func reference() -> bool
func unreference() -> bool
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Object (2)

Enums & Constants

enum WriteMode
WRITE_MODE_TEXT = 0

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

WRITE_MODE_BINARY = 1

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

enum State
STATE_CONNECTING = 0

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

STATE_OPEN = 1

The connection is open and ready to communicate.

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_CLOSED = 3

The connection is closed or couldn't be opened.