GameServer.Lobbies (game_server_sdk v0.1.0)

View Source

Context module for lobby management: creating, updating, listing and searching lobbies.

This module contains the core domain operations; more advanced membership and permission logic will be added in follow-up tasks.

Usage

# Create a lobby (returns {:ok, lobby} | {:error, changeset})
{:ok, lobby} = GameServer.Lobbies.create_lobby(%{name: "fun-room", title: "Fun Room", host_id: host_id})

# List public lobbies (paginated/filterable)
lobbies = GameServer.Lobbies.list_lobbies(%{}, page: 1, page_size: 25)

# Join and leave
{:ok, user} = GameServer.Lobbies.join_lobby(user, lobby.id)
{:ok, _} = GameServer.Lobbies.leave_lobby(user)

# Get current lobby members
members = GameServer.Lobbies.get_lobby_members(lobby)

# Subscribe to global or per-lobby events
:ok = GameServer.Lobbies.subscribe_lobbies()
:ok = GameServer.Lobbies.subscribe_lobby(lobby.id)

PubSub Events

This module broadcasts the following events:

  • "lobbies" topic (global lobby list changes):

    • {:lobby_created, lobby} - a new lobby was created
    • {:lobby_updated, lobby} - a lobby was updated
    • {:lobby_deleted, lobby_id} - a lobby was deleted

  • "lobby:<lobby_id>" topic (per-lobby membership changes):

    • {:user_joined, lobby_id, user_id} - a user joined the lobby
    • {:user_left, lobby_id, user_id} - a user left the lobby
    • {:user_kicked, lobby_id, user_id} - a user was kicked from the lobby
    • {:lobby_updated, lobby} - the lobby settings were updated
    • {:host_changed, lobby_id, new_host_id} - the host changed (e.g., after host leaves)

Note: This is an SDK stub. Calling these functions will raise an error. The actual implementation runs on the GameServer.

Summary

Functions

create_lobby(attrs)

Creates a new lobby.

delete_lobby(lobby)
get_lobby(id)
get_lobby_members(lobby_id)

Gets all users currently in a lobby.

join_lobby(user, lobby_arg, opts)
kick_user(arg1, lobby, arg3)

Kick a user from a lobby. Only the host can kick users. Returns {:ok, user} on success, {:error, reason} on failure.

leave_lobby(user)
list_lobbies(filters, opts)

List lobbies. Accepts optional search filters.

subscribe_lobbies()

Subscribe to global lobby events (lobby created, updated, deleted).

subscribe_lobby(lobby_id)

Subscribe to a specific lobby's events (membership changes, updates).

update_lobby(lobby, attrs)

Updates an existing lobby.

Functions

create_lobby(attrs)

@spec create_lobby(GameServer.Types.lobby_create_attrs()) ::
  {:ok, GameServer.Lobbies.Lobby.t()} | {:error, Ecto.Changeset.t() | term()}

Creates a new lobby.

## Attributes

See GameServer.Types.lobby_create_attrs/0 for available fields.

delete_lobby(lobby)

@spec delete_lobby(GameServer.Lobbies.Lobby.t()) ::
  {:ok, GameServer.Lobbies.Lobby.t()} | {:error, Ecto.Changeset.t() | term()}

get_lobby(id)

@spec get_lobby(integer() | String.t()) :: GameServer.Lobbies.Lobby.t() | nil

get_lobby_members(lobby_id)

@spec get_lobby_members(GameServer.Lobbies.Lobby.t() | integer() | String.t()) :: [
  GameServer.Accounts.User.t()
]

Gets all users currently in a lobby.

Returns a list of User structs.

## Examples

  iex> get_lobby_members(lobby)
  [%User{}, %User{}]

  iex> get_lobby_members(lobby_id)
  [%User{}]

join_lobby(user, lobby_arg, opts)

@spec join_lobby(
  GameServer.Accounts.User.t(),
  GameServer.Lobbies.Lobby.t() | integer() | String.t(),
  map() | keyword()
) :: {:ok, GameServer.Accounts.User.t()} | {:error, term()}

kick_user(arg1, lobby, arg3)

@spec kick_user(
  GameServer.Accounts.User.t(),
  GameServer.Lobbies.Lobby.t(),
  GameServer.Accounts.User.t()
) :: {:ok, GameServer.Accounts.User.t()} | {:error, term()}

Kick a user from a lobby. Only the host can kick users. Returns {:ok, user} on success, {:error, reason} on failure.

leave_lobby(user)

@spec leave_lobby(GameServer.Accounts.User.t()) :: {:ok, term()} | {:error, term()}

list_lobbies(filters, opts)

@spec list_lobbies(map(), GameServer.Types.lobby_list_opts()) :: [
  GameServer.Lobbies.Lobby.t()
]

List lobbies. Accepts optional search filters.

## Filters

* `:title` - Filter by title (partial match)
* `:is_passworded` - boolean or string 'true'/'false' (omit for any)
* `:is_locked` - boolean or string 'true'/'false' (omit for any)
* `:min_users` - Filter lobbies with max_users >= value
* `:max_users` - Filter lobbies with max_users <= value
* `:metadata_key` - Filter by metadata key
* `:metadata_value` - Filter by metadata value (requires metadata_key)

## Options

See GameServer.Types.lobby_list_opts/0 for available options.

subscribe_lobbies()

@spec subscribe_lobbies() :: :ok | {:error, term()}

Subscribe to global lobby events (lobby created, updated, deleted).

subscribe_lobby(lobby_id)

@spec subscribe_lobby(integer()) :: :ok | {:error, term()}

Subscribe to a specific lobby's events (membership changes, updates).

update_lobby(lobby, attrs)

@spec update_lobby(
  GameServer.Lobbies.Lobby.t(),
  GameServer.Types.lobby_update_attrs()
) ::
  {:ok, GameServer.Lobbies.Lobby.t()} | {:error, Ecto.Changeset.t() | term()}

Updates an existing lobby.

## Attributes

See GameServer.Types.lobby_update_attrs/0 for available fields.