DOCSEARCHbyAlgolia
Submit Docs

GodotPhoenixChannels

repository·master·Indexed 43 days ago

https://github.com/alfredbaudisch/godotphoenixchannels

A GDScript implementation of the Phoenix Channels API that enables Godot games to connect to real-time Elixir/Phoenix backends via WebSockets. It provides support for Phoenix Socket, Channels, and Presence features, with compatible versions for Godot 3 and Godot 4.

Tokens
1.6K
Snippets
4
Records
6
Agent score
5%

What's inside GodotPhoenixChannels

  1. How PhoenixSocket, PhoenixChannel, and PhoenixPresence work together

    master

    The library follows the design patterns of the official Phoenix JavaScript client, using Godot's WebSocketClient for transport. The hierarchy of connection is as follows:

    1. PhoenixSocket: The entry point. It manages the connection to the Phoenix server (e.g., ws://localhost:4000/socket), handles heartbeats, reconnection timers, and socket-level events.
    2. PhoenixChannel: Created via a PhoenixSocket. It represents a specific topic (e.g., game:abc) and handles joining, leaving, pushing messages, and receiving events.
    3. PhoenixPresence: An optional component passed to a PhoenixChannel to enable tracking of connected clients (Presence) within that channel.

    When a Node is freed, the library automatically handles disconnection and channel leaving.

  2. Run the Elixir Demo Server

    master

    If you want to test the Godot client against a local Elixir server, use the server provided in the demo repository:

    1. Navigate to the server directory: cd Demo/server
    2. Install dependencies: mix deps.get
    3. Start the Phoenix server: iex -S mix phx.server

    Once running, connect your Godot client to ws://localhost:4000/socket.

    cd Demo/server
mix deps.get
iex -S mix phx.server

  3. Install GodotPhoenixChannels

    master

    You can install the library using one of two methods depending on your Godot version:

    Using Godot Asset Library

    • Godot 4: Search for the addon in the AssetLib.
    • Godot 3: Search for the addon in the AssetLib.

    Manual Installation

    Clone or download the repository from the correct branch:

    • Godot 4 branch: https://github.com/alfredbaudisch/GodotPhoenixChannels/tree/4.0
    • Godot 3 branch: https://github.com/alfredbaudisch/GodotPhoenixChannels/tree/3.x

  4. Use PhoenixPresence to track connected clients

    master

    To track presence, create a PhoenixPresence instance and pass it when creating a PhoenixChannel. This allows you to listen to client join/leave events.

    Presence Events:

    • on_join: Triggered when a new client joins. Returns joins.
    • on_leave: Triggered when a client leaves. Returns leaves.
    var presence : PhoenixPresence = PhoenixPresence.new()

# Subscribe to Presence events
presence.connect("on_join", self, "_on_Presence_join")
presence.connect("on_leave", self, "_on_Presence_leave")

# Pass the presence instance to the channel
channel = socket.channel("game:abc", {}, presence)

func _on_Presence_join(joins):
    print("Presence joined: ", joins)

func _on_Presence_leave(leaves):
    print("Presence left: ", leaves)

  5. Use PhoenixSocket to connect to a Phoenix server

    master

    Initialize a PhoenixSocket with the WebSocket URL and an optional params dictionary (useful for authentication tokens). You must connect listeners for socket events before calling connect_socket().

    Socket Events:

    • on_open
    • on_close
    • on_error
    • on_connecting (receives a boolean is_connecting)
    var socket : PhoenixSocket

socket = PhoenixSocket.new("ws://localhost:4000/socket", {
  params = {user_id = 10, token = "some_token"}
})

# Subscribe to Socket events
socket.connect("on_open", self, "_on_Socket_open")
socket.connect("on_close", self, "_on_Socket_close")
socket.connect("on_error", self, "_on_Socket_error")
socket.connect("on_connecting", self, "_on_Socket_connecting")

# Must be added to the scene tree to function
call_deferred("add_child", socket, true)

# Connect!
socket.connect_socket()

  6. Use PhoenixChannel to join topics and handle events

    master

    Channels are created from a PhoenixSocket instance. You can optionally pass a PhoenixPresence instance to the channel.

    Channel Events:

    • on_event: Triggered when a broadcast or a push reply is received. Returns (event, payload, status).
    • on_join_result: Triggered when a join attempt succeeds or fails. Returns (status, result).
    • on_error: Triggered on channel errors.
    • on_close: Triggered when the channel closes.

    Pushing Messages: Use channel.push("event_name", {payload}) to send data to the server.

    # Create a Channel (optionally passing a presence instance)
channel = socket.channel("game:abc", {}, presence)

# Subscribe to Channel events
channel.connect("on_event", self, "_on_Channel_event")
channel.connect("on_join_result", self, "_on_Channel_join_result")
channel.connect("on_error", self, "_on_Channel_error")
channel.connect("on_close", self, "_on_Channel_close")

# To join the channel, call join() inside a socket 'on_open' callback
func _on_Socket_open(payload):
    channel.join()

# To send data to the server
channel.push("event_name", {"some": "param"})

# To receive data
func _on_Channel_event(event, payload, status):
    print("Received event: ", event, " Payload: ", payload)