Release Notes #

See the updates and improvements in the latest releases of Nakama and supported client libraries.

Nakama #

This section covers new releases and their features for the nakama and nakama-common packages jointly.

Compatibility matrix #

Developers using the Go Server Runtime must ensure the correct nakama-common version is used for their Nakama version:

3.12.0 #

Released: May 22, 2022

New features #

• Added the following functions to all runtimes:
  • FriendsBlock
  • ChannelMessagesList
• Added the following functions to Lua and TypeScript runtimes:
  • metricsCounterAdd
  • metricsGaugeSet
  • metricsTimerRecord

Improvements #

• Storage write ops now return acks in the same order as inputs.
• Updated console path for Delete All data operation.
• The HTTP Key is now checked before Authorization headers in RPC function invocations.
• Exposed error message for Apple authentication JWT verification failures.
• Improved user online status lookups.
• Updated naming of delete notifications before/after hook registration functions.
• Improved clarity of Nakama Console status view graph headers.
• Improved log messages from failed social provider requests.
• Improve concurrency with Lua runtime function registrations.
• Authoritative match loggers correctly include only their own match identifier.
• Improved handling of large tournament max size values.
• Improve handling of channel removal on group leave/kick/ban.
• UI improvements to the group membership view in the Nakama Console.
• Improve JavaScript runtime authoritative match filtered broadcasts to large sets of users.
• Build with Go 1.18.2 release.

Fixes #

• StreamUserList in JavaScript runtime now returns the correct data.
• Lists of presences can now be passed as match init parameters to Go runtime matches.
• Fixed Nakama Console object counts when database statistics are not available.
• Must generate username field in the token generator if not specified when called by the server runtimes.
• Align optional parameters in JavaScript runtime bindings.
• JavaScript registered match handlers were not available within the InitModule function.
• Use unique notification ID handling for persistent notifications sent to all users.
• Concurrent leaderboard creation requests are now handled idempotently.
• Fixed a regression with matchmaker optimization when only two opponents are matched.

3.11.0 #

Released: March 21, 2022

New features #

• Added the following functions to all runtimes:
  • GroupUsersBan
  • LeaderboardRecordsHaystack
  • NotificationSendAll
• Added a senderID parameter to the ChannelIdBuild function.
• Added the Groups page to Nakama Console.
• Added the countMultiple option to the Matchmaker.

Improvements #

• A warning is now logged when a client IP address cannot be resolved.
• Tagged Prometheus stats contains RPC function identifiers have been added.
• Improved the Stackdriver log timestamp and and message field formats.
• Crypto random is now used to seed global random instances when possible.
• The migrate command now allows the use of database names containing dashes.
• Leaderboard rank cache population at startup has been improved.
• JavaScript global variables are now made immutable by default after the InitModule function is invoked.
• For all runtimes, StorageWrite acks now return system user UUID string.
• Real-time after hooks now include the outgoing and incoming payloads.
• Real-time after hooks no longer run when the operation fails.
• Build with Go 1.18.0 release.

Fixes #

• The registered function name for nk.channelIdBuild in the JavaScript runtime.
• Input validation for Steam link operations.
• Incorrect link device behavior in JavaScript runtime.
• JavaScript runtime multi-update execution consistency when part of the operation fails.
• Handling of wallet ledger lookups with no limit during account exports.
• Maximum count is correctly accounted for in matchmaker mutual match checks.
• Matchmaker correctly prefers matches closer to the maximum count.

3.10.0 #

Released: December 17, 2021

New features #

• Added ctx field to access HTTP request headers in all runtimes.
• Added the following functions to the JavaScript runtime:
  • stringToBinary
  • binaryToString
• Added a new configuration option for frequency of database DNS change scans.

Improvements #

• Set JavaScript runtime custom error message as the returned payload message in RPC requests.
• JavaScript runtime match data changed to use Uint8Array type.
• Update Tally and transitive dependencies to resolve dynamic linker error in xxhash package.
• Build with Go 1.17.5 release.

Fixes #

• Gracefully close Lua matches when call queue fills up.
• Better error handling for Lua runtime wallet update operations.
• Better handling of leaderboard record writes that do not need to update the database.
• Fixed parsing edge case in TypeScript/JavaScript runtime storage delete operations.
• Better handling of leaderboard and tournament score submissions that result in no score change.
• Named match creation now returns existing presences if the name mapped to an existing match.

3.9.0 #

Released: October 30, 2021

New features #

• Relayed multiplayer matches can now be created with a custom name. Names are mapped to match identifiers.
• Nakama errors are now exposed to the server runtime.
• The Nakama Console wallet view now supports pagination.

Improvements #

• Periodic checks of underlying address changes to database hostname now occur more frequently.
• Upgraded GRPC, GRPC-Gateway, Protobuf, PGX, and other dependencies.

Fixes #

• Fixed optimistic email imports when linking social profiles.

3.8.0 #

Released: October 15, 2021

New features #

