Skip to content

Home

Jump to bottom
Andrew Bates edited this page Aug 1, 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
    }
}

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