Cloud Code Best Practices
Before you start to build out the Cloud Code for your game, we strongly recommend that you read these guidelines. They are designed to help you avoid creating Cloud Code structures that might compromise your game's performance. Suggestions are also given on ways in which you can check and review your Cloud Code's performance and efficiency.
Using Modules
- Use modules for custom made utilities and libraries with functions and variables that will be commonly used across your code.
- Use requireOnce(“shortCode”) to avoid reloading the same functions and variables multiple times.
Code Iteration and Loops
- Implement timeouts and/or a break after a set number of loops. Loops can be very expensive if executed incorrectly or can get stuck in an endless loop.
Data Access
- Mongo System Collections - These Collections are subject to change by the development team during continuous
development performed on our services. Reading these System Collections is not advised in
case a change affects your game’s logic. We advise using the Game Data Service to create mirror Data Types that
have indexed fields you can use to query in Cloud Code.
- For example, create a Data Type that saves player ID, username, and address that you can query to look up a player’s ID and use it in Spark.loadPlayer(playerID).
- Please see the Mirroring the Player Collection tutorial.
- Data Persistence - For further details on how to manage data persistence, refer to this page.
API Requests
If you embed API requests into your Cloud Code scripts, those API requests will count towards the limit imposed on your game for API request rate, which will depend on your game's Pricing Tier - please see our Usage Limits and Fair Usage Policy webpage for details.
For an explanation of what counts towards the limit imposed on the API Requests rate for your game and how to tell if you have reached your limits, please see our Self-Service Pricing FAQs page.
Bulk Jobs and Schedulers
- Schedulers can call other schedulers up to 10 levels deep, after which they fail to set. If you want to schedule a regular event or logic, consider using the Every Minute, Every Hour and Every Day system scripts.
- Note also that each game is limited to 20 scheduled bulk jobs. See System Limits for details.
Custom Logic
- The GameSparks API is capable of reading and returning nearly every field in your game - in any System Collection. Use the Spark object and the Spark requests to retrieve values such as Players, Challenges, Matches and Leaderboards, instead of writing your own custom logic. In other words, try to avoid writing your own custom logic for something that the platform already does very efficiently:
- For example, instead of reading the Team System Collection for a particular team, use Spark.getTeams().getTeam().
- Review the API Documentation pages to gain a good understanding of the API.
Querying
Here are some best practices for embedding database queries in your Cloud Code.
Indexed Fields for Data Types
When using the Game Data Service, you must define indexed fields first and these Game Data Indexes are the fields you can use to query and retrieve data from the custom Data Types you've created for your game. For more details, see the Game Data page.
Indexing Fields for Mongo Runtime Collections
When creating your own custom Mongo Runtime Collections, ensure that often-queried fields are indexed. This can be done via Cloud Code. Indexing will speed up Querying speeds. For more details see the Creating Game Collection Indexes page.
Spark Cache, Redis, and Mongo Collections
How do I determine where the data should be saved?
Here’s a few things to keep in mind for answering this question.
First ask: what type of data do you want to save: game meta data, Player data, or Team, Match, or Leaderboard specific data?
- Game meta data: Does this data ever change outside of a new snapshot being published?
- No: Metadata collection.
- Yes: Do you need to operate on the data - for example, increment numeric values and so on?
- Yes: Redis.
- No: SparkCache.
- Player data: Is it a very small amount of data, frequently accessed by the player it belongs to?
- Yes: Store in Player privateData.
- No: Use the Game Data Service to store in separate custom Data Type.
- Team, Match, Leaderboard and similar data: Use first class features for these - that is, these data are automatically stored in System Collections. Additional data can be stored in custom Data Types.
Legacy Games with Mongo? If you are working with a game that was created before the launch of the Game Data Service in January 2018, you can you still use Mongo Runtime collections to store custom data, such as extra player or team data. Note that Runtime collections for Mongo are now deprecated and are not available for new games - those created after January 2018.
More on Data Persistence? For more details on how to manage data persistence on the platform, see the Managing Date Persistence page.
Querying Large Entry Numbers
Using Game Data Service
- Results returned for a query on a Data Type are limited to a maximum of 100.
Using Mongo Runtime Collections
- Split large Runtime Collection documents into smaller entries in different Collections and refer to them using a unique ID.
- Do not run queries on a large amount of entries if the field is not indexed.
- If your Runtime Collection has thousands of entries, we recommend that you limit the number of entries returned when querying the Collection.
Using Performance Metrics
There are several useful tools built right into the GameSparks platform that you can exploit for checking on how well your Cloud Code is performing:
- Analytics Overview - This page provides a basic overview of how well your code is performing. Keeping an eye on the metrics presented on the Analytics Overview>Performance tab will help you to identify calls into the platform that have a larger performance impact. See Analytics Overview for more details.
- API Stream Analytics - You can take a closer look at how individual requests and messages are performing by using the API Stream Analytics feature. See API Stream Analytics for more details.
- Cloud Code Profiler - You can use the Cloud Code Profiler tool in the Test Harness to return and inspect detailed performance metrics on your Cloud Code. Precise metrics, such as the number of statements and processing time will help you gauge the performance of your code and give you an idea on how to optimize it. See Cloud Code Profiler for more details.
Next
Please review the Cloud Code API Functions Guide guide, which will help you find the Cloud Code functions suited to your game development requirements.