Metaplay Docs

Appearance

Updating the Metaplay SDK

Learn how to update the Metaplay SDK in your project.

Dependencies ​

  • A project with the Metaplay SDK integrated - If you don't have a project yet, you can follow our Integrate the Metaplay SDK guide. You should also have a working knowledge of your project's codebase and any potential customizations you may have made to the Metaplay SDK in your project.
  • Automated tests - While not strictly required, being able to run our automated integration tests will greatly help you when verifying that the update was successful. If you don't have automated tests set up yet, you can follow our Introduction to Automated Testing guide.

Overview ​

Updating the SDK might look intimidating, but it's usually a straightforward process.

You can see which versions are available in the Release Notes. If you're not sure which version you're currently running, just run metaplay update sdk in the project directory and it will tell you.

Before applying the update, you should review the release notes for the new version of the SDK for any breaking changes and migration steps. This will give you an idea of what to expect in case you have customized our core SDK code.

One Major Version at a Time

You should not skip major versions, as each major SDK update will have migration steps that need to be followed. Minor versions can be skipped. If you're more than one major version behind, you need to apply them one at a time using the process below.

Performing the Update ​

1. Establish a Clean Working State ​

Before applying the update, you should have a clean working state. This means that you should have no uncommitted or other work-in-progress changes that could get mixed up with the file changes from the update.

Always create a new branch in your version control system to apply the update. This will make it easier in later steps to compare changes, run tests, and potentially revert the update if necessary. Working in a branch also allows other team members to continue working on the project without being affected by the update.

2. Apply the Update ​

  1. Close your IDE and running processes - Before applying the update, make sure that your IDE is closed, the local game server or dashboard is not running, and Unity is closed. This will prevent any potential issues with file locks or other conflicts.

  2. Update the SDK files - Use the Metaplay CLI to update the SDK files to the new version:

    shell
    MyProject$ metaplay update sdk

    The command will guide you through the update process interactively and replace your MetaplaySDK/ directory with the new version.

  3. Follow the migration guide - Follow the migration guide in the release notes for the new version of the SDK. It contains step-by-step instructions that are easy to follow.

3. Test the Update ​

After applying the update, verify that everything works correctly through comprehensive testing:

  1. Test server locally - Verify that the game server builds and runs successfully:

    shell
    MyProject$ metaplay dev server

  2. Test client locally - Connect Unity to your local game server and verify everything runs smoothly.

  3. Test LiveOps Dashboard - If you're using a custom LiveOps Dashboard, verify it works correctly against your local game server.

    shell
    MyProject$ metaplay dev dashboard

  4. Run integration tests - Execute the integration test suite:

    shell
    MyProject$ metaplay test integration

  5. Test in cloud environment - Trigger your CI pipeline to deploy the update to a test environment, then verify that the Unity client connects successfully.

4. Final Review ​

Before merging the update into your main branch, make sure to review the changes and verify that there are no unexpected or accidental changes to files outside of the update. This is also a good time to double-check that you have not missed any customizations you may have made to our core SDK code.

Support ​

If you run into any issues during the SDK update, feel free to join our Discord and ask for help!

If you have a support contract with Metaplay and need any assistance, feel free to contact us through your official support channels.

Further Reading ​