Function Reference

The code runtime built into the server includes a module with functions to implement various logic and custom behavior. It is easy to define authoritative code and conditions on input received by clients.

Nakama module

This module contains all the core gameplay APIs, all registration functions used at server startup, utilities for various codecs, and cryptographic primitives.

local nk = require("nakama")

Note

All code examples assume the "nakama" module has been imported.

base16

base16_decode (input)

Base 16 decode the input.

Parameters

Param Type Description
input string The string which will be base16 decoded.

Returns

The base 16 decoded input.

Example

local decoded = nk.base16_decode("48656C6C6F20776F726C64")
print(decoded) -- outputs "Hello world"

base16_encode (input)

Base 16 encode the input.

Parameters

Param Type Description
input string The string which will be base16 encoded.

Returns

The base 16 encoded input.

Example

local encoded = nk.base16_encode("Hello world")
print(encoded) -- outputs "48656C6C6F20776F726C64"

base64

base64_decode (input)

Base 64 decode the input.

Parameters

Param Type Description
input string The string which will be base64 decoded.

Returns

The base 64 decoded input.

Example

local decoded = nk.base64_decode("SGVsbG8gd29ybGQ=")
print(decoded) -- outputs "Hello world"

base64_encode (input)

Base 64 encode the input.

Parameters

Param Type Description
input string The string which will be base64 encoded.

Returns

The base 64 encoded input.

Example

local encoded = nk.base64_encode("Hello world")
print(encoded) -- outputs "SGVsbG8gd29ybGQ="

cron

cron_next (expression, timestamp)

Parses a CRON expression and a timestamp in UTC seconds, and returns the next matching timestamp in UTC seconds.

Parameters

Param Type Description
expression string A valid CRON expression in standard format, for example " * * *".
timestamp number A time value expressed as UTC seconds.

Returns

The next UTC seconds timestamp that matches the given CRON expression, and is immediately after the given timestamp.

Example

-- Based on the current time, return the UTC seconds value representing the
-- nearest upcoming Monday at 00:00 UTC (midnight.)
local expr = "0 0 * * 1"
local ts = os.time()
local next = nk.cron_next(expr, ts)

groups

groups_create (new_groups)

Setup one or more groups with various configuration settings. The groups will be created if they don't exist or fail if the group names are taken.

Parameters

Param Type Description
new_groups table The Lua table array of new groups to create.

Example

local metadata = { -- Add whatever custom fields you want.
  my_custom_field = "some value"
}
local group = {
  Name = "Some unique group name",
  Description = "My awesome group.",
  Lang = "en",
  Private = true,
  CreatorId = "4c2ae592-b2a7-445e-98ec-697694478b1c",
  AvatarUrl = "url://somelink",
  Metadata = metadata
}
local new_groups = { group }
nk.groups_create(new_groups)

groups_update (update_groups)

Update one or more groups with various configuration settings. The groups which are updated can change some or all of their fields.

Parameters

Param Type Description
update_groups table A Lua table of groups to be updated.

Example

local metadata = {
  some_field = "some value"
}
local group = {
  GroupId = "f00fa79a-750f-11e7-8626-0fb79f45ff97",
  Description = "An updated description.",
  Metadata = metadata
}
local update_groups = { group }
nk.groups_update(update_groups)

groups_user_list (user_id)

List all groups which a user belongs to and whether they've been accepted into the group or if it's an invite.

Parameters

Param Type Description
user_id string The Id of the user who's groups you want to list.

Returns

A list of groups for the user.

Example

local user_id = "64ef6cb0-7512-11e7-9e52-d7789d80b70b"
local groups = nk.groups_user_list(user_id)
for _, g in ipairs(groups)
do
  local msg = ("Group name %q with id %q"):format(g.Name, g.Id)
  print(msg)
end

group_users_list (group_id)

List all members and admins which belong to a group.

Parameters

Param Type Description
group_id string The Id of the group who's members and admins you want to list.

Returns

The members and admins for the group.

Example

local group_id = "a1aafe16-7540-11e7-9738-13777fcc7cd8"
local members = nk.group_users_list(group_id)
for _, m in ipairs(members)
do
  local msg = ("Member handle %q has status %q"):format(m.Handle, m.Type)
  print(msg)
end

http

http_request (url, method, headers, content)

Send a HTTP request and receive the result as a Lua table.

Parameters

Param Type Description
url string The URL of the web resource to request.
method string The HTTP method verb used with the request.
headers table A table of headers used with the request.
content string The bytes to send with the request.

Returns

code, headers, body - Multiple return values for the HTTP response.

