PlanetSide 2 API v0.1.3 PS2.SocketClient behaviour View Source

A module that handles all interaction with Daybreak Games' Planetside 2 Event Streaming service.

Implementation

To handle incoming game events, your module should use PS2.SocketClient and call PS2.SocketClient.start_link/2, passing the desired subscription info (Example implementation below). Events will now be sent to your SocketClient, which you handle though handle_event/1. Note that you should have a catch-all handle_event/1 callback in the case of unhandled events (see example), otherwise the client will crash whenever it receives an unhandled event.

Example implementation:

defmodule MyApp.EventStream do
  use PS2.SocketClient

    def start_link do
        subscriptions = [
            events: ["PlayerLogin"],
            worlds: ["Connery", "Miller", "Soltech"],
            characters: ["all"]
        ]
    PS2.SocketClient.start_link(__MODULE__, subscriptions)
  end

  @impl PS2.SocketClient
  def handle_event({"PlayerLogin", payload}) do
    IO.puts "PlayerLogin: #{payload["character_id"]}"
  end

  # Catch-all callback.
  @impl PS2.SocketClient
  def handle_event({event_name, _payload}) do
    IO.puts "Unhandled event: #{event_name}"
  end
end

The second param of PS2.SocketClient.start_link/2 is the subscription info your client is interested in. See the link below to find a list of all event names. You may also specify "all" in any of the subscription fields (Note: if a field is missing, "all" will be the default.) If you want to receive heartbeat messages (which contain world status updates), include "heartbeat" in your event subscriptions.

For more information, see the official documentation: https://census.daybreakgames.com/#websocket-details

Link to this section Summary

Types

A two-element tuple representing an in-game event.

An element in a keyword list where the key is either :events, :worlds, or :characters, and the value is a list of event names, world names, or character IDs with respect to the key.

A list of subscriptions.

Functions

Starts the client process, subscribing to the event stream and listens for relevant events.

Link to this section Types

Specs

event() :: {String.t(), map()}

A two-element tuple representing an in-game event.

The first element is the event name (String), and the second element is the event payload (Map). Example: {"VehicleDestroy", %{attacker_character_id: "5428812948092239617", ... }}

For a list of example payloads, see Daybreak's documentation: https://census.daybreakgames.com/#websocket-details

Specs

subscription() ::
  {:events, [String.t()]}
  | {:worlds, [String.t()]}
  | {:characters, [integer() | String.t()]}

An element in a keyword list where the key is either :events, :worlds, or :characters, and the value is a list of event names, world names, or character IDs with respect to the key.

Specs

subscription_list() :: [subscription()] | []

A list of subscriptions.

Link to this section Functions

Link to this function

start_link(module, subscriptions)

View Source

Specs

start_link(atom(), subscription_list()) :: {:ok, pid()}

Starts the client process, subscribing to the event stream and listens for relevant events.

Link to this section Callbacks

Specs

handle_event(event()) :: any()