Difference between revisions of "Upgrading the engine"

From Open Surge Engine Wiki
Jump to: navigation, search
(Flatpak / Snap)
 
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
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.
+
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.
  
 
== Preliminaries ==
 
== Preliminaries ==
  
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.
+
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 [https://youtu.be/GpxynnR1yOw a lesson on YouTube] explaining in detail how to use the tool.
  
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'''.
+
Upgrading your game is a must if you want to play it on mobile devices. Two ingredients are required for the upgrade:
  
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).
+
# 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)
  
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.
+
The procedure for invoking the Open Surge Import Utility varies slightly according to the operating system. Make a backup of your game before proceeding.
  
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 [http://opensurge2d.org in our website].
+
== Import your game ==
  
== Upgrading manually ==
+
=== Windows ===
  
=== Step by step ===
+
Download the latest stable release of the engine at [https://opensurge2d.org opensurge2d.org] or a development build at the [https://forum.opensurge2d.org forums].
  
This is the outline of the upgrade process. The steps below must be followed in order:
+
# Open the folder of the clean build of the engine.
 +
# Go to src\misc\goodies\
 +
# Double click on import_game.cmd
  
# First of all, make a backup of your game. '''THIS IS MANDATORY!'''
+
A wizard will be launched. Follow the instructions on the screen. You'll need to point out where your game is stored.
# 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!
+
'''Note:''' double clicking on import_game.cmd is the same as running ''opensurge.exe --import-wizard'' on a Command Prompt.
  
=== Troubleshooting ===
+
=== GNU/Linux ===
  
==== I lost some of my sprites ====
+
==== Flatpak / Snap ====
  
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.
+
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:
  
==== The engine crashes with an error ====
+
# Run ''flatpak run org.opensurge2d.OpenSurge --version'' on a console to know which version of the game engine is installed on your filesystem
 +
# [https://github.com/alemart/opensurge/releases/ 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"''
 +
# 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"''
 +
# 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"''
  
Inspect the '''logfile.txt'''. This file is your friend, and will help you catch any conflicts that may be causing the crash.
+
The procedure for the Snap version is analogous.
  
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).
+
'''Note:''' you can simplify the process if you use a tool such as [https://flathub.org/apps/details/com.github.tchx84.Flatseal Flatseal] to allow the engine to access your home folder.
  
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.
+
==== Compiled from sources ====
  
If you can't solve the error, ask the community for help. Reach out on Discord or on the forums.
+
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.
  
==== I can't find some of my scripts/objects ====
+
# Open a console
 +
# ''cd ~/path/to/opensurge/''
 +
# ''./opensurge --import-wizard''
  
Make sure you have copied ''all'' the .ss files you have written into ''NEW/scripts/mygame/''. Nothing should be missing.
+
A wizard will be launched. Follow the instructions on the screen. This procedure works just like it does on Windows.
  
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.
+
==== Downloaded from distro repositories ====
  
==== I have modified the source code of the engine ====
+
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:
  
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.
+
# Open a console
 +
# Run ''opensurge --version'' to know your version of the engine
 +
# [https://github.com/alemart/opensurge/releases/ 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"''
 +
 
 +
== Keep your assets separate ==
 +
 
 +
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.
 +
 
 +
== Troubleshooting ==
 +
 
 +
=== I lost some of my sprites ===
 +
 
 +
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.
 +
 
 +
=== I lost some of my texts ===
 +
 
 +
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.
 +
 
 +
=== 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.
  
== Upgrading automatically ==
+
* 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 ''--verbose'' command-line argument to get the logs printed on the standard output.
  
Upgrading a game to a new version of the engine is a process that can be automated. An automated process is less error-prone. A computer program could do this task. Here's a sketch of a spec for a program that automatically upgrades a game:
+
If you can't solve the error, ask the community for help.
  
* The program MUST display some sort of logging mechanism to provide information to the user
+
=== I have modified the source code of the engine ===
* 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 MUST receive as input the directory of the game to be upgraded and the directory of a clean build of the new engine
+
* The program MUST 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
+
** If the version of the new engine is less than or equal to the version of the old engine, the program MUST warn the user that no upgrade is taking place
+
*** Note: downgrading the engine may introduce compatibility issues and is not recommended
+
* The program MUST include a storage of the listing of the directory tree of all files of all official versions of the engine
+
** The program MUST use relative paths to store the listing (e.g., images/surge.png, musics/sunshine.ogg, and so on)
+
* The program MUST include a storage of the checksums of all files of all official versions of the engine
+
** Text-based files based on DOS/Windows format ("\r\n" newlines) SHOULD be converted to Unix format ('\n' newlines) for the purpose of computing the checksum
+
*** Given a text-based file, the program MUST compute the same checksum regardless if the file is in DOS/Windows format or in Unix format.
+
* The program MUST inspect the directory tree of the game to be upgraded 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 MUST 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
+
** When comparing the files, the engine version of the game being upgraded and the engine version of the official release MUST be the same
+
* The program SHOULD write the list of added files to its logs
+
* The program MUST write the list of modified files to its logs
+
** Note: files of the official release that have been modified by the user may require manual inspection. The user can thus read the logs to know which files of the official release he or she has modified.
+
* 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.
+
  
If you are a community member interested in contributing to open-source, this would make a valuable contribution.
+
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.
  
 
[[Category:Users]]
 
[[Category:Users]]
 
[[Category:MODs]]
 
[[Category:MODs]]

Latest revision as of 18:37, 4 February 2023

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.

Preliminaries

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:

  1. Your game
  2. 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.

Import your game

Windows

Download the latest stable release of the engine at opensurge2d.org or a development build at the forums.

  1. Open the folder of the clean build of the engine.
  2. Go to src\misc\goodies\
  3. 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.

GNU/Linux

Flatpak / Snap

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:

  1. Run flatpak run org.opensurge2d.OpenSurge --version on a console to know which version of the game engine is installed on your filesystem
  2. Download the source release of that version (it's typically the latest version)
  3. 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.
  4. Place the folder of your game at ~/Downloads/. The sandboxed engine can read from that folder.
  5. Invoke the Open Surge Import Utility
    1. 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"
  6. After importing the game, move the newer release to ~/Downloads
    1. Run on a terminal: mv "$HOME/.local/share/opensurge/path_to_the_newer_release" "$HOME/Downloads/path_to_the_newer_release"
  7. Launch the engine with the imported project as the game folder.
    1. Run on a terminal: flatpak run org.opensurge2d.OpenSurge --game-folder "$HOME/Downloads/path_to_the_newer_release"

The procedure for the Snap version is analogous.

Note: you can simplify the process if you use a tool such as Flatseal to allow the engine to access your home folder.

Compiled from sources

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.

  1. Open a console
  2. cd ~/path/to/opensurge/
  3. ./opensurge --import-wizard

A wizard will be launched. Follow the instructions on the screen. This procedure works just like it does on Windows.

Downloaded from distro repositories

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:

  1. Open a console
  2. Run opensurge --version to know your version of the engine
  3. Download the source release of that version and extract it somewhere in your home folder
  4. 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

  1. opensurge --game-folder "$HOME/path/to/the/source_release/I_just_downloaded"

Keep your assets separate

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.

Troubleshooting

I lost some of my sprites

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.

I lost some of my texts

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.

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 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 --verbose command-line argument to get the logs printed on the standard output.

If you can't solve the error, ask the community for help.

I have modified the source code of the engine

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.