Example

local url = "https://google.com/"
local method = "HEAD"
local headers = {
  ["Content-Type"] = "application/json",
  ["Accept"] = "application/json"
}
local content = nk.json_encode({}) -- encode table as JSON string
local success, code, headers, body = pcall(nk.http_request, url, method, headers, content)
if (not success) then
  nk.logger_error(("Failed %q"):format(code))
elseif (code >= 400) then
  nk.logger_error(("Failed %q %q"):format(code, body))
else
  nk.logger_info(("Success %q %q"):format(code, body))
end

json

json_decode (input)

Decode the JSON input as a Lua table.

Parameters

Param Type Description
input string The JSON encoded input.

Returns

A Lua table with the decoded JSON.

Example

local json = nk.json_decode('{"hello": "world"}')
print(json.hello)

json_encode (input)

Encode the input as JSON.

Parameters

Param Type Description
input string The input to encode as JSON.

Returns

The encoded JSON string.

Example

local input = {["some"] = "json"}
local json = nk.json_encode(input)
print(json) -- outputs '{"some": "json"}'

leaderboard

leaderboard_create (id, sort, reset, metadata, authoritative)

Setup a new dynamic leaderboard with the specified ID and various configuration settings. The leaderboard will be created if it doesn't already exist.

Parameters

Param Type Description
id string The unique identifier for the new leaderboard. This is used by clients to submit scores.
sort string The sort order for records in the leaderboard; possible values are "asc" or "desc".
reset string The cron format used to define the reset schedule for the leaderboard. This controls when a leaderboard is reset and can be used to power daily/weekly/monthly leaderboards.
metadata table The metadata you want associated to the leaderboard. Some good examples are weather conditions for a racing game.
authoritative bool Mark the leaderboard as authoritative which ensures updates can only be made via the Lua runtime. No client can submit a score directly.

Example

local metadata = {
  weather_conditions = "rain"
}
local id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521"
nk.leaderboard_create(id, "desc", "0 0 * * 1", metadata, false)

leaderboard_submit_set (id, value, owner, handle, lang, location, timezone, metadata)

The set operator will submit the value and replace any current value for the owner.

leaderboard_submit_best (id, value, owner, handle, lang, location, timezone, metadata)

The best operator will check the new score is better than the current score and keep whichever value is best based on the sort order of the leaderboard. If no score exists this operator works like "set".

leaderboard_submit_incr (id, value, owner, handle, lang, location, timezone, metadata)

The increment operator will add the score value to the current score. If no score exists the new score will be added to 0.

leaderboard_submit_decr (id, value, owner, handle, lang, location, timezone, metadata)

The decrement operator will subtract the score value from the current score. If no score exists the new score will be subtracted from 0.

Parameters

Param Type Description
id string The unique identifier for the leaderboard to submit to. Mandatory field.
value number The value to update the leaderboard with. Mandatory field.
owner string The owner of this submission. Mandatory field.
handle string The owner handle of this submission. Optional.
lang string The language you want to associate with this submission. Optional.
location string The location you want to associate with this submission. Optional.
timezone string The timezone you want to associate with this submission. Optional.
metadata table The metadata you want associated to this submission. Some good examples are weather conditions for a racing game.

Example

local metadata = {
  weather_conditions = "rain"
}
local id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521"
local owner_id = "4c2ae592-b2a7-445e-98ec-697694478b1c"
local handle = "02ebb2c8"
nk.leaderboard_submit_set(id, 10, owner_id, handle, "", "", "", metadata)

leaderboard_records_list_user (id, owner, limit)

List records on the specified leaderboard, automatically paginating down to where the given user is on this leaderboard. If the user has no record on the given leaderboard will return no records.

Parameters

Param Type Description
id string The unique identifier of the leaderboard to list from. Mandatory field.
owner string The record owner to find in the leaderboard. Mandatory field.
limit number The maximum number of records to return, from 10 to 100. Mandatory field.

Returns

A page of leaderboard records and optionally a cursor that can be used to retrieve the next page, if any.

Example

local id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521"
local owner_id = "4c2ae592-b2a7-445e-98ec-697694478b1c"
local limit = 10
local records, cursor = nk.leaderboard_records_list_user(id, owner_id, limit)

leaderboard_records_list_users (id, owners, limit)

List records on the specified leaderboard, filtering to only the records owned by the given list of users. If one or more of the given users have no record on the given leaderboard they will be omitted from the results.

Parameters

