Upgrading the engine
This article targets users who are creating games with Open Surge. You'll learn how to upgrade your project to a new version of the game engine.
A new version of the engine has been released. There are many exciting new features. You are eager to try it. You realize it's time to port your game to this new version.
If we would summarize the whole upgrade process in one sentence, it would be this: get a clean build of the new version of the engine and gradually work your way up from there, until you get your game running.
The official releases of Open Surge ship many files with it. In a single package, you get: the game engine (the executable file), a lot of media content (images, musics, etc.) and many scripts. In order to facilitate the upgrade process, you should make a clear distinction between what is a file that belong to the official release of Open Surge, and what is a file that belong to your game. An easy way to do it is to store the files that belong to your game in subfolders that are specific to your game (examples: scripts/mygame/, sprites/mygame/, images/mygame/, and so on).
If you work with a clean build of the engine and can clearly say which files belong to your game and which do not, the upgrade process will be straightforward. Keep in mind that, during this process, the logfile.txt will be your best friend. If any conflicts arise, this file will help you catch them.
As a reminder, it's recommended that you use the latest stable release of the engine to develop your game. The latest stable release is available in our website.
Step by step
This is the outline of the upgrade process. The steps below must be followed in order:
- First of all, make a backup of your game. THIS IS MANDATORY!
- Get a clean build of the new version of the engine. Make sure you are able to run it correctly.
- If you get an error at this point, it means you don't have a clean build of the engine. Old files are being mixed up with new files. On Windows, extract the package of the game engine into a new, empty folder. On Linux, get rid of the old files by clearing up user-space content. You may run opensurge --reset in a console to clear up the user-space folders (this will delete files).
- For the purposes of this guide, we'll establish the following conventions:
- We'll call the folder that stores the game assets of the new version of the engine NEW.
- We'll call the folder that stores the game assets of your project, using the old version of the engine, OLD.
- Inside the OLD folder, make a clear distinction between which assets belong to your game and which do not.
- If you have replaced official sprites (examples: Collectibles, Shields, Checkpoints...), your replacements must be moved to a special folder called sprites/overrides/. Read the Sprites page for further information on how to properly replace the official sprites.
- If you have modified one or more translation files (.lng extension), move them to languages/mygame/. Create that subfolder if it doesn't exist (if you don't want to call it mygame, call it something unique).
- Move the scripts that you have created (all .ss files written by you) to scripts/mygame/. It helps if your scripts were already in a folder of their own.
- Make sure that you can still run your game using the old engine. If any errors arise (should not happen), fix them now.
- Now we're going to copy the assets we have just moved into the new engine.
- Copy sprites/overrides/ from OLD to NEW. You should have a newly created folder whose path is NEW/sprites/overrides/. This folder should have your .spr files in it.
- Copy languages/mygame/ from OLD to NEW, if that subfolder exists.
- Copy scripts/mygame/ from OLD to NEW. This folder should store all SurgeScript files written by you.
- Make sure you can run the new engine now. If any errors arise, fix them now. Maybe some sprites will be different already.
- Now we're going to copy the bulk of the media (images, audio, etc.) to the new engine.
- Copy images/ from OLD to NEW. Do NOT replace any files, meaning: if two files in that folder have the same name, you must keep the file of the NEW engine.
- Copy sprites/from OLD to NEW. Do NOT replace any files.
- Copy fonts/from OLD to NEW. Do NOT replace any files.
- Copy characters/ from OLD to NEW. Do NOT replace any files.
- Copy inputs/ from OLD to NEW. Do NOT replace any files.
- Copy levels/ from OLD to NEW. Do NOT replace any files.
- Copy musics/ from OLD to NEW. Do NOT replace any files.
- Copy quests/ from OLD to NEW. Do NOT replace any files.
- Copy samples/ from OLD to NEW. Do NOT replace any files.
- Copy themes/ from OLD to NEW. Do NOT replace any files.
- Make sure you can run the new engine now. If you find any errors, fix them now. We haven't completed the port yet, but we're almost there.
- If you have replaced some musics and/or sound effects in your game, you may want to keep them.
- Optionally, copy your own files inside samples/ from OLD to NEW. Replace the files you want to replace.
- Optionally, copy your own files inside musics/ from OLD to NEW. Replace the files you want to replace.
- If you have modified the default controls of the game, you may want to keep your modification.
- Optionally, copy inputs/default.in from OLD to NEW (or merge the file manually for greater control).
- It may be desirable to keep your save state. Save states are stored in a file called surge.prefs.
- Optionally, copy surge.prefs from OLD to NEW.
- If you have created new files for your game (example: your own user manual), you should keep them.
- Copy your own user manual (and/or whatever else is not a part of the engine) from OLD to NEW.
- Now we're going to move two standard quest files to the new engine:
- Copy quests/intro.qst from OLD to NEW. Replace the file.
- Copy quests/default.qst from OLD to NEW. Replace the file.
- Make sure you can run the new engine now. If you find any errors, fix them now.
Now your game should be running in the new engine!
I lost some of my sprites
If you have correctly followed the steps above, then it most likely means that you have modified the original image files that are shipped with Open Surge. Those modifications have not (and should not) be imported into the new engine. You should create new image files for your modifications. Please read the Sprites page for instructions on how to properly replace the sprites in a upgrade-friendly manner.
The engine crashes with an error
Inspect the logfile.txt. This file is your friend, and will help you catch any conflicts that may be causing the crash.
On Windows, the logs are stored in the same folder as the executable file of the engine. On Linux, they are usually in ~/.cache/opensurge2d (flatpak and snap use different folders - take a look at the README for further information).
Additionally, make sure you don't replace new scripts by old scripts. Using old scripts in a new engine may cause issues that require manual inspection.
If you can't solve the error, ask the community for help. Reach out on Discord or on the forums.
I can't find some of my scripts/objects
Make sure you have copied all the .ss files you have written into NEW/scripts/mygame/. Nothing should be missing.
If you have modified an official script that is shipped with Open Surge, we recommend that you drop your modification. Know that this is not recommended practice, because official scripts may receive updates and fixes from time to time. If you need to create such a modification, make a copy of the official script and modify YOUR COPY instead.
I have modified the source code of the engine
When you modify the source code of the engine (in C language), you lose compatibility with the official releases. You must carefully merge the changes by yourself and then recompile the project. This is an advanced operation, not meant for the average user.
Upgrading a game to a new version of the engine is a process that can be automated. If a program would automatically upgrade a game, here's a sketch of a spec:
- The program SHOULD display some sort of logging mechanism to provide information to the user
- The program SHOULD make a backup of the game before modifying any files whatsover
- If no backup is made, the program MUST warn the user about the necessity of making a backup before upgrading
- The program SHOULD determine the version of the old engine and of the new engine
- The version of the game engine can be determined by reading the output of the opensurge --version command
- The program MUST inspect the game and determine which files have been added or modified by the user
- The list of added files can be determined by comparing the directory tree of the game to the directory tree of the official release of the engine
- The list of modified files can be determined by comparing the checksums of the files of the game to the checksums of the files of the official release of the engine
- Once the program has determined the lists of added and modified files, the program SHOULD proceed according to the step-by-step described in this guide.