Server API Authorization

Game Servers are automatically provided a server token when hosted in the Nodecraft Hosting platform. 3rd party hosting licenses are planned for a future release, where players can self-host and receive their own server token. It’s recommended you use the Nodecraft STudio SDK to receive these tokens or use an environment variable NODECRAFT_TOKEN for your Game Server to send the token when making API calls.

Game Server Events

Handling Player Identity is handled when the Player initially connects to Nodecraft Studio. That ident process is extended to Server Authorization when players attempt to connect and authorize themselves to your Game Server. The Game Client is given a session token which is validated by the Game Server via the Nodecraft Studio API.

The importance of this guarantees that every player connecting is validated for the following:

• Has a valid session with an Identity Provider, complete with username, avatar, & ID
• Has authorization to join the server via an invite, public, or rather access controls
• The connecting player has accepted the Server Rules, if it’s a Community Server
• The connecting player has provided the correct Server Password, if the server is password-protected
• Is not actively banned from the server from Server Moderation
• The player has completed the Server Queue and has a join token
• Requires no 3rd party libraries for server-validated authorization & identity

Player Join: Validate authorization token

Once a Game Client has connected to your Game Server, we recommend you require the session token is provided as the first message with a low threshold of delay allowed within 2-5 seconds, with no longer than 10 seconds. If you are using a Nodecraft Studio SDK, this will be provided as a Game Hook. Read the guide for the SDK you are using.

Using the GameServerPlayerJoin API call will consume the session token returned by the Game Client. It’s important that this token be consumed as fast as possible, as it expires within 60 seconds. This will return a valid player details that includes:

• Player:
  • ID — unique Nodecraft Studio Player ID
  • username — Player Username as defined by the ident platform
  • ident — unique ID provided by the ident platform
  • ident_type — string representing the ident platform
  • image_avatar — URL to avatar for this user
• Session ID — Unique session ID for this player. This needs to be stored and used in later calls
• Analytics Session ID — Unique Session ID for this player to be used for GDPR compliant analytics. If provided, this needs to be stored and used in later calls.

We recommend each Game Server store the information for this connection with this full payload of data.

Player Leave: Terminating The Session

Once the connection ends for the player set in the above section, it’s required that the Game Server call the GameServerPlayerLeave API. This ensures new Players in the Server Queue can join the server, the player can join other game servers, and if analytics is enabled will track analytics for both the game developer and the server owner.

You’ll need the Session ID and, optionally, the Analytics Session ID to finalize this request. There is also an optional session_end_message, which can be helpful to see why players are joining with analytics if you use common phrases or strings.

Heartbeat: Checkin for Moderation and Data Shift

The reality is that the internet can be an unreliable network, so we can make sure that all session data is reviewed for missing details. For example if a Player Leave event didn’t successfully get sent, this heartbeat will correct the data.

This GameServerHeartbeat API call also returns data about moderation events that need to occur. This is usually authorized by the Server Moderation events, which means this heartbeat needs to occur frequently.

A Game Server Heartbeat should ideally occur every 7 seconds, but no more than every 6 seconds and no more than every 10 seconds. Additionally, you are required to send an ISO 8601 formatted date, marking the last response time you received from the Heartbeat call.

Kicking Players from Heartbeats

When kicks are returned in the above Heartbeat, it’s required that the Game Server send a GameServerPlayerKick API after the player’s connection is terminated. This ensures the heartbeat knows that the Player was kicked.