Documentation

Home
• Networked multiplayer• Lobbies• Fetch lobbies• API reference

Fetch lobbies

The GDScript plugin gives you access to Gotm's powerful lobby system that lets you fetch lobbies with custom filters and sorting. Try it out!

You can filter and sort your lobbies any way you want with custom properties.

The above game example uses the GDScript plugin to fetch existing lobbies with custom properties. It fetches lobbies depending on its map, difficulty and name. It also sorts the results depending on the lobby's creation time or difficulty. See the source code for more details.

Use cases

Gotm's GDScript plugin provides you the basic building blocks of a lobby system, which gives you much freedom in your own design of your game's lobby experience. Install the plugin directly from the AssetLib in the Godot Editor.

Explore the use cases below to find some inspiration for your game's lobby system.

Lobby browser

See the example project for a live lobby browser example.

GotmLobbyFetch provides stateful pagination out-of-the-box. It can fetch lobbies page-by-page both forwards and backwards.

var fetch = GotmLobbyFetch.new()
var lobbies

## Get the next 5 lobbies...
lobbies = yield(fetch.next(5), "completed")

## And the next...
lobbies = yield(fetch.next(5), "completed")

## And so on...

Quick-join

Let your players join a lobby without browsing or searching in a lobby browser. With quick-joining you could present your players with a simple "Play" button that automatically joins the lobby with most players.

func quick_join():
  var fetch = GotmLobbyFetch.new()
  fetch.sort_property = "player_count"
  fetch.sort_ascending = false

  var lobbies = yield(fetch.first(1), "completed")
  var success = yield(lobbies[0].join(), "completed")

Global lobbies

Give your players the illusion of always-running dedicated servers!

With global lobbies you gather your players in a limited set of lobbies with preset modes, such as deathmatch, free for all and king of the hill. You then present your players with a button for each mode. When pressed, join the matching lobby or host one if it doesn't exist.

func join_global_lobby(mode):
  var fetch = GotmLobbyFetch.new()
  fetch.filter_properties.mode = mode

  var lobbies = yield(fetch.first(1), "completed")
  if not lobbies.empty():
    var success = yield(lobbies[0].join(), "completed")
  else:
    Gotm.host_lobby()
    Gotm.lobby.mode = mode
    Gotm.lobby.hidden = false

Matchmaking

Match players based on their rank by limiting the fetched lobbies to a rank range using GotmLobbyFetch.sort_min and GotmLobbyFetch.sort_max.

Keep widening the range until a match is found.

func do_matchmaking(rank):
  var fetch = GotmLobbyFetch.new()
  fetch.sort_property = "rank"
  fetch.sort_min = rank
  fetch.sort_max = rank

  while true:
    var lobbies = yield(fetch.first(1), "completed")
    if not lobbies.empty():
      var success = yield(lobbies[0].join(), "completed")
      return
    else:
      fetch.sort_min -= 1
      fetch.sort_max += 1

Get started

Install the plugin from the AssetLib in the Godot Editor and follow its installation instructions. The example project already comes with the plugin installed.

This example uses GotmDebug.add_lobby to add test lobbies. Test lobbies do not appear when you run your game on Gotm.

1. Create test lobby

To try out Gotm's lobby-fetching system you first need lobbies to fetch. The plugin lets you create test lobbies that behave as real lobbies. This makes it quick and easy to try out the system.

Call GotmDebug.add_lobby to host a lobby without joining it.

var lobby = GotmDebug.add_lobby()
lobby.name = "My Test Lobby!"

Lobbies are hidden from fetch results by default. Make the lobby visible by setting its hidden property to false.

lobby.hidden = false

You can now fetch it as if it was a real lobby.

var fetch = GotmLobbyFetch.new()
var lobbies = yield(fetch.first(), "completed")

2. Set custom properties

You can attach your own metadata to a lobby as custom properties with GotmLobby.set_property.

lobby.set_property("difficulty", "easy")
lobby.set_property("map", "classic")

You can now fetch the lobby and see its custom properties by calling GotmLobby.get_property.

var difficulty = lobby.get_property("difficulty")
var map = lobby.get_property("classic")

3. Filter

To only fetch lobbies with a particular difficulty or map, you can make them filterable by calling GotmLobby.set_filterable.

lobby.set_filterable("difficulty")
lobby.set_filterable("map")

Now you can filter lobbies with GotmLobbyFetch.filter_properties. For example, fetch lobbies with difficulty easy and map classic with the following code:

fetch.filter_properties.difficulty = "easy"
fetch.filter_properties.map = "classic"

To fetch lobbies with any difficulty you can set its value to null.

fetch.filter_properties.difficulty = null
fetch.filter_properties.map = "classic"

When using GotmLobbyFetch.filter_properties you must set every value that was registered with GotmLobby.set_filterable. For example, the following will fail to fetch our lobby because it does not set map to any value.

fetch.filter_properties.difficulty = null

Always make sure you are setting all properties.

Disable filtering by setting all filter properties to null.

fetch.filter_properties.difficulty = null
fetch.filter_properties.map = null

4. Sort

Make your lobby sortable by difficulty with GotmLobby.set_sortable.

lobby.set_sortable("difficulty")

Now you can sort lobbies by setting GotmLobbyFetch.sort_property. For example, the following sort lobbies by difficulty with the following code:

fetch.sort_property = "difficulty"

When using GotmLobbyFetch.sort_property only lobbies that have registered that property with GotmLobby.set_sortable will be fetched. For example, the following will fail to fetch our lobby because map is not registered as sortable.

fetch.sort_property = "map"

Disable sorting by setting it to "".

fetch.sort_property = ""

5. Search by name

You can search lobbies by name with GotmLobbyFetch.filter_name.

fetch.filter_name = "My Test Lobby!"

This searches for all lobbies whose names contains My Test Lobby!. Since the search is tolerant, these example values would successfully fetch our lobby too:

fetch.filter_name = "my test lobby"
fetch.filter_name = "tEsT"
fetch.filter_name = "MY!!!     "

Disable name-searching by setting it to "".

fetch.filter_name = ""

6. Paginate

You can fetch lobbies page-by-page by using GotmLobbyFetch.next.

var lobbies

## Get the next 5 lobbies...
lobbies = yield(fetch.next(5), "completed")

## And the next...
lobbies = yield(fetch.next(5), "completed")

## And so on...

You can refresh your current page with GotmLobbyFetch.current.

lobbies = yield(fetch.current(5), "completed")

Modifying any property in GotmLobbyFetch will reset its state to the first page.

## Page 1
lobbies = yield(fetch.first(5), "completed")

## Page 2
lobbies = yield(fetch.next(5), "completed")

## Modify state
fetch.name = "abc"

## Page 1
lobbies = yield(fetch.next(5), "completed")

Limitations

Gotm provides you the basic building blocks of a lobby system, which gives you much freedom in your own design of your game's lobby experience. However, there are some restrictions:

  • Custom properties:
    • Must be of types String, int, float or bool.
    • Strings and property names longer than 64 characters are truncated.
    • A lobby can have up to 10 custom properties.
    • A lobby can have up to 3 filterable custom properties.
    • A lobby can have up to 3 sortable custom properties.
  • Up to 8 lobbies can be fetched at a time.