• Added a final notification sent to sockets closed via the single socket configuration option.
• Added matchSignal function to the server framework, now required by match handlers. Match signals allow the match handler to be sent a reservation signal to mark a user ID or session ID into the match state ahead of their join attempt and eventual join flow.
• Nakama Console dashboard now displays node status icons.

Improvements #

• Log status follow missing users at debug instead of warn level.
• Build with Go 1.17.2 release.

Fixes #

• Fixed input validation edge case in group listing operations.

3.7.0 #

Released: September 28, 2021

New features #

• Added the following configuration options:
  • single_socket
  • single_match

Improvements #

• Allow tournament creation operations to set the authoritative flag.
• Build with Go 1.17.1 release.

3.6.0 #

Released: September 9, 2021

New features #

• Added more detailed logging when creating, updating, or deleting groups.
• Added ChannelMessageUpdate function to server framework.
• Added lua_api_stacktrace configuration option to toggle Lua runtime error stacktraces returned to clients.

Improvements #

• Facebook Graph API v11.0 is now used.
• Facebook email import execution is now deferred until after account creation.
• Improved encode/decode checks in authoritative match creation parameters.
• A warning is now generated when using deprecated configuration parameters.
• Improve email import semantics when linking social accounts.
• Log IAP provider API response payload when non-200 status code is returned.
• Purchase validation functions now return a flag indicating if valid purchases are new or resubmitted.
• Better handling of storage operations where OCC is not required.
• Ledger updates now default to false in walletsUpdate function in all server runtimes.
• Adjust Lua runtime pool allocation startup logs.
• Build with Go 1.17.0 release.

Fixes #

• Fixed log level in Lua runtime log calls which use structured logger fields.
• Registered purchase validation before/after hooks in JavaScript and Lua runtimes.
• Registered DemoteGroupUsers before/after hooks in the JavaScript runtime.
• Added missing environment to JavaScript ValidatedPurchases type.
• Fixed typos in error messages which mention empty input values.
• Fixed resolution of exported time and latency metrics.
• Optimized tournament lookup operations.
• Fixed groupUpdate function incorrect parsing of open argument in the Lua runtime.
• List JavaScript modules if loaded from the default entrypoint in the Console.

3.5.0 #

Released: August 11, 2021

New features #

• Handle thrown JavaScript runtime custom exceptions containing a message and a grpc code to be returned in the server response.
• Added the following functions to server framework:
  • BuildChannelId
  • ChannelMessageSend
  • UsersGetRandom

Improvements #

• Apple Sign-In is now supported across both web and mobile tokens.
• Status messages can now be up to 2048 characters (increased from 128 characters).
• Improved SQL used in unfiltered group listings queries.
• Throw error instead of panic when attempting to create a group with the system user.
• Added userId field for permission check in JavaScript and Lua runtimes groupUpdate functions.
• Allow standard space characters in usernames for direct compatibility with Steam display names.
• Allow batch-only leaderboard and tournament score lookups from the server framework.
• Return a better error message when single input wallet updates are performed for a user which does not exist.
• Update to newer Apple guidelines on Game Center root certificate validation in authentication.
• Build with Go 1.16.7 release.

Fixes #

• Creator id was read from the wrong argument in JavaScript runtime groupUpdate function.
• Incorrect validation of max count in groupUpdate JavaScript runtime function.
• Fixed error handling when attempting to write records to a tournament that does not exist.
• Missing fields from leaderboards/tournaments get, list, and write functions in JavaScript runtime.
• Bad parsing of ownerId field in leaderboard/tournament records list functions in JavaScript runtime.
• Fixed parameter usage in leaderboard score set operator.
• JavaScript runtime storageList functions did not return a cursor.

3.4.0 #

Released: July 9, 2021

New features #

• Added the following functions to server framework:
  • GroupsList
  • LeaderboardList
  • LeaderboardsGetId
  • Custom Metrics for counters, gauges, and timers.
• Added the prev_reset field to leaderboard/tournament functions.
• Added an optional passwordOverride to Apple IAP validation function.
• Added socket lang parameter to Go runtime contexts.

Improvements #

• Party matchmaker add operation responses now include a ticket.
• Replace Bleve gtreap in-memory store implementation with a more compact version.
• Users kicked from parties now receive a party close event.
• Log recovered panics in HTTP handler functions at error level rather than info.
• Added new langTag, members and open filters to the group listing API.
• Upgraded pgx to v4 for improved SQL performance.
• Updated RegisterLeaderboardReset runtime function signature.
• Cancel runtime context when graceful shutdown completes.
• Added button to Nakama Console UI to allow device IDs to be copied.
• Build with Go 1.16.5 release.

Fixes #

• Ensure all members are correctly listed in party info when there are multiple concurrent successful joins.
• Correctly set party ID in matchmaker matched callback input.
• Send Party close messages only where appropriate.
• Fix TypeScript/JavaScript match dispatcher presence list validation.
• Fix JavaScript/Lua friendsList incorrect returned values.

3.3.0 #

Released: May 17, 2021

New features #

• Tournaments and leaderboards now allow operator scoring to be passed in on updates.
• Tournaments and leaderboards now support decrement score operator.
• Added rpc_id and api_id to the structured logger output in API calls.

