All runtime code is evaluated at server startup and can be used to register functions called hooks.
You can register before hooks to intercept and act on client messages, after hooks to call a function after an event has been processed, and custom RPC hooks which can be called by clients.
There are multiple ways to register a function within the runtime, each of which is used to handle specific behavior between client and server. For example:
Message names #
Provided here is a full list of server messages that can benefit from hooks.
Use the following request names for registering your Before and After hooks:
|AddFriends||Add friends by ID or username to a user’s account.|
|AddGroupUsers||Add users to a group.|
|AuthenticateCustom||Authenticate a user with a custom id against the server.|
|AuthenticateDevice||Authenticate a user with a device id against the server.|
|AuthenticateEmail||Authenticate a user with an email+password against the server.|
|AuthenticateFacebook||Authenticate a user with a Facebook OAuth token against the server.|
|AuthenticateGameCenter||Authenticate a user with Apple’s GameCenter against the server.|
|AuthenticateGoogle||Authenticate a user with Google against the server.|
|AuthenticateSteam||Authenticate a user with Steam against the server.|
|BlockFriends||Block one or more users by ID or username.|
|CreateGroup||Create a new group with the current user as the owner.|
|DeleteAccount||Delete the current user’s account.|
|DeleteFriends||Delete one or more users by ID or username.|
|DeleteGroup||Delete one or more groups by ID.|
|DeleteLeaderboardRecord||Delete a leaderboard record.|
|DeleteNotifications||Delete one or more notifications for the current user.|
|DeleteStorageObjects||Delete one or more objects by ID or username.|
|GetAccount||Fetch the current user’s account.|
|GetUsers||Fetch zero or more users by ID and/or username.|
|Healthcheck||A healthcheck which load balancers can use to check the service.|
|ImportFacebookFriends||Import Facebook friends and add them to a user’s account.|
|JoinGroup||Immediately join an open group, or request to join a closed one.|
|KickGroupUsers||Kick a set of users from a group.|
|LeaveGroup||Leave a group the user is a member of.|
|LinkCustom||Add a custom ID to the social profiles on the current user’s account.|
|LinkDevice||Add a device ID to the social profiles on the current user’s account.|
|LinkEmail||Add an email+password to the social profiles on the current user’s account.|
|LinkFacebook||Add Facebook to the social profiles on the current user’s account.|
|LinkGameCenter||Add Apple’s GameCenter to the social profiles on the current user’s account.|
|LinkGoogle||Add Google to the social profiles on the current user’s account.|
|LinkSteam||Add Steam to the social profiles on the current user’s account.|
|ListChannelMessages||List a channel’s message history.|
|ListFriends||List all friends for the current user.|
|ListGroups||List groups based on given filters.|
|ListGroupUsers||List all users that are part of a group.|
|ListLeaderboardRecords||List leaderboard records.|
|ListMatches||Fetch a list of running matches.|
|ListNotifications||Fetch a list of notifications.|
|ListStorageObjects||List publicly readable storage objects in a given collection.|
|ListUserGroups||List groups the current user belongs to.|
|PromoteGroupUsers||Promote a set of users in a group to the next role up.|
|DemoteGroupUsers||Demote a set of users in a group to a lower role.|
|ReadStorageObjects||Get storage objects.|
|UnlinkCustom||Remove the custom ID from the social profiles on the current user’s account.|
|UnlinkDevice||Remove the device ID from the social profiles on the current user’s account.|
|UnlinkEmail||Remove the email+password from the social profiles on the current user’s account.|
|UnlinkFacebook||Remove Facebook from the social profiles on the current user’s account.|
|UnlinkGameCenter||Remove Apple’s GameCenter from the social profiles on the current user’s account.|
|UnlinkGoogle||Remove Google from the social profiles on the current user’s account.|
|UnlinkSteam||Remove Steam from the social profiles on the current user’s account.|
|UpdateAccount||Update fields in the current user’s account.|
|UpdateGroup||Update fields in a given group.|
|WriteLeaderboardRecord||Write a record to a leaderboard.|
|WriteStorageObjects||Write objects into the storage engine.|
Names are case-insensitive. For more information, see
For real-time before and after hooks, use the following message names:
|ChannelJoin||Join a realtime chat channel.|
|ChannelLeave||Leave a realtime chat channel.|
|ChannelMessageSend||Send a message to a realtime chat channel.|
|ChannelMessageUpdate||Update a message previously sent to a realtime chat channel.|
|ChannelMessageRemove||Remove a message previously sent to a realtime chat channel.|
|MatchCreate||A client to server request to create a realtime match.|
|MatchDataSend||A client to server request to send data to a realtime match.|
|MatchJoin||A client to server request to join a realtime match.|
|MatchLeave||A client to server request to leave a realtime match.|
|MatchmakerAdd||Submit a new matchmaking process request.|
|MatchmakerRemove||Cancel a matchmaking process using a ticket.|
|PartyCreate||A client to server request to create a party.|
|PartyJoin||A client to server request to join a party.|
|PartyLeave||A client to server request to leave a party.|
|PartyPromote||A client to server request to promote a party member.|
|PartyAccept||A client to server request to accept a party join request.|
|PartyRemove||A client to server request to remove a party member.|
|PartyClose||A client to server request to close a party.|
|PartyJoinRequestList||A client to server request to list all join requests for a particular party.|
|PartyMatchmakerAdd||Submit a new party matchmaking process request.|
|PartyMatchmakerRemove||Cancel a party matchmaking process using a ticket.|
|PartyDataSend||A client to server request to send data to a party.|
|StatusFollow||Start following some set of users to receive their status updates.|
|StatusUnfollow||Stop following some set of users to no longer receive their status updates.|
|StatusUpdate||Set the user’s own status.|
Names are case-insensitive. For more information, have a look at
Before hooks #
Any function may be registered to intercept a message received from a client and operate on it (or reject it) based on custom logic. This is useful to enforce specific rules on top of the standard features in the server, or to replace what would otherwise be an invalid input.
Input validation does not apply until after execution of any before hooks, meaning clients can send larger (or otherwise invalid) inputs than the server would normally allow so long as the before hook replaces the input with a valid one. For example, given custom authentication IDs must be between 6-128 bytes, if your external authentication provider returns a longer ID use a before hook to replace that input with a valid ID.
In Go, each hook will receive the request input as a
struct containing the data that will be processed by the server for that request, if that feature is expected to receive an input. In Lua, the second argument will be the incoming
payload is the fourth argument.
You must remember to return the payload at the end of your function in the same structure as you received it.
If you choose to return
nil (Lua) or
payload (or a non-nil
error in Go) the server will halt further processing of that message. This can be used to stop the server from accepting certain messages or disabling/blacklisting certain server features.
After hooks #
Similar to Before hook you can attach a function to operate on a message. The registered function will be called after the message has been processed in the pipeline. The custom code will be executed asynchronously after the response message has been sent to a client.
The second argument is the “outgoing payload” containing the server’s response to the request. The third argument contains the “incoming payload” containing the data originally passed to the server for this request.
After hooks cannot change the response payload being sent back to the client and errors do not prevent the response from being sent.
RPC hooks #
Some logic between client and server is best handled as RPC functions which clients can execute. For this purpose Nakama supports the registration of custom RPC hooks.
The ID of your registered RPC can be used within client code to send an RPC message to execute the function on the server and return the result.
From Go runtime code, the result is returned as
(string, error). From Lua runtime code, results are always returned as a Lua string (or optionally
null or omitted (undefined).