Param Type Description
id string The unique identifier of the leaderboard to list from. Mandatory field.
owners table A set of owner IDs to retrieve records for. Mandatory field.
limit number The maximum number of records to return, from 10 to 100. Mandatory field.
cursor string A previous cursor value if paginating to the next page of results. Optional.

Returns

A page of leaderboard records and optionally a cursor that can be used to retrieve the next page, if any.

Example

local id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521"
local owners = {
  "4c2ae592-b2a7-445e-98ec-697694478b1c",
  "f15526e8-6cf8-49a8-b4c8-0b1e4c32a1d7"
}
local limit = 10
local previous_cursor = nil
local records, cursor = nk.leaderboard_records_list_users(id, owner_ids, limit, previous_cursor)

logger

logger_error (message)

Write an ERROR level message to the server logs.

Parameters

Param Type Description
message string The message to write to server logs with ERROR level severity.

Returns

(string) - The message which was written to the logs.

Example

local message = ("%q - %q"):format("hello", "world")
nk.logger_error(message)

logger_info (message)

Write an INFO level message to the server logs.

Parameters

Param Type Description
message string The message to write to server logs with INFO level severity.

Returns

(string) - The message which was written to the logs.

Example

local message = ("%q - %q"):format("hello", "world")
nk.logger_info(message)

logger_warn (message)

Write an WARN level message to the server logs.

Parameters

Param Type Description
message string The message to write to server logs with WARN level severity.

Returns

(string) - The message which was written to the logs.

Example

local message = ("%q - %q"):format("hello", "world")
nk.logger_warn(message)

notifications

notifications_send_id (new_notifications)

Send one or more in-app notifications to a user. Have a look at the section on in-app notifications.

Parameters

Param Type Description
new_notifications table The Lua table array of notifications to send.

Example

local subject = "You've unlocked level 100!"
local content = nk.json_encode({
  reward_coins = 1000
})
local user_id = "4c2ae592-b2a7-445e-98ec-697694478b1c" -- who to send
local code = 101

local new_notifications = {
  { Subject = subject, Content = content, UserId = user_id, Code = code, Persistent = true}
}
nk.notifications_send_id(new_notifications)

register hooks

register_after (func, msgname)

Register a function with the server which will be executed after every message with the specified message name.

This can be used to apply custom logic to standard features in the server. Similar to the register_before function but it will not block the execution pipeline. The logic will be executed in parallel to any response message sent back to a client. Have a look at the section on runtime code basics.

Parameters

Param Type Description
func function A function reference which will be executed on each msgname message.
msgname string The specific message name to execute the func function after.

Example

local function my_func(context, payload)
  -- run some code
end
nk.register_after(my_func, "tfriendsadd")

register_before (func, msgname)

Register a function with the server which will be executed before every message with the specified message name.

For example register_before(somefunc, "tfriendsadd") will execute the function before the Friend Add message is executed by the server's message pipeline. This can be used to apply custom conditions to standard features in the server. Have a look at the section on runtime code basics.

Parameters

Param Type Description
func function A function reference which will be executed on each msgname message.
msgname string The specific message name to execute the func function before.

Note

The func should pass the payload back as a return argument so the pipeline can continue to execute the standard logic.

Example

local function my_func(context, payload)
  -- run some code
  return payload -- important!
end
nk.register_before(my_func, "tfriendsadd")

register_http (func, path)

Registers a HTTP endpoint within the server.

Warning

This should not be used to implement custom client functions instead have a look at register_rpc.

This can be useful to define web callbacks to handle various Ad networks. It can also be used to enable server to server communication to ease the integration of Nakama server into various server stacks. Have a look at the section on runtime code basics.

Parameters

Param Type Description
func function A function reference which will be executed on each HTTP call.
path string The path that should be registered as a HTTP endpoint.

Note

The func can pass nil or table back as a return argument which will determine the HTTP response code returned.

Example

local function my_func(context, payload)
  -- let's return the "context" as JSON back in the HTTP response body
  return context
end
nk.register_http(my_func, "/my_endpoint")
-- "my_func" will be registered at 'POST /runtime/my_endpoint'

You can send a request to the HTTP endpoint with JSON and responses will be returned in JSON.

curl -X POST http://127.0.0.1:7350/runtime/my_endpoint?key=defaultkey \
     -d '{"some": "data"}' \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json'

register_rpc (func, id)

Registers a function for use with client RPC to the server.

The ID can be any string identifier and is sent by the client. The ID is used to map the client RPC message to the specific function to execute. Have a look at the section on runtime code basics.

Parameters

Param Type Description
func function A function reference which will be executed on each RPC message.
id string The unique identifier used to register the func function for RPC.

