Skip to content

Home

Jump to bottom
Andrew Bates edited this page Aug 22, 2024 · 14 revisions

EVR Game Server wiki

[Guilds|Guilds.md] [GameServers|GameServers.md] [Matchmaking|Matchmaking.md]

API

Obtaining a Session Token

Session Tokens are required to use non-public API endpoints.

Authenticate with user_id, discord_id, or username.

Request:

curl --location 'http://localhost:7350/v2/rpc/account/authenticate/password?unwrap=null&http_key=95cb0fce-dead-beef-dead-20a4cce4942d' \
--header 'Content-Type: application/json' \
--data '{
        "user_id": "08152ad4-dead-beef-dead-ee5501eb94d7",
        "password": "somepassword"
}'

Returns:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWQiOiI5MDNmODYzMC1mMjkwLTRjMzMtODMyMS0xNDczZDc3ODE2OWMiLCJ1aWQiOiIwODE1MmFkNC1mMmJlLTRmOTMtODNiOS1lZTU1MDFlYjk0ZDciLCJ1c24iOiJzcHJvY2tlZSIsImV4cCI6MTcxODgzNzUxM30.ryE1T7vR1OgsT08M9P8gY518619eISYs1RbgefnUkW4",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWQiOiI5MDNmODYzMC1mMjkwLTRjMzMtODMyMS0xNDczZDc3ODE2OWMiLCJ1aWQiOiIwODE1MmFkNC1mMmJlLTRmOTMtODNiOS1lZTU1MDFlYjk0ZDciLCJ1c24iOiJzcHJvY2tlZSIsImV4cCI6MTcxODgzMzkxM30.RhA2dU1DFwE-ym257Q4lB16wn1OmCt6bTvoZeBHatME"
}

To refresh the token:

curl --location 'http://localhost:7350/v2/rpc/account/authenticate/password?unwrap=null&http_key=95cb0fce-b529-4910-801c-20a4cce4942d' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Og==' \
--data '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWQiOiI5MDNmODYzMC1mMjkwLTRjMzMtODMyMS0xNDczZDc3ODE2OWMiLCJ1aWQiOiIwODE1MmFkNC1mMmJlLTRmOTMtODNiOS1lZTU1MDFlYjk0ZDciLCJ1c24iOiJzcHJvY2tlZSIsImV4cCI6MTcxODgzMzkxM30.RhA2dU1DFwE-ym257Q4lB16wn1OmCt6bTvoZeBHatME"
}'

Returns:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWQiOiI5MDNmODYzMC1mMjkwLTRjMzMtODMyMS0xNDczZDc3ODE2OWMiLCJ1aWQiOiIwODE1MmFkNC1mMmJlLTRmOTMtODNiOS1lZTU1MDFlYjk0ZDciLCJ1c24iOiJzcHJvY2tlZSIsImV4cCI6MTcxODgzODc0NX0.29NaXG-Auw0W8sqdlNJcKL-KS5F8mS-zl3BemUEiHK4",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWQiOiI5MDNmODYzMC1mMjkwLTRjMzMtODMyMS0xNDczZDc3ODE2OWMiLCJ1aWQiOiIwODE1MmFkNC1mMmJlLTRmOTMtODNiOS1lZTU1MDFlYjk0ZDciLCJ1c24iOiJzcHJvY2tlZSIsImV4cCI6MTcxODgzNTE0NX0.IsJ7DAQIreK0brTAMkmUoytj4-c_XHlwWvuAW0jJ1_0"
}

RPC Endpoints

To authenticate to the endpoints, you will need the HTTP key, and a valid session token

Account Lookup - /v2/rpc/account/lookup

To lookup the details of an account:

curl --location 'http://localhost:7350/v2/rpc/account/lookup?unwrap=null' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwODE1MmFkNC1mMmJlLTRmOTMtODNiOS1lZTU1MDFlYjk0ZDciLCJ1c24iOiJzcHJvY2tlZSIsImV4cCI6MTcxODg0MDIxNX0.Jx7uy8rdL55_psi72cf0OO9zuO4JtHc5-RJ_xQySrrk' \
--data '{
    "discord_id": "695081603180789771"
}'

Returns:

{
    "id": "08152ad4-f2be-4f93-83b9-ee5501eb94d7",
    "discord_id": "695081603180789771",
    "username": "sprockee",
    "display_name": "sprockee",
    "avatar_url": "https://cdn.discordapp.com/avatars/695081603180789771/0d2cf2e3e861a9491894bde54a81a54b.png?size=512"
}

Player Lookup - /v2/rpc/account/lookup

Player lookup will return the Discord ID, Username, and Nakama ID for exact matches of a lookup.

NOTE: you can search for discord_id, user_id, or username. For example:

curl --location 'http://localhost:7350/v2/rpc/account/lookup?unwrap=null' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIwODE1MmFkNC1mMmJlLTRmOTMtODNiOS1lZTU1MDFlYjk0ZDciLCJ1c24iOiJzcHJvY2tlZSIsImV4cCI6MTcxODg3NTkyNX0.fHSusH-aqMN9iVC_goyfl7TH46OTv4jYXCt3JQhylYY' \
--data '{
    "discord_id": "695081603180789771"
}'

Response:

{
    "id": "08152ad4-f2be-4f93-83b9-ee5501eb94d7",
    "discord_id": "695081603180789771",
    "username": "sprockee",
    "display_name": "sprockee",
    "avatar_url": "https://cdn.discordapp.com/avatars/695081603180789771/0d2cf2e3e861a9491894bde54a81a54b.png?size=512"
}

