Offline games in Construct

8

Features on these Courses

Stats

13,078 visits, 18,706 views

Tools

License

This tutorial is licensed under CC BY 4.0. Please refer to the license text if you wish to reuse, share or remix the content contained within this tutorial.

Published on 3 Oct, 2017. Last updated 21 Nov, 2023

Construct 3 and Construct Animate web exports can work offline. So long as the project has been downloaded once while online, the user can successfully load the project again after going offline. This is especially good for "Add to home screen" apps, since you get an icon on your device to launch the game and you don't need to be online to play - just like a native app! This tutorial describes how the offline support works and how you can enhance it with features like auto-update.

The Service Worker

Construct exports use a browser technology called service workers to allow projects to work offline. This is essentially some JavaScript that can run even without an Internet connection, and can also read locally saved files, so it can continue to read files used by the project even while offline.

After exporting your project, you should notice two files in the exported folder named sw.js and offline.json. Together these enable offline support. sw.js is the Service Worker, which is the JavaScript that allows the project to load offline. offline.json is basically just a list of every file in the project, so they can all be saved for use offline.

Upon loading your project on the web (and assuming your server is using HTTPS), the browser will save your entire project to disk after loading it for the first time. After that, if you load the web page again, it loads from disk. Nothing is downloaded at all! Usually that means the project loads very quickly as well. This means even if you're offline, you can still load and view the project. Your imported project files are cached for offline use, too.

Updating your project

You might wonder: if the project is always loaded from disk, how do you update it?

If you're online and you load the project, the browser loads from disk instantly as before. However, as the project is running, it checks for an update in the background. If you've uploaded a new version, the browser downloads it and saves it to disk. Then, next time you load the project (including refreshing the page), the browser loads the new version. Until then, the user keeps using the old version.

The Browser object has two conditions to detect this happening: On update found and On update ready. On update found triggers as soon as the browser detects a new version in the background. It is not ready to use yet, though - it's just started downloading the update. On update ready triggers when the download has finished and the new version is ready to be loaded. If this triggers on the project's title screen, you might want to prompt the user to reload the page (using the Browser's Reload action) so they're seeing the latest and greatest version. However, you probably don't want to interrupt them if they're already interacting with it.

This allows you to easily make a simple auto-updater for your project. You could show a text object saying "Downloading an update..." to notify the user an update is being downloaded after On update found triggers. When On update ready triggers, you might want to show a message saying an update is ready, and display a button which reloads the page when clicked.

Remember to re-upload offline.json

If you're updating even just one file of your project, you must also re-upload the exported offline.json file - every time! Otherwise the browser will assume nothing has changed and won't bother downloading the update. (The offline.json file must have changed for the browser to check for an update, and Construct adds a timestamp to the top of the file to ensure it always changes.)

The simplest way to remember to do this is to simply always re-upload all files after exporting.

Troubleshooting

If you are not seeing an update happen even after uploading a whole new set of files including offline.json, check the caching configuration of your web server. For example if your server sends offline.json with a caching header that says "you can keep reading this file from the cache for 24 hours", then you won't see an update happen for another 24 hours. If it allows the files to be permanently cached, you may never see an update happen. Clearing your browser cache and inspecting the server's HTTP response headers can help identify this.

Other useful features

The Browser object also has an On offline ready trigger. This runs the first time the project is loaded after it has finished being saved to disk. From that point on the project can work offline. Before then if the user goes offline, it hasn't finished saving yet so will not work offline.

If you want to check the status of the Service Worker's saving or updating of your project, you can check the browser console. This will log status messages as the Service Worker identifies whether it is up-to-date or if an update is available, as it starts downloading a new version, when it's ready to use, and so on.

Checking if online

While the Browser object provides an Is online condition and On went online/offline triggers, it's best not to rely on these other than for notifying the user of possible connectivity problems. Internet connectivity is not always in a simple on/off state, and can in fact be partial or intermittent, such as when on a train using a cell signal, or with unreliable WiFi. Sometimes the system will more or less guess the online/offline state, which means it could think it's online when actually it's offline, or vice-versa. Usually it is better to just go ahead and make network requests and see if they succeed or fail rather than to wait for an online state. For example making an AJAX request and handling On error is a better approach to determining if the user cannot reach the server than checking the offline state, as it checks the real connectivity state rather than the estimated state.

Conclusion

Construct uses Service Workers to allow your web exports to work offline. Be sure to update offline.json whenever you update your project. Drop in the Browser object to your project and use the update checking events. Now you have a project that works offline and auto-updates whenever the user is online. This is very simple to set up, but very useful!

  • 4 Comments

  • Order by
Want to leave a comment? Login or Register an account!
  • Doesn't work

  • Yeah, I can never get this to work either. It updates, refreshes, detects an update, refreshes... etc, etc, etc...

    I ended up having to search for other methods, but I'm yet to find something I'd consider a good alternative.

    • Hi AnD4D - we had this issue when building our game. We found it happens if there was any other instance of the game in an un-updated state running on a different tab. Which happens a lot with building and testing. We added text to users saying 'close all other instances of the game' then hit the button to reload. That solved it for us. Hope that's helpful.

  • this apply the same for C2?

    if this is the case... why the pwabuilder.com site and others does not detect the service worker?

    and is there a simple way to convert a C2 game to TWA in order to run in android?