Tube Godot Addon

Tube implements a server-client architecture for peer-to-peer connectivity. One peer is designated as the server, while all other peers act as clients that connect to it.

The server's primary responsibility is relaying Godot's High-level Multiplayer RPCs between peers. Connectivity is established via WebRTC, which requires three components for the initial signaling phase:

1. Signaling servers: Used to exchange connection initialization messages.
2. STUN servers: Used to help peers determine their public addresses.
3. TURN servers (optional): Used as relays if a direct peer-to-peer connection cannot be established (e.g., when both peers are behind a symmetric NAT).

Note: Tube attempts to use UPnP port mapping to open ports automatically when a TURN server is unavailable, but this is not supported on the Web platform.

On a local network, Tube can use local signaling, which does not require external STUN or TURN servers.

In this mode, the server peer listens on a determined port, and joining peers broadcast their signaling data across the network to the server's destination. Once signaling is complete, peers automatically transition to a WebRTC connection.

Limitation: Local signaling is unavailable on Web builds because the Web platform cannot open listening ports.

For online play, Tube uses WebTorrent tracker servers as signaling servers.

To improve connection reliability, it is recommended to use multiple public trackers. If public trackers are unstable, you should consider deploying your own tracker servers.

To install Tube, copy the addons/tube folder into your Godot project's addons folder. Alternatively, you can download it directly from the Godot Asset Library.

After copying the files, you must activate the addon in your project:

1. Open Project Settings.
2. Navigate to the Plugins tab.
3. Enable Tube.

Requirements:

• Godot Version: Developed for Godot 4.5; works with other Godot 4.x versions. Not compatible with Godot 3.
• WebRTC Support: Works automatically on HTML5 exports. For other platforms (Windows, macOS, Linux, Android, iOS), you must install the webrtc-native GDExtension plugin.
• Android Permissions: If exporting to Android, you must enable INTERNET and CHANGE_WIFI_MULTICAST_STATE in the Android export preset.

Copy addons/tube to your project's addons/ folder

To visualize and debug internal network activity, use the TubeInspector tool.

How to use:

1. Add the scene located at /addons/tube/tube_inspector.tscn to your project.
2. Assign your active TubeClient to the inspector.

Key Debugging Fields:

• NAT hole punching: Shows if a connection can be established via NAT hole punching. If unknown, try different STUN servers.
• UPnP port mapping: Shows if UPnP is available for port mapping. This can help bypass symmetric NAT issues.

Note: Latency display and chat features in the inspector require the TubeInspector to be part of the MultiplayerAPI scene tree.

To deploy your own WebTorrent tracker, you can use the Official Webtorrent Tracker or OpenWebTorrent Tracker.

Requirements & Best Practices:

• The tracker must be configured with WebSocket support accessible over the internet.
• Set the tracker URL in your TubeContext.
• Use secure WebSockets (WSS/TLS). Many browsers will block non-secure communication, and WSS ensures reliable, encrypted signaling.

To improve connection reliability (especially to bypass symmetric NAT issues), you can host your own TURN server using coturn or eturnal. These can also function as STUN servers.

Setup:

1. Deploy your TURN/STUN server.
2. Add the server's URL and credentials to your TubeContext configuration.

Security Recommendation: Use ephemeral credentials (generated dynamically via a secure backend) to prevent unauthorized access to your TURN server.

A TubeContext is a Resource that defines the session connection configuration. You must create one for your project via FileSystem inspector -> Create New -> TubeContext.

Required Configuration:

• App ID: A unique 15-character ASCII string. It must be identical across all game instances. You can use the Generate App ID button in the inspector.

Web Build Requirements (Mandatory for Web): If you are targeting Web builds, you must also configure the following (these can be skipped for local-only play):

• Trackers URLs: Add WebRTC tracker URLs (e.g., wss://tracker.openwebtorrent.com).
• Stun Servers URLs: Add STUN server URLs (e.g., stun:stun.l.google.com:19302).

in Godot FileSystem inspector -> Create New -> TubeContext

Once peers are connected via TubeClient, use Godot's High-Level Multiplayer system (RPCs, MultiplayerSpawner, MultiplayerSynchronizer) to handle game logic.

Important: If the server is also a player, you must use the call_local RPC mode to ensure the server executes the logic locally.

# Example: Sending input to the server
func _on_some_input():
    transfer_some_input.rpc_id(1) # Send only to the server (ID 1)

# The RPC implementation
@rpc("any_peer", "call_local", "reliable")
func transfer_some_input():
    # The server can identify the sender
    var sender_id = multiplayer.get_remote_sender_id()
    # Process logic here

@rpc("any_peer", "call_local", "reliable")
func transfer_some_input():
    var sender_id = multiplayer.get_remote_sender_id()
    # Process the input and affect game logic.

The server player has administrative control over the session:

• Kick a player: Call kick_peer(p_peer_id: int) to remove a specific peer.
• Refuse new connections: Set refuse_new_connections = true to prevent new players from joining.
• Leave a session: Any player can call leave_session(). If the server calls this, the session is terminated for all participants.

A TubeClient is a Node that manages network connections and multiplayer peers. It must be present in the scene tree to function.

Setup Steps:

1. Add a TubeClient as a child node to your scene.
2. Assign your created TubeContext to the Context property of the TubeClient.

Available Properties:

• Context: The TubeContext resource used for connections.
• peer_signaling_timeout: Timeout duration for peer signaling.
• peer_signaling_max_attempts: Maximum number of attempts for peer signaling.
• multiplayer_root_node: The node where Godot's MultiplayerAPI is configured (defaults to the SceneTree root).

in Godot Scene inspector -> Add Child Node -> TubeClient