[GM: Studio] - Adding achievements - Complete beginners guide

Introduction

In this tutorial I am going to show you how to implement achievements including trophies and highscores, using the GJ API for GM Studio. Like my other tutorial this is aimed at those unfamilar with the Game API and those who are not keen on programming also.

Note: When you use this tutorial, I assume you already have a basic understanding of GML and GameMaker: Studio.

If you want to see how to implement achievements with previous versions of GM see my other tutorial. Below is a link to this.

Game Maker: Adding achievements complete beginners-guide

This tutorial will be using Florian van Strien's Game API library. The topic for this library is here

Preparation

So let's begin, first of all you need to download the GM Studio library from the achievements page, here is a link.

Gamejolt achievement API GM: Studio

Once you have downloaded the library into a convenient location on your computer, you need to import the scripts into your game. But first let's take a look at its contents, as shown below.

• AchievementExample.exe

• Documentation.rtf (I advise you read this)

• Example.gmz

• Scriptstoimportinyourgame.gml (needed)

The with "needed" in the brackets to one of the files, is the file that contain the scripts we need to import.

Note: Make you unzip the folder first before you use this.

To import the scripts right click "Scripts" and click "Add Existing Script" from the drop down menu. Then open "Scriptstoimportinyourgame.gml" from the file dialog box.

Important Note: If you are using the free edition of GM Studio then you are limited to importing 10 scripts.

Now you need to create an object to begin the API and open the session. Give the object a suitable name, so you will recognise it, such as "GJ_controller" and set the object to "persisent".

Then in the "Game start" event of this object add a new script and add the following:

		
			gj_init(ID, private_key)
		
	

In the first argument you enter the Game ID, for your game you can find this out by going to Game Jolt -> Dashboard -> Your Games. Then find your game and click Game API then API Settings. You should see the following screen:

Copy the Game ID and the Private key and pass them to gj_init() as shown below:

		
			gj_init("1234", " 381e2309cf82106f3a1d67cbbfecbdc6");
		
	

Important note: These arguments are string values so make sure you put these as such, below is an example to show this.

Important note: Ensure you only call this function once in your game, calling it again will induce memory leaks and will log the user out of the session.

Logging in the user

Now we attempt to log the user in, we are going to try and auto login the user first. So in the same action enter the following. If this fails we will prompt for user's username and password.

		
			if  (gj_user_autologin()) // Auto login the user
{
    gj_session_open(); // Open the session
    alarm[0]=30*room_speed;
}
		
	

So above we are saying if the user has been logged in automatically we open the session. This part alarm[0]=30*room_speed; will be explained in more detail later, but basically in the alarm event we are going to ping the session. If we didn't ping the session within 120 seconds the session will automatically close, so this is important.

Now extend the conditional if statement further, so it appears as below. So if the user cannot be logged in automatically you must ask the user for their GJ credentials

		
			if (gj_user_autologin()) // Try and auto login the user
{
    gj_session_open();
    alarm[0]=30*room_speed;  // ping every 30 seconds
}
else // if you cannot auto login the user
{
    userDialog[0] = get_string_async("Username:","");
}
		
	

The next thing to do is to add a "Dialog" event, as this will be triggered when you call the get_string_async() function. In this event enter the following code.

		
			var i_d;  
i_d=ds_map_find_value(async_load,"id");  
if(i_d==userDialog[0])  
{  
    if(ds_map_find_value(async_load,"status"))  
    {  
        if(ds_map_find_value(async_load,"result") !="")  
        {  
            user=ds_map_find_value(async_load,"result");  
            userDialog[1]=get_string_async("Token:","");  
            userDialog[0]=-1;  
        }  
    }  
}  
if(i_d==userDialog[1])  
{  
    if(ds_map_find_value(async_load,"status"))  
    {  
        if(ds_map_find_value(async_load,"result") !="")  
        {  
            token=ds_map_find_value(async_load,"result");  
            request[0]=gj_user_login(user,token);  
            userDialog[1]=-1;  
        }  
    }  
}
		
	

When you have done this in the "Async HTTP" event execute the following code.

		
			var result = gj_result_id();

if (result == request[0])
{
    if(gj_result_status())
    {
        gj_session_open();
        alarm[0]=30*room_speed;
     }
}
gj_result_clear()
		
	

