Behaviour for GameServer hooks/callbacks.

Implement this behaviour in your hooks module to receive lifecycle events from the GameServer and run custom game logic.

Setup

1. Create a module implementing this behaviour
2. Configure it in your GameServer instance

Example

defmodule MyGame.Hooks do
  @behaviour GameServer.Hooks

  @impl true
  def after_user_register(user) do
    # Give new users starting coins
    GameServer.Accounts.update_user(user, %{
      metadata: Map.put(user.metadata || %{}, "coins", 100)
    })
  end

  @impl true
  def after_user_login(user) do
    # Log login
    :ok
  end

  @impl true
  def after_user_updated(user) do
    # React to user profile changes (e.g., sync display name to external system)
    :ok
  end

  # Lobby hooks
  @impl true
  def before_lobby_create(attrs) do
    # Validate or modify lobby creation attributes
    {:ok, attrs}
  end

  @impl true
  def after_lobby_create(_lobby), do: :ok

  @impl true
  def before_lobby_join(user, lobby, opts) do
    # Check if user can join (e.g., level requirements)
    {:ok, {user, lobby, opts}}
  end

  @impl true
  def before_group_create(user, attrs) do
    # Check if user can create a group (e.g., enough coins in metadata)
    coins = get_in(user.metadata, ["coins"]) || 0
    if coins >= 50 do
      {:ok, attrs}
    else
      {:error, :not_enough_coins}
    end
  end

  @impl true
  def before_group_join(user, group, opts) do
    # Check if user can join group (e.g., level requirements based on metadata)
    {:ok, {user, group, opts}}
  end

  @impl true
  def after_lobby_join(_user, _lobby), do: :ok

  @impl true
  def before_lobby_leave(user, lobby) do
    {:ok, {user, lobby}}
  end

  @impl true
  def after_lobby_leave(_user, _lobby), do: :ok

  @impl true
  def before_lobby_update(_lobby, attrs) do
    {:ok, attrs}
  end

  @impl true
  def after_lobby_update(_lobby), do: :ok

  @impl true
  def before_lobby_delete(lobby) do
    {:ok, lobby}
  end

  @impl true
  def after_lobby_delete(_lobby), do: :ok

  @impl true
  def before_user_kicked(host, target, lobby) do
    {:ok, {host, target, lobby}}
  end

  @impl true
  def after_user_kicked(_host, _target, _lobby), do: :ok

  @impl true
  def after_lobby_host_change(_lobby, _new_host_id), do: :ok

  # Custom RPC handlers - define your own functions!
  # These are called from game clients via the RPC channel.
  #
  # def give_coins(amount, opts) do
  #   caller = Keyword.get(opts, :caller)
  #   # Update user's coins...
  #   {:ok, %{new_balance: 150}}
  # end
end

Hook Types

User Lifecycle Hooks

• after_user_register/1 - Called after a new user registers
• after_user_login/1 - Called after a user logs in
• after_user_updated/1 - Called after a user is updated (fire-and-forget)

Lobby Lifecycle Hooks

Before hooks can block operations by returning {:error, reason}. After hooks are fire-and-forget.

• before_lobby_create/1 - Before lobby creation, receives attrs map

• after_lobby_create/1 - After lobby is created

• before_lobby_join/3 - Before user joins lobby

• after_lobby_join/2 - After user joins lobby

• before_group_create/2 - Before group creation, receives (user, attrs). Return {:ok, attrs} to allow or {:error, reason} to block

• after_group_create/1 - After group is created (fire-and-forget)

• before_group_join/3 - Before user is accepted into a group (public join, invite accept, or request approval)

• before_chat_message/2 - Before a chat message is sent, receives (user, attrs). Return {:ok, attrs} to allow (and optionally modify), or {:error, reason} to block

• after_chat_message/1 - After a chat message is persisted (fire-and-forget)

• before_lobby_leave/2 - Before user leaves lobby

• after_lobby_leave/2 - After user leaves lobby

• before_lobby_update/2 - Before lobby is updated

• after_lobby_update/1 - After lobby is updated

• before_lobby_delete/1 - Before lobby is deleted

• after_lobby_delete/1 - After lobby is deleted

• before_user_kicked/3 - Before user is kicked from lobby

• after_user_kicked/3 - After user is kicked from lobby

• after_lobby_host_change/2 - After lobby host changes

• before_kv_get/2 - Called before a KV get to determine whether a key should be publicly readable (:public) or restricted (:private)

  Custom RPC Functions

  Game clients can call RPCs exposed by your hooks module in two ways:

  1. Exported functions: any exported function in your hooks module (other than the callbacks above) can be called from game clients.

  2. Dynamic functions (custom hooks): your after_startup/0 callback may return a list of dynamic exports describing additional callable function names that do not need to exist as exported Elixir functions. These dynamic calls are dispatched to on_custom_hook/2.

  # Client calls: rpc("give_coins", {amount: 50}) def give_coins(amount, opts) do

  caller = Keyword.get(opts, :caller)
  # Your game logic here
  {:ok, %{success: true}}

  end

Return values:

• {:ok, data} - Success, data is sent back to client
• {:error, reason} - Error, reason is sent back to client
• :ok - Success with no data