使用 WebSockets

HTML5 與 WebSocket

WebSocket 通訊協定於 2011 年標準化，原始目標是讓瀏覽器能與伺服器建立穩定的雙向連線。在此之前，瀏覽器僅支援 HTTP 請求，並不適合雙向通訊。

此協定以訊息為單位，非常適合向瀏覽器推播通知，常用於聊天、回合制遊戲等。它仍然使用 TCP 連線，雖可靠但延遲較高，不適合 VoIP 與快節奏的即時遊戲（這類情境請見 WebRTC）。

由於簡單、相容性廣，且比原生 TCP 更易使用，WebSocket 也開始在瀏覽器之外普及，被原生應用程式用作與網路伺服器溝通的方式。

Godot 在原生與網頁匯出中皆支援 WebSocket。

在 Godot 中使用 WebSocket

Godot 以 WebSocketPeer 提供 WebSocket 支援，並且可與高階多人 API 搭配使用。更多細節請見 高階多人連線。

警告

匯出到 Android 時，請在匯出專案或一鍵部署前，於 Android 匯出設定啟用 INTERNET 權限，否則所有網路連線都會被 Android 阻擋。

基本用戶端範例

本範例將示範如何建立 WebSocket 連線、並與遠端伺服器收發資料。

extends Node

# The URL we will connect to.
# Use "ws://localhost:9080" if testing with the minimal server example below.
# `wss://` is used for secure connections,
# while `ws://` is used for plain text (insecure) connections.
@export var websocket_url = "wss://echo.websocket.org"

# Our WebSocketClient instance.
var socket = WebSocketPeer.new()


func _ready():
    # Initiate connection to the given URL.
    var err = socket.connect_to_url(websocket_url)
    if err == OK:
        print("Connecting to %s..." % websocket_url)
        # Wait for the socket to connect.
        await get_tree().create_timer(2).timeout

        # Send data.
        print("> Sending test packet.")
        socket.send_text("Test packet")
    else:
        push_error("Unable to connect.")
        set_process(false)


func _process(_delta):
    # Call this in `_process()` or `_physics_process()`.
    # Data transfer and state updates will only happen when calling this function.
    socket.poll()

    # get_ready_state() tells you what state the socket is in.
    var state = socket.get_ready_state()

    # `WebSocketPeer.STATE_OPEN` means the socket is connected and ready
    # to send and receive data.
    if state == WebSocketPeer.STATE_OPEN:
        while socket.get_available_packet_count():
            var packet = socket.get_packet()
            if socket.was_string_packet():
                var packet_text = packet.get_string_from_utf8()
                print("< Got text data from server: %s" % packet_text)
            else:
                print("< Got binary data from server: %d bytes" % packet.size())

    # `WebSocketPeer.STATE_CLOSING` means the socket is closing.
    # It is important to keep polling for a clean close.
    elif state == WebSocketPeer.STATE_CLOSING:
        pass

    # `WebSocketPeer.STATE_CLOSED` means the connection has fully closed.
    # It is now safe to stop polling.
    elif state == WebSocketPeer.STATE_CLOSED:
        # The code will be `-1` if the disconnection was not properly notified by the remote peer.
        var code = socket.get_close_code()
        print("WebSocket closed with code: %d. Clean: %s" % [code, code != -1])
        set_process(false) # Stop processing.

這將印出類似：

Connecting to wss://echo.websocket.org...
< Got text data from server: Request served by 7811941c69e658
> Sending test packet.
< Got text data from server: Test packet

基本伺服器範例

這個範例將示範如何建立一個 WebSocket 伺服器收聽連線，並進行資料交換。

extends Node

# The port we will listen to.
const PORT = 9080

# Our TCP Server instance.
var _tcp_server = TCPServer.new()

# Our connected peers list.
var _peers: Dictionary[int, WebSocketPeer] = {}

var last_peer_id := 1


func _ready():
    # Start listening on the given port.
    var err = _tcp_server.listen(PORT)
    if err == OK:
        print("Server started.")
    else:
        push_error("Unable to start server.")
        set_process(false)


func _process(_delta):
    while _tcp_server.is_connection_available():
        last_peer_id += 1
        print("+ Peer %d connected." % last_peer_id)
        var ws = WebSocketPeer.new()
        ws.accept_stream(_tcp_server.take_connection())
        _peers[last_peer_id] = ws

    # Iterate over all connected peers using "keys()" so we can erase in the loop
    for peer_id in _peers.keys():
        var peer = _peers[peer_id]

        peer.poll()

        var peer_state = peer.get_ready_state()
        if peer_state == WebSocketPeer.STATE_OPEN:
            while peer.get_available_packet_count():
                var packet = peer.get_packet()
                if peer.was_string_packet():
                    var packet_text = packet.get_string_from_utf8()
                    print("< Got text data from peer %d: %s ... echoing" % [peer_id, packet_text])
                    # Echo the packet back.
                    peer.send_text(packet_text)
                else:
                    print("< Got binary data from peer %d: %d ... echoing" % [peer_id, packet.size()])
                    # Echo the packet back.
                    peer.send(packet)
        elif peer_state == WebSocketPeer.STATE_CLOSED:
            # Remove the disconnected peer.
            _peers.erase(peer_id)
            var code = peer.get_close_code()
            var reason = peer.get_close_reason()
            print("- Peer %s closed with code: %d, reason %s. Clean: %s" % [peer_id, code, reason, code != -1])

當有用戶端連線時，將印出類似以下內容：

Server started.
+ Peer 2 connected.
< Got text data from peer 2: Test packet ... echoing

進階聊天室範例

一個更進階的聊天範例 (其選擇性地使用中級多人連線抽象層) 以及一個高階多人連線範例，可在 godot 範例專案 中的 networking/websocket_chat 和 networking/websocket_multiplayer 下取得。