AOPS (Advanced Online Patching System) may seem a bit daunting to look at or configure, but it’s actually very easy. We made the AOPS system to make patching for you as easy as possible, the issue is, all the fields AOPS requires, are actually needed. So when you see all those fields to fill in, without filling them in, won’t make AOPS work for you.
We have a new built-in wizard for AOPS, built right into GLC V2, you can access via File > AOPS Wizard.
AOPS has been developed and tested with hundreds of different types of setups and does work 100%, when there is an issue, 90% of the time it’s a user-error, but no fear, we have written this guide to help and assist you in troubleshooting what it could be.
To enable debug logging, you first need to go into GLCV2 editor, open up your project, go to the AOPS settings and check the box ‘Allow Debugging Prompt’, then rebuild your launcher.
Debugging the Patcher
First thing’s first, AOPS contains a built-in debugger, enabling you to see what the potential issue or problem could be. To do this, simply build your launcher, then run it as normal and check for updates so AOPS launchers. When AOPS launchers you will be presented with a message…
Click Yes and this will produce a debug log. Your users can do this also.
The debug logs are produced in a temporary folder on yours (or your users) computers, it goes under %appdata% and the folder inside %appdata% will be whatever your game launcher is called, so if your Launcher Title is ‘My Game’ then the path to this temporary folder would be %appdata%\My Game\, it would look something like this
N.B – This is NOT your GLC project folder, it’s a folder that is created on yours and your users computers, there should be no GLCPro in the path.
When you run the launcher in debug mode, it runs as normal and produces a debug log file with every step it takes, this is just a normal text file you can view with Notepad (or Notepad++). It’s a file inside the temporary game launcher folder, under a folder called patchtemp called patch.log
Inside this log file will display exactly what the game patcher is trying to do every step, so whichever step is the last step, is usually where the problem lies. In this guide, we will look at most of the common errors and see how you can rectify them.
Stage 1 – Loading Patch Configuration
Stage is the first stage of the AOPS patching process. It initialises all the information from your patch settings file (the settings you put in GLC V2 when designing your launcher). If this is the stage where AOPS stops and doesn’t do anything else, then there are issues with your configuration settings. See the section Common Errors below.
Stage 2 – Creating Temporary directories
This stage is where all the temporary directories are setup and stored for further use into the patching process…
If AOPS stops at this stage, then there was a problem writing out to the users AppData directory. The AppData Directory is usually the most freely available directory to write to, this is why we and other software developers use it. If you or your user have issues writing to this directory, you must have some serious restricted privileges on your computer. Either this, or a 3rd party software is stopping AOPS from writing to this folder.
Stage 3 – Checking Directories and Patch File URL
This stage checks that the temp directories were setup correctly and are accessible and it also checks if a Patch file was specified, if the patch file was specified, it will start to download this file. If it stops at this stage, it’s either for the above reason or your patch file was not specified.
Stage 4 – Downloading Patch File
This stage downloads the actual patch file from your server. When your patch file is downloaded from your server, it will be saved in this temporary folder as files.lst. Again, you can open this up with Notepad to inspect if you wish. If AOPS bombs at this stage, there’s either an issue with the way you’ve typed in your patch file url or it’s not accessible from your webserver. See Common Errors below. You can also put your patch file URL (in the debug log file) into Chrome/Firefox and go to that page and see if it loads up, if it doesn’t, you know there is surely an issue.
If you see our debug log above, if there was an error, we would go to https://byteboxmedia.co.uk/testdir2/patch.gcl and see if it loads within our browser. If it didn’t, we know there would be either a problem with the link we provided or something on our webserver blocking the file from being accessed.
Stage 5 – Patch File Successfully Downloaded
If you have reached this stage of the AOPS process, this means your patch file has successfully downloaded and can be seen in your temporary folder as files.lst.
Stage 6 – Retrieve Local Installation Information
Stage 6 is all about getting the current installation information from the registry. If you selected ‘Retrieve Install Location from Registry’ inside GLC V2 setup, this is where that stage is performed. So it will read the users registry and hunt down this information. If AOPS bombs at this point it’s because the registry information wasn’t found.
As you can see from our settings above, we specified the registry settings AOPS should look for. The current key has no starting trail and no end trails \ – you don’t need these.
If you didn’t choose ‘Retrieve Local Installation Information’ within your AOPS patching configuration then the AOPS system will assume that the files are to be patched at the current location AOPS/Your Launcher is ran from.
Stage 7 – Testing Installation Directory
This is an important stage for AOPS to check whether the directory it will be installing the patch files to, exists… it will use the information you provided through ‘Retrieve installation from Registry’ section or through the current directory of which AOPS is launched from (where the launcher is installed to).
If it bombs at stage 7, the directory doesn’t exist or is protected somehow.
Stage 8 – Patching Stage
This is the most important stage of AOPS. This is a stage which will cycle through all the files in your patch list file and compare them with what’s installed on the users computer, it will then make a decision whether or not to patch. This stage will cycle until all files are completely scanned and checked. Then it will proceed to the final stage.
Let’s take a look at Stage 8 more in-depth here.
This is the order in which AOPS operates Stage 8, for each individual file:
- Check data from Patch File
- Check local file exists
- Check local file size and local file checksum
- If the checksum is the same, go to next file
- If the checksum is different, download file, install file, loop back to part 1
If the checksum was different for a file, this means either the users installed file was different to what is on the server or it didn’t exist at all. So AOPS will download and install the file.
If AOPS has to patch a particular file, after it has downloaded and patched it, it will re-scan over it again, just to make sure that the local file now has the same checksum as the server file.
If AOPS scans a file and the checksum is the same as the server, it will just move onto the next file. This cycle repeats until all files listed in the patch.gcl file are looped.
Stage 9 – Updating Version Number
After AOPS has completed everything, before it finalises, it needs to update a version number somewhere. This tells AOPS when it runs again, which version is currently installed, otherwise it will just keep thinking there is a new update available.
You need to fill out one of the following in the AOPS configuration:
If you are updating the version number via Registry, select Registry and fill out the corresponding fields. If you are updating a local INI or local file (ie: version.txt) which is in the same directory as the launcher, then specify that filename in the relative box (and don’t forget to select the checkbox for which one you’re using).
Common Errors
Most “issues” with AOPS are typically user error. Here we list possible issues and their causes along with possible solutions.
AOPS only recognises whole integers or floating values to one decimal place. You should use either 1,2,3,4 incrementally for update triggers, or use 1.1 or 1.12 or 1.123. Please remember, this is only an internal reference number for you and AOPS. It doesn’t actually affect the versioning of your game or app, or files.
I checked my debug log and it keeps repeating the same file on the scan
This usually means there is an issue between the file on the server and the file on the local machine. This is usually because you have rescanned your files in GLC, then produced a new patch file but not uploaded the new renamed files and overwritten them on the server. You must always ensure you use the same HASH SALT for your original launcher all your future patches.
You must ensure whenever you push out a new patch you follow these steps:
- Rescan files in GLC V2 (AOPS Dialog)
- Rename files in GLC V2
- Upload Files to Server (overwriting any previous) – you only need to upload the modified files for patching
- Upload patch.gcl file to refresh the one on the server
I can’t pinpoint why it just stops on a certain stage
If you have looked at the debug log and can see a particular stage was the last stage it performed, check above and then check any URLS you have put into your configuration.
All files (including patch file url and all the server files) should be accessible via the web so if your patch file URL is:
https://byteboxmedia.co.uk/testgame/testgame.gcl?cb=80902?mode=GLC3140?app=My Test Game R115353
Then copy that url from the debug log file and paste it into your web browser and go to it. If it loads up or starts to download, you know it’s ok. If it doesn’t, then check what the error is in the browser. If it’s a 404 error, this usually means the file doesn’t exist, either that or the link to the file is wrong, in this case, check your Patch URL file (directory where your files are stored).
One typo in any URL will break the whole AOPS operation.
It’s always worth going through your whole AOPS configuration where there are URLs and check these URLs yourself in your web browser.
Cannot retrieve local information from local file (or INI or Registry)
If this happens are you are 100% sure all the settings are correct, please ensure that your starting value is greater than 0. If the local version number is 0, it will bomb the AOPS editor. It should never be zero (0). You can use any number greater, including 0.1 but never have your initial release at a value of just 0.
The same file keeps on looping inside AOPS
We have checked the AOPS system on tens of different setups and everything works as it should. However, we understand some users may experience difficulties in the same file looping over and over again, which is why we wrote this guide. Please follow all the correct steps above and below before consulting this section.
- Comparing with the patch log
When you generate a debug log, you can see AOPS output exactly what is going on with that particular file. The first thing to do is match up the MD5 on your server. To do this, find the suspect filename inside your patch log. Take a look at the file size (in bytes). Take a look at the timestamp. Now locate the actual file on your web server and ensure those details are 100% correct. - Ensure GZIP is Disabled on your webserver
You must ensure GZIP is disabled on the domain you are hosting your files from, or at least disabled using HTACCESS for the directory and sub-directories in which your files are placed on your webserver. Having GZIP enabled, can sometimes force the server to serve a compressed version of your files, which will result in an MD5 mismatch once downloaded. - Make sure you can see the suspect file in your web browser
When you see the same file looping around and around, locate it inside your debug log. Then locate the http string what AOPS is downloading. Now copy this string and paste it into your web browser, don’t forget to put tlg at the end. If you receive an error and your browser doesn’t start downloading the file, then this is why AOPS is having problems. You will need to figure out how to allow these files to be downloaded on your webserver. Alternatively, you could have specified a wrong patch URL path. - If your web browser can’t access it, neither can AOPS…
As above, if your web browser can’t access the file, then neither can AOPS. Ensure all paths/files are readable so AOPS can use this to download the patch files.
Your Hash Key
Your Hash Key (Salt) can be any letter, character or number you wish, however please do not use the hash symbol (#) this will cause breakages inside AOPS. You should also refrain from using the hash symbol (#) inside filenames too.
The Correct Patching Procedure
To ensure AOPS works correctly, we have designed a Wizard that’s built into GLC V2. You can access it via the File > AOPS Wizard in the menu. This wizard will give you helpful advice as to what each setting does. Follow this carefully.
The procedure for a first-time setup is like this:
- Fill out all information
- Scan over your game files
- Rename all of your game files
- Upload all of your game files
- Upload your patch.gcl file
- Build Launcher
For future updates or patches, you will need to:
- Open your launcher project in GLC V2
- Re-scan over your new game files
- Re-Rename all your new game files
- Re-Upload all your game files (only overwriting ones that have been modified)
- Re-Upload your patch.gcl file (overwriting the previous one)
If you are still stuck please see AOPS Troubleshooting Guide – Part 2 here.
AOPS Tutorial Video
Here is a link to a Live Stream we did, which shows you how to setup AOPS and how to create your first patch with GLC V2…