Important note: Always call gj_result_clear() at the end of the Async HTTP event to prevent any possible memory leaks.

Note: Remember to initialise your variables before using them! In the create event I would advise you to do this. For request[0] assign -1 to it, so you have request[0] = -1 (You must do this for each slot in arrays).

Now add an alarm and make sure it is the alarm 0 event. This is where we are going to ping the session. In this alarm execute the following:

gj_session_ping(true);

alarm[0]=30*room_speed; // To continue pinging

The user should now be be able to login to the API through your game. This part is essential if you want to go onto the next sections.

Adding trophies

This section will depend on your game, as you determine when a trophy is achieved in your game. I will just go through how to set a trophy as achieved.

At the point of where you want the trophy to be achieved in your game execute the following.

		
			gj_trophy_add(Trophy ID);
		
	

Just change the argument to the ID of the trophy you want achieved in your game and make sure it is a string. To get the trophy ID go to Dashboard -> Your Games -> Game API -> Trophies then copy the trophy ID you want to be achieved. Below is an image showing this:

And here is an example of gj_trophy_add being used.

		
			// Step event 
if (score > 100)
{
    gj_trophy_add("2340");
}
		
	

Note: When passing your Id number to gj_trophy_add you must make sure you pass as a string, NOT a real number.

Adding scores

Like trophies, how you do this will be entirely up to you. But I will show you how to post scores into your game's leaderboards. Below is the function you call in your game to post a user's score.

		
			gj_scores_add(string table_id, string scorestring, real score_sort, string extra_data);
		
	

Let me break this function down. The first argument " stringtable_id is where you add the table you wish to post the score to. To find your table ID go to Dashboard -> Your Games -> Game API -> Scores you should then see the table ID next to the table.

Then in the second argument " stringscorestring " you enter the score string, so just enter the variable thats storing the score. In the third argument " realscore_sort " you enter the value that will manage the order of your scores in the table; the score variable can go here. And for the fourth argument " stringextra_data " you can enter any extra data you wish to store; but this will not show on your game page, you may leave this as blank quotations. However extra data can help identity the integrity of an added score.

Below is an example of how to use this.

		
			if (gj_user_isloggedin())
{
    request[1] = gj_scores_add("1234", string(score)+"points", score,"");
}

//in the Async HTTP event**
if (result == request[1])
{
    if(gj_result_status())
     {
         show_message_async("successfully added score to list");
     }
     else
     {
         show_message_async(gj_result_error()); 
     }
 }
		
	

Get scores

To fetch scores from leaderboards in your game you need to call this function shown below.

		
			gj_scores_get(TableID, score num)
		
	

For the first argument of this function you enter the ID of the table you wish to fetch scores from, make sure this is a string. And for the second argument you enter the number of scores you wish to fetch, this is a real number not a string.

Note: The maximum amount of scores you can fetch is 100

Below is an example to demonstrate it's use:

In the Game Start event

		
			request[2] = gj_scores_get("1234", 10); // Fetch 10 scores from this table
		
	

		
			for(i = 0; i<10; i++)  
{  
    score_name[i] = "Name";
    score_display[i] = 0;   
}
		
	

In the Async HTTP event

		
			if (result == request[2])
{
    if(gj_result_status())  
    {
        var i;
        for(i = 0; i < gj_result_data_count(); i++)  
        {
            score_name[i]= gj_result_data_field_num("display_name",i);
            score_display[i]=gj_result_data_field_num("score",i);
        }
    }
}
		
	

For more information these functions I advise you check through the documentation.

Draw scores

To draw the scores you just need to loop through the arrays score_name score_display you populated in the previous section of this tutorial. For example:

Draw event

		
			// Draw the top 10 scores
var i;

for(i=0; i<10; i++)
{
   draw_text(10, i*15, "Place " string(i+1) + ". Score by: " + score_name[i] + " Score: " +   score_display[i]);
}
		
	

You would have to tweak the above to suit your game, but this is how you would display your fetched game scores.

Conclusion

Hopefully now you should have users to be able to login to GJ through your game and achieve trophies and highscores. If you have any further questions or suggestions then please leave a reply and I will see if I can solve it.