Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

使用 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 下取得。