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:

Nakama VersionNakama Common Version
3.12.01.23.0
3.11.01.22.0
3.10.01.21.0
3.9.01.20.0
3.8.01.19.0
3.7.01.18.0
3.6.01.17.0
3.5.01.16.0
3.4.01.15.0
3.3.01.14.0
3.2.11.13.1
3.2.01.13.0
3.1.21.12.1
3.1.11.12.1
3.1.01.12.0
3.0.01.11.0

3.12.0

Released: May 22, 2022

New features

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

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

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

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

Improvements

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

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

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

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

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.

Contribute
All Nakama SDKs are open-source and contributions are welcome.

.NET/Unity

These release notes include updates and improvements to the nakama-unity and nakama-dotnet packages.

3.4.1

Released: May 13, 2022

Fixes
  • Updated to correct Nakama .NET 3.4.0 release binary.

3.4.0

Released: May 2, 2022

Improvements
  • The max message size limit with socket messages can now be overridden in the adapter.
  • Relayed multiplayer matches can now be created with a custom name.
Fixes
  • The background read loop now correctly updates isConnecting and isConnected when close is detected.

JavaScript

2.3.0

Released: August 3, 2021

Improvements
  • The rpcHttpKey parameter list optionals and sequencing have changed, the new signature is: rpcHttpKey(httpKey: string, id: string, input?: object);
  • ApiOverrideOperator has been renamed to ApiOperator.
  • Query parameters are now formatted using snake_case rather than camelCase by the client.
Fixes
  • 401 Unauthorized Response from the server due to rpcHttpKey.

Cocos2d-JS

2.1.0

Released: April 7, 2021

Improvements
Fixes
  • Removed usage of unsupported:
    • setter in XmlHttpRequest.withCredentials
    • XmlHttpRequest.responseType

C++

2.5.1

Released: January 16, 2022

Fixes
  • Errors in Party and Matchmaker callbacks.
  • Fixed removeMatchmakerParty API.

Unreal

2.5.0

Released: September 14, 2021

Improvements
Fixes
  • Cursor assignment in storage object listing.

Cocos2d-x

2.5.1

Released: January 17, 2022

Improvements
Fixes
  • Cursor assignment in storage object listing.
  • Corrected enum values of NChannelType for join group chat.

Godot

3.1.0

Released: April 30, 2022

Improvements
  • Exposed the seen_before property on NakamaAPI.ApiValidatedPurchase. Any previously validated purchases are returned with this flag.
  • Relayed multiplayer matches can now be created with a custom name.
  • Added support for count_multiple on NakamaSocket.add_matchmaker_async() and NakamaSocket.add_matchmaker_party_async().
  • Added C# support classes to better integrate the .NET client with the Mono version of Godot, allowing HTML5 exports to work.
Fixes
  • Receiving of NakamaRTAPI.PartyClose messages.
  • Sending and receiving of PartyData.

Java/Android

2.1.4

Released: April 20, 2021

Fixes
  • protobuf-lite now properly exported to Maven and Gradle projects.

Defold

3.0.0

Released: April 11, 2022

Improvements
  • Breaking changes introduced in this version due to changes in code generation and interaction with Nakama APIs.
    • Socket creation and socket events, including sending events and adding socket event listeners, have been moved to nakama/socket.lua.
    • Message creation functions have been removed in favor or including all message arguments in the functions sending the messages.
  • Added message functions to the client and socket instances. Compare: nakama.do_foo(client, ...) and client.do_foo(...).
    • The old approach of passing the client or socket instance as the first argument still exists for backwards compatibility.