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 Version | Nakama Common Version |
---|---|
3.12.0 | 1.23.0 |
3.11.0 | 1.22.0 |
3.10.0 | 1.21.0 |
3.9.0 | 1.20.0 |
3.8.0 | 1.19.0 |
3.7.0 | 1.18.0 |
3.6.0 | 1.17.0 |
3.5.0 | 1.16.0 |
3.4.0 | 1.15.0 |
3.3.0 | 1.14.0 |
3.2.1 | 1.13.1 |
3.2.0 | 1.13.0 |
3.1.2 | 1.12.1 |
3.1.1 | 1.12.1 |
3.1.0 | 1.12.0 |
3.0.0 | 1.11.0 |
3.12.0 #
Released: May 22, 2022
New features #
- Added the following functions to all runtimes:
- Added the following functions to Lua and TypeScript runtimes:
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:
- 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 accessHTTP
request headers in all runtimes. - Added the following functions to the JavaScript runtime:
- 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 ofwarn
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:
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
inwalletsUpdate
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 JavaScriptValidatedPurchases
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 ofopen
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:
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 runtimesgroupUpdate
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 runtimegroupUpdate
function. - Incorrect validation of
max count
ingroupUpdate
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 thaninfo
. - Added new
langTag
,members
andopen
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
andapi_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 VMGetMatch
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:
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.
.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
andisConnected
whenclose
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 toApiOperator
.- Query parameters are now formatted using
snake_case
rather thancamelCase
by the client.
Fixes #
401 Unauthorized Response
from the server due torpcHttpKey
.
Cocos2d-JS #
2.1.0 #
Released: April 7, 2021
Improvements #
- Updated to the nakama-js v2.1.5 client.
- Added examples for Cocos Creator.
Fixes #
- Removed usage of unsupported:
- setter in
XmlHttpRequest.withCredentials
XmlHttpRequest.responseType
- setter in
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 #
- Added real-time parties support.
Fixes #
- Cursor assignment in storage object listing.
Cocos2d-x #
2.5.1 #
Released: January 17, 2022
Improvements #
- Added real-time parties support.
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 onNakamaAPI.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
onNakamaSocket.add_matchmaker_async()
andNakamaSocket.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.
- Socket creation and socket events, including sending events and adding socket event listeners, have been moved to
- Added message functions to the client and socket instances. Compare:
nakama.do_foo(client, ...)
andclient.do_foo(...)
.- The old approach of passing the client or socket instance as the first argument still exists for backwards compatibility.