-
-
Notifications
You must be signed in to change notification settings - Fork 33
upgrading the engine
This article targets users who are creating games with Open Surge. You'll learn how to upgrade your project to a newer version of the game engine.
In order to upgrade your game, you must get it in sync with a newer version of the engine. Since version 0.6.1.0, Open Surge is shipped with a tool called Open Surge Import Utility. This tool will import your game into a newer release. There is a lesson on YouTube explaining in detail how to use the tool.
Upgrading your game is a must if you want to play it on mobile devices. Two ingredients are required for the upgrade:
- Your game
- A clean build of a newer version of the engine
- You'll typically use the latest stable version, but you can also use a development build
The procedure for invoking the Open Surge Import Utility varies slightly according to the operating system. Make a backup of your game before proceeding.
Download the latest stable release of the engine or a development build.
- Open the folder of the clean build of the engine.
- Go to src\misc\goodies\
- Double click on import_game.cmd
A wizard will be launched. Follow the instructions on the screen. You'll need to point out where your game is stored.
Note
Double clicking on import_game.cmd is the same as running opensurge.exe --import-wizard on a Command Prompt.
If you're using the Flatpak version, the engine is sandboxed. Since it has very limited access to the filesystem (see the note below), the procedure is longer:
- Run
flatpak run org.opensurge2d.OpenSurge --versionon a console to know which version of the game engine is installed on your filesystem - Download the source release of that version (it's typically the latest version)
- Store the newer release in a subfolder of ~/.local/share/opensurge/ (that's $XDG_DATA_HOME/opensurge/). The sandboxed engine can write to that folder.
- Place the folder of your game at ~/Downloads/. The sandboxed engine can read from that folder.
- Invoke the Open Surge Import Utility.
- Run on a terminal:
OPENSURGE_USER_PATH="$HOME/.local/share/opensurge/path_to_the_newer_release" flatpak run org.opensurge2d.OpenSurge --import "$HOME/Downloads/path_to_your_game"
- Run on a terminal:
- After importing the game, move the newer release to ~/Downloads
- Run on a terminal:
mv "$HOME/.local/share/opensurge/path_to_the_newer_release" "$HOME/Downloads/path_to_the_newer_release"
- Run on a terminal:
- Launch the engine with the imported project as the game folder.
- Run on a terminal:
flatpak run org.opensurge2d.OpenSurge --game-folder "$HOME/Downloads/path_to_the_newer_release"
- Run on a terminal:
The procedure for the Snap version is analogous.
Tip
You can simplify the process if you use a tool such as Flatseal to allow the engine to access your home folder.
If you compiled the game engine from the source code with the GAME_RUNINPLACE flag set, invoking the Open Surge Import Utility is a lot simpler.
- Open a console
cd ~/path/to/opensurge/./opensurge --import-wizard
A wizard will be launched. Follow the instructions on the screen. This procedure works just like it does on Windows.
If you downloaded the engine from the repositories of your distro, or if you compiled the engine yourself without the GAME_RUNINPLACE flag set, follow this procedure:
- Open a console
- Run
opensurge --versionto know your version of the engine - Download the source release of that version and extract it somewhere in your home folder
- Run
OPENSURGE_USER_PATH="$HOME/path/to/the/source_release/I_just_downloaded" opensurge --import-wizard
Follow the instructions of the wizard. After successfully importing your game, launch the engine with the imported project as the game folder
opensurge --game-folder "$HOME/path/to/the/source_release/I_just_downloaded"It's important to keep your assets (images, scripts...) separate from those of the base game. If the assets of the base game are modified directly, the import utility will bring back the original files (in order to get the game in sync) and modifications will be lost. In this case, you'll have to correct the missing modifications after importing your game.
The Open Surge Import Utility gives tips on how to keep assets separate:
- Do not modify the images of the base game. If you want to change them, create new images and replace the sprites using the sprites/overrides/ folder.
- Do not modify the texts of the base game. If you want different texts, store your changes in the languages/extends/ folder.
- Do not modify the SurgeScript objects of the base game. If you want changed functionality, clone the objects, change their name and save them as separate files.
- Do not modify the characters/levels/bricksets of the base game. Clone them before you remix, or create your own.
- If you have modified the input controls, manually merge your changes. Look especially at inputs/default.in.
- If you'd like to know which files you have previously changed, you may run a diff between the folder of your MOD and the folder of a clean build of the version of the engine you were using.
- If you have modified the source code of the engine (C language), your changes no longer apply. You may redo them.
- You can modify the audio files directly. The Open Surge Import Utility will import them.
Have you modified the original image files that are shipped with Open Surge? Create new image files for your modifications and use the sprites/overrides/ folder. Read the Sprites page for instructions on how to properly replace the sprites in a upgrade-friendly manner.
Have you modified the original translation files (example: languages/english.lng) that are shipped with Open Surge? Use the languages/extends/ folder to add new texts or modify the existing ones. Read the Translation Guide page for instructions on how to properly replace the texts in a upgrade-friendly manner.
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 that holds the executable file of the engine.
- On Linux, they are usually stored in ~/.local/share/opensurge (i.e., in $XDG_DATA_HOME/opensurge).
- The Flatpak and the Snap versions use different folders - take a look at the README for further information.
- You can also run the engine with the
--verbosecommand-line argument to get the logs printed on the standard output.
If you can't solve the error, ask the community for help.
If you modify the source code of the engine (C language), you lose compatibility with the official releases. You must merge the changes yourself and recompile the project. This is an advanced operation, not meant for the average user.