Improvements #

• Store email, avatar URL, and display name provided by Apple, Facebook, and Google login providers if empty.
• Change runtime group add/kick/promote/demote APIs to include optional callerID parameter for permission checking. If the caller ID is an empty string it defaults to the system user.
• Default to use SSL mode prefer in database connections.

Fixes #

• Reading of Lua and JavaScript authoritative match states that contain functions.
• UNIX path representation for embedded migrations and console files on Windows systems are now used.
• Updated Lua VM implementation to resolve nil reference caused after a VM registry resize.
• Pointerize slice and map types when passed into the JS VM so they’re mutated by reference.
• Fixed off by one error in leaderboard records returned by “around owner” queries.
• Return null from within JS VM GetMatch function if match does not exist.

3.2.1 #

Released: April 19, 2021

Improvements #

• User online indicators now observe status mode not just socket connectivity.
• Updated sql-migrate library to a32ed26.
• Reworked migrations for better compatibility with different database engines.
• Updated to Protobuf v1.5.2, GRPC v1.37.0, and GRPC-Gateway v2.3.0 releases.
• Updated to Bleve v2.0.3 release.
• Various other dependency updates.

Fixes #

• Fixed user scoping in Nakama Console purchase listing view.

3.2.0 #

Released: April 14, 2021

New features #

• New API to logout and intercept logouts with session and refresh tokens.
• Added a leave reason to presence events to handle transient disconnects more easily.
• New API for IAP validation with Apple App Store, Google Play Store, and Huawei AppGallery.

Improvements #

• Improved struct field alignment on types in the social package.
• Improved memory re-use within the matchmaker and match registry structures.
• Support for Facebook Limited Login tokens received into the standard Facebook login/link/unlink functions.
• Updated JS VM to newer version. This resolves an issue with resizing some JS arrays.
• Build with Go 1.16.3 release.

Fixes #

• Matchmaker entries which were only partially matched together could not combine with larger player counts.
• Fixed bad inputs parsed in some before/after hook executions made from the API Explorer in the Console.
• Incorrect Unix timestamps in JS runtime functions returning users/accounts data were returned.

3.1.2 #

Released: March 4, 2021

Improvements #

• Sort match listings to show newer created matches first by default.
• Loosen status follow input validation and constraints to ignore unrecognized user IDs and usernames.
• Do not import Steam friends by default on Steam authentication.
• Do not import Facebook friends by default on Facebook authentication.
• Improved match label update batching semantics.
• Account object returned by some JS runtime functions are not flattened with user values anymore.
• Build with Go 1.16.0 release.

Fixes #

• The matchmaker matched callback did not function correctly in the JavaScript runtime.
• Allow the console API to return large responses based on the configured max message size.
• Allow JS runtime initializer functions to be invoked inside a try/catch block.
• Fix Tournament Reset function hook schedules calculated on first write if the end active time must be computed with no reset schedule.

3.1.1 #

Released: February 15, 2021

Improvements #

• Go runtime logger now identifies the file/line in the runtime as the caller rather than the logger.
• Newer CA certificates package within the Docker containers are now used.
• Build with Go 1.15.8 release.

Fixes #

• Runtime hooks were not invoked correctly in the JavaScript runtime.
• Leaderboard listing Delete button did not function in the Nakama Console.
• GetUsers can fetch user accounts by Facebook ID the same as in the client API.

3.1.0 #

Released: February 4, 2021

New features #

• New API to import Steam friends when authenticating with Steam.

Improvements #

• Improve output of nakama migrate status command when database contains unknown migrations.
• The socket status flag is now parsed as case-insensitive.
• Build with Go 1.15.7 release.

Fixes #

• The multiUpdate function did not work correctly in the JavaScript runtime.
• The InitModule would be called twice in the JavaScript runtime.
• Fixed how the JS runtime invokes matchmakerMatched and leaderboard/tournament related hooks.
• JS VMs were not being put back into the pool after an RPC call.

3.0.0 #

Released: January 16, 2021

New features #

• Added JavaScript runtime for writing server code.
• Added refresh tokens that can be used to refresh sessions.
• New Realtime Parties for users to create teamplay in games.
• Added party matchmaking support to the matchmaker.
• Added configuration options to the Matchmaker to control how long tickets wait for their preferred match.
• Added Console UI permissions API.
• Added the following runtime functions:
  • ReadFile

Improvements #

• Rebuild Console UI with Angular framework. Manage user data, update objects, restrict access to production with permission profiles, and gain greater visibility into realtime features like active matches.
• Matchmaker improvements to the process for matching and the handling of player count ranges.
• Authoritative match handlers can now tick at 60 per second.
• Support CockroachDB 20.2 release.
• Build with Go 1.15.6 release.

Fixes #

• Return rank field in Lua API for leaderboard record writes.
• Return social fields for users in friend listings.

Client SDKs #

This section covers new releases and their features for the Nakama SDKs. Select your language using the drop-down above to view the relevant releases.

Remember that Nakama version numbering is not aligned with the SDK version numbering.