Heroic Labs Documentation

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.13.11.24.0
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.13.1 #

Released: August 18, 2022

New features #

Improvements #

  • Improved runtime handling of non-persisted purchases and subscriptions.
  • Improved validation of the count multiple matchmaker parameter.
  • Added stricter validation of Developer Console user email inputs.
  • Added next and previous cursor to results of leaderboard and tournament records around owner client operations.
  • Added next and previous cursor to results of leaderboard and tournament records haystack runtime operations.
  • Improve signature of JavaScript runtime HMAC SHA256 hash function.
  • Improve signature of JavaScript runtime Base64 encode functions.
  • Improve handling of JavaScript runtime context cancellation.
  • Runtime group updates can now increase max count above 100.
  • Build with Go 1.19.0 release.

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.5.0 #

Released: September 6, 2022

Improvements #
  • Added the following functions and features for In-app Purchase Validation:
    • Ability to persist Apple, Google, and Huawei purchase receipts in the Nakama database. Used to compute SeenBefore and protect against replay attacks. Set to true by default.
    • A SeenBefore property to IApiValidatedPurchase.
    • ListSubscriptionsAsync which returns a list of the user’s subscriptions.
    • ValidateSubscriptionAppleAsync which returns details about a user’s Apple subscription.
    • ValidateSubscriptionGoogleAsync which returns details about a user’s Google subscription.
    • GetSubscriptionAsync which returns a subscription for the provided product ID.
Changes #
  • ValidatedPurchaseEnvironment has been renamed to ApiStoreEnvironment.
  • ValidatedPurchaseStore has been renamed to ApiStoreProvider.
  • Removed obsolete client methods that accept a CancellationTokenSource. These have been replaced in favor of methods that accept a CancellationToken as added in v3.3.
Fixes #
  • Fixed an issue with SocketClosed event taking a significant length of time or not firing at all when internet connection is lost.
  • An issue would occur when sending messages over the socket from multiple threads.
  • Automatic retry seeding is now random across devices.

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.4.1 #

Released: June 7, 2022

  • Republication of 2.4.0 release with the cjs distribution provided.

2.4.0 #

Released: June 2, 2022

Improvements #
  • Changed the data structure used to pass session variables to authentication methods from Map<string, string> to Record<string, string> for serialization support.
  • StreamData.stream_presence changed to StreamData.sender, and this field is populated correctly now.
  • MatchData.presences changed to a singular MatchData.presence, representing the sender. This field should be populated correctly now.
  • Match and party data payloads are now serialized as protobuf when using the protobuf adapter.
    • Breaking Change:MatchData and PartyData have their data fields typed as a Uint8Array. Users who send a string as their match or party data will need to use a utility such as TextDecoder to deserialize the string. This change is enforced at compile time.
    • sendMatchState and sendPartyData can now receive bytes as input. If bytes are sent using the default text adapter they are base64 encoded to a string.
      • These functions can no longer receive data payloads of type any. Any object previously passed in must be serialized to a string or bytes. This change is enforced at compile time.
  • Improved comments and documentation on objects and methods.
Fixes #
  • Fixed an issue with the base64 dependency in React Native.

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.

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.6.0 #

Released: September 8, 2022

Changes #
  • Rewrite of the C++ repository structure and build system. The user-facing API remains unchanged.

Read more about the changes in the accompanying blog post.

2.5.1 #

Released: January 16, 2022

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

Unreal #

2.6.0 #

This release builds upon the rewrite of the C++ repository structure and build system. Read more about the changes in the accompanying blog post.

Added #
  • Support for Unreal native types. Use the NakamaUnreal module and see the README for details on how to use it.
  • Support for Blueprints. Use the NakamaBlueprints module if you are interested and see the README for details on how to use it.
Changes #
  • Functionality exposed in previous releases has been moved to NakamaCore. The NakamaUnreal and NakamaBlueprints modules depend on NakamaCore.

Released: September 10, 2022

2.5.0-r1 #

Released: January 20, 2022

Fixes #
  • Added missing headers.

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.2.0 #

Released: August 31, 2022

Improvements #
  • Added support for receiving binary data in NakamaRTAPI.MatchState.
  • Added support for sending and receiving binary data in NakamaRTAPI.PartyData.
  • Added NakamaMultiplayerBridge to integrate with Godot’s High-Level Multiplayer API.
Fixes #
  • Fixed NakamaSocket.add_matchmaker_party_async() and its tests.
  • MatchData.op_code type in schema changed to TYPE_INT.
  • Fixed circular reference in Nakama singleton to itself.

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.3 #

Released: May 20, 2022

Fixes #
  • Fixed issue with incorrect match data property being used in socket_send function.

3.0.2 #

Released: May 12, 2022

Improvements #
  • Allows optional parameters to be nil in socket functions.

3.0.1 #

Released: May 12, 2022

Fixes #
  • Fixed runtime error when an unhandled socket message is received.

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.