Note

The func can pass nil or string back as a return argument which will returned as bytes in the RPC response.

Example

local function my_func(context, payload)
  -- run some code
end
nk.register_rpc(my_func, "my_func_id")

storage

storage_fetch (record_keys)

Fetch one or more records by their bucket/collection/keyname and optional user.

Parameters

Param Type Description
record_keys table A table array of record identifiers to be fetched.

Returns

A table array of the records result set.

Example

local user_id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521" -- some user ID.
local record_keys = {
  {Bucket = "mygame", Collection = "save", Record = "save1", UserId = user_id},
  {Bucket = "mygame", Collection = "save", Record = "save2", UserId = user_id},
  {Bucket = "mygame", Collection = "save", Record = "save3", UserId = user_id}
}
local records = nk.storage_fetch(record_keys)
for _, r in ipairs(records)
do
  local message = ("read: %q, write: %q, value: %q"):format(r.PermissionRead, r.PermissionWrite, r.Value)
  print(message)
end

storage_list (user_id, bucket, collection, limit, cursor)

You can list records in a collection and page through results. The records returned can be filtered to those owned by the user or "" for public records which aren't owned by a user.

Parameters

Param Type Description
user_id string User ID or "" (empty string) for public records.
bucket string Bucket to list data from.
collection string Collection to list data from.
limit number Limit number of records retrieved. Min 10, Max 100.
cursor string Pagination cursor from previous result. If none available set to nil or "" (empty string).

Returns

A table array of the records result set.

Example

local user_id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521" -- some user ID.
local records = nk.storage_list(user_id, "bucket", "collection", 10, "")
for _, r in ipairs(records)
do
  local message = ("read: %q, write: %q, value: %q"):format(r.PermissionRead, r.PermissionWrite, r.Value)
  print(message)
end

storage_remove (record_keys)

Remove one or more records by their bucket/collection/keyname and optional user.

Parameters

Param Type Description
record_keys table A table array of record identifiers to be removed.

Example

local user_id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521" -- some user ID.
local friend_user_id = "8d98ee3f-8c9f-42c5-b6c9-c8f79ad1b820" -- friend ID.
local record_keys = {
  {Bucket = "mygame", Collection = "save", Record = "save1", UserId = user_id},
  {Bucket = "mygame", Collection = "save", Record = "save2", UserId = user_id},
  {Bucket = "mygame", Collection = "public", Record = "progress", UserId = friend_user_id}
}
nk.storage_remove(record_keys)

storage_update (record_keys)

Update one or more records by their bucket/collection/keyname and optional user. Have a look at the section on storage collections.

Parameters

Param Type Description
record_keys table A table array of records to update.

Example

local user_id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521" -- some user ID.
local now = os.time() * 1000 -- current time converted for msec
local update_ops = {
  {Op = "init", Path = "/", Value = { progress = 1 }},
  {Op = "incr", Path = "/progress", Value = 1},
  {Op = "replace", Path = "/updated_at", Value = now}
}
local record_keys = {
  {Bucket = "b", Collection = "c", Record = "r", UserId = user_id, Update = update_ops},
  {Bucket = "b", Collection = "c", Record = "r2", UserId = user_id, Update = update_ops, PermissionRead = 2, PermissionWrite = 1}
  {Bucket = "b", Collection = "c", Record = "r3", UserId = user_id, Update = update_ops, Version="*", PermissionRead = 1, PermissionWrite = 1}
}
nk.storage_update(record_keys)

storage_write (new_records)

Write one or more records by their bucket/collection/keyname and optional user.

Parameters

Param Type Description
new_records table A table array of new records to write.

Example

local user_id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521" -- some user ID.
local new_records = {
  {Bucket = "mygame", Collection = "save", Record = "save1", UserId = user_id, Value = {}},
  {Bucket = "mygame", Collection = "save", Record = "save2", UserId = user_id, Value = {}},
  {Bucket = "mygame", Collection = "save", Record = "save3", UserId = user_id, Value = {}, PermissionRead = 2, PermissionWrite = 1},
  {Bucket = "mygame", Collection = "save", Record = "save3", UserId = user_id, Value = {}, Version="*", PermissionRead = 1, PermissionWrite = 1}
}
nk.storage_write(new_records)

users

users_ban (user_ids)

Ban one or more users from the server.

Parameters

Param Type Description
user_ids table A table array of user IDs to be banned.

Example

local user_ids = {"4c2ae592-b2a7-445e-98ec-697694478b1c"}
local status, result = pcall(nk.users_ban, user_ids)
if (not status) then
  print(result)
