Tutorial: Version update detection using Delfruit

[patrickgh3]

Hi all. In a recent Delicious Fruit update, Klazen recently added some neat features, and I'd like to show people how to use them to make your game check if a new version is available when it starts up.

This tutorial is kinda long and involved because what we're doing is kinda complicated, and I tried to provide a lot of detail. Once you know how the process works, actually implementing it for your game should be pretty quick.

A. Adding a version attribute to your game's Delfruit page

First, before you upload your game to the wiki, create a Delfruit page for your game. You probably only want to do this when you're about to release. Make sure the name you type matches the name you will type when you upload to the wiki.

Next, claim your game's Delfruit page. Log in and click "report" on your game's page, and mention that you are the creator, and that this is a new game. Then you'll have to wait for the admin team to approve your request. This might take a little while since the admins aren't adminning 24/7.

You can tell your request was approved if when you edit your review for your game, an additional "attribute system" text appears. These instructions tell you how to add an attribute, and the URL to then access it. Go ahead and add a version tag with some number, e.g. [attribute]version=1.0[/attribute], and click the button to update your review. Visit that attribute's URL in your browser, e.g. https://delicious-fruit.com/ratings/game_details.php?id=12243&attribute=version, and make sure "success" is true, and "version" is the number you set.

Delfruit automagically takes care of reading the attributes you've set and then serving them over a REST API. If you have access to your own server, you could do this yourself, like I've done for Jtool update checking. But having this readily-configurable on Delfruit is very convenient.

B. Accessing the version attribute from your game

These instructions assume you're using GM Studio, which has built-in networking stuff. I might later add resources to check out for 8.1. Consider this another nudge to switch to Studio if you're still using 8 for new projects.

First, let's send an HTTP request for our game's version. This snippet should be executed once at the start of your game. We'll save the id the function returns for later.

Code: [Select]

versionRequestId = -1
if os_is_network_connected() {
    versionRequestId = https_get('blahblahblah?id=12345&attribute=version')
}

This is an asynchronous request, which means we don't get the response right away when this line executes. Create an HTTP event (under the Asynchronous group). This is where we receive the response to our request and deal with it accordingly. Put this snippet in there.

Code: [Select]

var result = ds_map_find_value(async_load, "result")
resultMap = json_decode(result)
if resultMap == -1 exit

var Id = ds_map_find_value(async_load, "id")
if Id == versionRequestId {
    var success = ds_map_find_value(resultMap, 'success')
    if is_undefined(success) exit
    if is_string(success) exit
    if not success exit
    var newestVersion = ds_map_find_value(resultMap, 'version')
    if is_undefined(newestVersion) exit
    newestVersion = string(newestVersion)
    if newestVersion == '' exit
   
    var thisVersion = '1.0'
    if newestVersion != thisVersion {
        if show_question('Theres a new version available. Visit the download page?') {
            url_open_full('https://www.google.com','_blank','')
        }
    }
}
ds_map_destroy(resultMap)

Let's analyze that snippet. In the first 3 lines, we store a ds_map of the response into the variable resultMap. From this ds_map we can access the version number and whatever else the response contains. Next, we grab the id of the response. We compare this to the id we saved earlier in the variable versionRequestId to check which response we're dealing with. Right now our game only sends one request ever, so this isn't really necessary, but it's good practice, since you could potentially have multiple requests in the future.

Inside the if-block, first we do a bunch of error-checking just in case. Then we grab the newest version and compare it to the game's version. If they're different, you know there's a newer version available, and we can prompt the player to visit the download page. The '_blank' target argument opens the page in a new tab. You should also consider using something other than GM's built in popups, for example creating a button on the title screen, since the built-in popups can feel kinda janky.

C. Managing versions

When you release a new version of your game, there are two things you need to do to keep update checking working correctly.
1. Update the version number variable inside the game.
2. Update the version attribute on your game's delfruit game to that same number.
Always remember to do both! It can be easy to forget one.

Something to note is that while the delfruit version attribute updates immediately, the download links on your game's wiki and delfruit pages do not. So if a player's game detects a new version, and you send them to your game's wiki or delfruit page, they could arrive before the download link has been updated. One solution is to upload your games to Mediafire, keep all uploaded versions in one folder, and have your game send players to the Mediafire folder instead since it's updated immediately. Another solution is to have another attribute on your delfruit page that is the newest download link, and the game grabs that and that's where the player is sent to. If you do that be sure you don't have a race condition issue.

Another note: The reason you create your game's delfruit page before uploading to the wiki is so that you can add the version attribute and put the URL into your game.

Another note: It's okay to release your game before the admins approve your request and you're able to add the version attribute on your delfruit page. You're not going to release an update within that timespan anyways. And the version checker code doesn't break if you haven't set the version attribute yet.

D. Checklists

First release your game:
1. Create delfruit page
2. Request to be that page's creator (don't have to wait for approval)
3. Copy delfruit version URL into the game's update check code
3a. If using Mediafire folder: create folder, copy folder URL into game code.
4. Test the case when version numbers are different
5. Test the case when version numbers are the same
6. Double-check game version number 1.0 or whatever it's supposed to be
7. Upload game
7a. If using Mediafire folder, put in that folder
8. Submit game to wiki, be sure it's the same title as delfruit page

Release an update:
1. Increment game's internal version number
2. Increment delfruit page version number
3. Upload game
3a. If using Mediafire folder, put in that folder
4. Possibly submit update to wiki*

*If you submitted your Mediafire folder to the wiki, the links for your wiki and delfruit pages don't need to be updated. But you might consider submitting that your game has an update if it's very important, like a lot more content or a balance overhaul.

Conclusion

I hope this tutorial makes it as easy as possible to add an update checker to your game, and that it'll encourage more people to do it. You don't have to give me credit for using this tutorial. After all, the real work was done by Klazen adding and maintaining these features in Delfruit! That said however, it's probably a good idea to mention in your game's readme that it connects to the internet to check for a new version, to let people know it's not doing anything malicious and to allow it.

If you have any questions, go ahead and ask, I'm happy to try and help. And if you have any feedback on the writing, for example if certain parts weren't clear, if something's incorrect, or if something's missing, I'd appreciate it. Enjoy!

[Kyir]

I'm not really in the habit of updating unfinished games yet, but I think this will be particularly useful for the people always expanding a single game! Thanks for your efforts. If this was a larger community I would be concerned about people doing malicious things with external links, but we're probably all safe for now.