Match Details - /v2/rpc/match

NOTE: If the request payload is empty, all matches are returned.

Request:

Prepare Match - /v2/rpc/match/prepare

Matches can be "prepared" and only started when the first player joins.

Request:

{
    "id": "777f13d6-0080-4b71-8665-9783062c4fc7.dev-nakama",
    "mode": "echo_arena_private",
    "level": "mpl_arena_a",
    "role_alignments": {
        "267489979125596170": "blue",
        "695081603180789771": "orange"
    },
    "start_time": "2024-06-25T10:10:00Z"
}

Response:

{
    "id": "777f13d6-0080-4b71-8665-9783062c4fc7.dev-nakama",
    "signal_payload": "{\n  \"UserId\": \"\",\n  \"Signal\": 2,\n  \"Data\": \"ewogICJpZCI6ICIiLAogICJsb2JieV90eXBlIjogInB1YmxpYyIsCiAgImJyb2FkY2FzdGVyIjogewogICAgImVuZHBvaW50IjogIiIKICB9LAogICJzdGFydGVkIjogZmFsc2UsCiAgInN0YXJ0X3RpbWUiOiAiMjAyNC0wNi0yNVQxMDoxMDowMFoiLAogICJzcGF3bmVkX2J5IjogIjA4MTUyYWQ0LWYyYmUtNGY5My04M2I5LWVlNTUwMWViOTRkNyIsCiAgIm1vZGUiOiAiZWNob19hcmVuYV9wcml2YXRlIiwKICAic2Vzc2lvbl9zZXR0aW5ncyI6IHsKICAgICJhcHBpZCI6ICIiLAogICAgImdhbWV0eXBlIjogMCwKICAgICJsZXZlbCI6IG51bGwKICB9LAogICJsaW1pdCI6IDEyLAogICJ0ZWFtX2FsaWdubWVudHMiOiB7CiAgICAiMDgxNTJhZDQtZjJiZS00ZjkzLTgzYjktZWU1NTAxZWI5NGQ3IjogMSwKICAgICI1YWE4M2M3Ny01MGUwLTQ1OTgtYmZkNi00ZjdiMzliNTAzYmIiOiAwCiAgfQp9\"\n}",
    "label": {
        "id": "777f13d6-0080-4b71-8665-9783062c4fc7.dev-nakama",
        "open": true,
        "lobby_type": "private",
        "broadcaster": {
            "sid": "58fd16b6-3304-11ef-a077-66d3ff8a653b",
            "oper": "c239683b-1183-46b2-9d13-56363958d6ec",
            "group_ids": [
                "e6a5387f-506e-4f05-99cf-977417a146ae"
            ],
            "endpoint": "192.168.56.1:174.58.161.237:6792",
            "version_lock": 14280634968751706381,
            "regions": [
                "default",
                "0xf1e60114d33c122a",
                "0xd5a260c6a990722f",
                "0x2f91d3794c71ad61"
            ],
            "server_id": 3427753309332680033
        },
        "started": false,
        "start_time": "2024-06-25T10:12:49.849537117-05:00",
        "spawned_by": "08152ad4-f2be-4f93-83b9-ee5501eb94d7",
        "group_id": "00000000-0000-0000-0000-000000000000",
        "mode": "echo_arena_private",
        "level": "mpl_arena_a",
        "session_settings": {
            "appid": "1369078409873402",
            "gametype": 691594351282457603,
            "level": 6300205991959903307
        },
        "limit": 12,
        "player_limit": 10,
        "team_size": 5
    }
}

Set Next Match - /v2/rpc/player/setnextmatch

The player's next match may be set by calling this RPC. Once set, the next time the user matchmakes, they will be sent to that match. The target player may be set via user_id or discord_id. If omitted, the caller's next match is set. If the match_id is left blank, the next match value will be cleared.

Note: 'role' is optional, and maybe one of blue, orange, or spectator

Request:

{
    "discord_id": "695081603180789771",
    "match_id": "777f13d6-0080-4b71-8665-9783062c4fc7.dev-nakama",
    "role": "orange",
}

Response:

{
    "user_id": "580230ee-3866-446f-8f3f-6cc68e3c8621",
    "match_id": "777f13d6-0080-4b71-8665-9783062c4fc7.dev-nakama",
    "role": "orange",
}

System Groups

Bots

Member of the Global Bots group may join multiple matches. The game server uses session ID is used to track players in a match, but echo clients/broadcasters use the EVRID (e.g. DMO-123412341234). If the bot tries to join a match that another bot with the same EVR ID, it will be rejected.

Supporting/Requiring Features on Clients/Servers

If there is a need for a client and server to specify a feature, and a client to require that feature. Use the following method.

config.json

  • serverdb_host:
  • features the broadcaster supports
  • matchingservice_host:
  • features= features that the client supports
  • required_features= features that client requires matches that it creates to support

If a game client defines the URL parameter required_features= on the matching_host URL--nakama will--when creating a match:

  • only select a broadcaster that supports the given feature(s).
  • populate the required_features field of the match label.
  • embed the list of required_features= into the SessionSetttings JSON payload of LobbySessionStart.

When a game client attempts to join a match--while missing a feature--, then nakama will reject the join attempt with IncompatibleServer error code of LobbySessionFailure.

It will be up to the game server to vet/confirm/handle clients that improperly have features defined when they shouldn't.

Matches created as a result of LobbyFindSessionRequest will ignore required_features.

Clone this wiki locally