end

users_fetch_handle (user_handles)

Fetch a set of users by handle.

Parameters

Param Type Description
user_handles table A table array of user handles to fetch.

Returns

A table array of the user result set.

Example

local user_handles = {"b7865e7e", "c048ba7a"}
local users = nk.users_fetch_handle(user_handles)
for _, u in ipairs(users)
do
  local message = ("id: %q, fullname: %q"):format(u.Id, u.Fullname)
  print(message)
end

users_fetch_id (user_ids)

Fetch one or more users by ID.

Parameters

Param Type Description
user_ids table A table array of user IDs to fetch.

Returns

A table array of the user result set.

Example

local user_ids = {
  "3ea5608a-43c3-11e7-90f9-7b9397165f34",
  "447524be-43c3-11e7-af09-3f7172f05936"
}
local users = nk.users_fetch_id(user_ids)
for _, u in ipairs(users)
do
  local message = ("handle: %q, fullname: %q"):format(u.Handle, u.Fullname)
  print(message)
end

users_update (user_updates)

Update one or more users.

Parameters

Param Type Description
user_updates table The table array of users to update.

Example

local user_id = "4ec4f126-3f9d-11e7-84ef-b7c182b36521" -- some user ID.
local user_updates = {
  { UserId = user_id, Metadata = {} }
}
local status, err = pcall(nk.users_update, user_updates)
if (not status) then
  print(("User update error: %q"):format(err))
end

uuid

uuid_v4 ()

Generate a version 4 UUID in the standard 36-character string representation.

Returns

The generated version 4 UUID identifier.

Example

local uuid = nk.uuid_v4()
print(uuid)

uuid_bytes_to_string (uuid_bytes)

Convert the 16-byte raw representation of a UUID into the equivalent 36-character standard UUID string representation. Will raise an error if the input is not valid and cannot be converted.

Parameters

Param Type Description
uuid_bytes string The UUID bytes to convert.

Returns

A string containing the equivalent 36-character standard representation of the UUID.

Example

local uuid_bytes = "\78\196\241\38\63\157\17\231\132\239\183\193\130\179\101\33" -- some uuid bytes.
local uuid_string = nk.uuid_bytes_to_string(uuid_bytes)
print(uuid_string)

uuid_string_to_bytes (uuid_string)

Convert the 36-character string representation of a UUID into the equivalent 16-byte raw UUID representation. Will raise an error if the input is not valid and cannot be converted.

Parameters

Param Type Description
uuid_string string The UUID string to convert.

Returns

A string containing the equivalent 16-byte representation of the UUID.

Example

local uuid_string = "4ec4f126-3f9d-11e7-84ef-b7c182b36521" -- some uuid string.
local uuid_bytes = nk.uuid_string_to_bytes(uuid_string)
print(uuid_bytes)

sql

Note

These functions allow your Lua scripts to run arbitrary SQL staments beyond the ones built into Nakama itself. It is your responsibility to manage the performance of these queries.

sql_exec (query, parameters)

Execute an arbitrary SQL query and return the number of rows affected. Typically an INSERT, DELETE, or UPDATE statement with no return columns.

Param Type Description
query string A SQL query to execute.
parameters table Arbitrary parameters to pass to placeholders in the query.

Returns

A single number indicating the number of rows affected by the query.

Example

-- This example query deletes all expired leaderboard records.
local query = [[DELETE FROM leaderboard_record
                WHERE expires_at > 0 AND expires_at <= $1]]
local parameters = {os.time() * 1000}
local affected_rows_count = nk.sql_exec(query, parameters)

sql_query (query, parameters)

Execute an arbitrary SQL query that is expected to return row data. Typically a SELECT statement.

Param Type Description
query string A SQL query to execute.
parameters table Arbitrary parameters to pass to placeholders in the query.

Returns

A Lua table containing the result rows in the format:

{
  {column1 = "value1", column2 = "value2", ...}, -- Row 1.
  {column1 = "value1", column2 = "value2", ...}, -- Row 2.
  ...
}

Example

-- Example fetching a list of handles for the 100 most recetly signed up users.
local query = [[SELECT handle, updated_at
                FROM users
                ORDER BY created_at DESC
                LIMIT 100]]
local parameters = {}
local rows = nk.sql_query(query, parameters)

-- Example of processing the rows.
nk.logger_info("Selected " .. #rows .. " rows.")
for i, row in ipairs(rows) do
  nk.logger_info("User handle " .. row.handle .. " created at " .. row.created_at)
end