Difference between revisions of "Upgrading the engine"

From Open Surge Engine Wiki
Jump to: navigation, search
(A simpler way)
(Flatpak / Snap)
 
(3 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 which files belong to the official release of Open Surge and which files 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 it (examples: ''scripts/mygame/'', ''sprites/mygame/'', ''images/mygame/'', and so on). Keep what is Surge's, Surge's, and keep what is yours, yours.
+
# 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 ones 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. For the purposes of this guide, we'll establish the following conventions:
+
# Open the folder of the clean build of the engine.
 +
# Go to src\misc\goodies\
 +
# Double click on import_game.cmd
  
* We'll call the folder that stores the game assets of the new version of the engine ''NEW''.
+
A wizard will be launched. Follow the instructions on the screen. You'll need to point out where your game is stored.
* We'll call the folder that stores the game assets of your project, using the old version of the engine, ''OLD''.
+
  
The steps below must be followed in order:
+
'''Note:''' double clicking on import_game.cmd is the same as running ''opensurge.exe --import-wizard'' on a Command Prompt.
  
# First of all, make a backup of your game. '''THIS IS MANDATORY!'''
+
=== GNU/Linux ===
# 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).
+
# PRELIMINARIES. 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.
+
## Move the sprites that you have created (all .spr files written by you that are not in the official builds of the engine) to ''sprites/mygame/''. It helps if your sprites were already in a folder of their own.
+
### Note: if you don't want to call the subfolder ''mygame'', call it something unique and keep things consistent by using the same name everywhere.
+
## 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.
+
## If you have modified the official language files (.lng files), the entries that you have modified must be moved to a special folder called ''languages/extends/''. Read the [[Translation Guide]] - particularly the language extensions section - for further information on how to properly modify the texts.
+
## 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 ''sprites/mygame/'' from ''OLD'' to ''NEW''. This folder should store all original .spr files written by you.
+
## Copy ''scripts/mygame/'' from ''OLD'' to ''NEW''. This folder should store all SurgeScript files written by you.
+
## Copy ''languages/extends/'' from ''OLD'' to ''NEW''. This folder should have your .lng files in it.
+
## 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.
+
## 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 files to the new engine.
+
## Copy ''fonts/'' 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 ''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.
+
# Now we're going to copy 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.
+
# OPTIONAL. 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.
+
# OPTIONAL. 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).
+
# OPTIONAL. 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''.
+
# OPTIONAL. 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 your game should be running in the new engine!
+
==== Flatpak / Snap ====
  
=== A simpler way ===
+
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:
  
If your assets are already separated from the assets of the base game (you keep them in separate folders), then you may try a simpler process:
+
# 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"''
  
# Make sure you have a backup stored somewhere else
+
The procedure for the Snap version is analogous.
# Extract NEW on top of the OLD and replace all files
+
# Use your backup folder to bring back the individual files you wish to keep (e.g., musics, sound effects and your quest files)
+
  
Launch the engine and make sure that all things are as you want them to be. If not, bring back more individual files, launch the engine again and repeat until you're satisfied.
+
'''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.
  
=== Troubleshooting ===
+
==== Compiled from sources ====
  
==== I lost some of my sprites ====
+
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.
  
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.
+
# Open a console
 +
# ''cd ~/path/to/opensurge/''
 +
# ''./opensurge --import-wizard''
  
==== The engine crashes with an error ====
+
A wizard will be launched. Follow the instructions on the screen. This procedure works just like it does on Windows.
  
Inspect the '''logfile.txt'''. This file is your friend, and will help you catch any conflicts that may be causing the crash.
+
==== Downloaded from distro repositories ====
  
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).
+
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:
  
If you can't solve the error, ask the community for help. Reach out on Discord or on the forums.
+
# 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''
  
'''VERY IMPORTANT:''' make sure you do NOT replace new scripts by old scripts. Using old scripts in a new engine may cause issues that require manual inspection.
+
Follow the instructions of the wizard. After successfully importing your game, launch the engine with the imported project as the game folder
  
==== I can't find some of my scripts/objects ====
+
# ''opensurge --game-folder "$HOME/path/to/the/source_release/I_just_downloaded"''
  
Make sure you have copied ''all'' the .ss files you have written into ''NEW/scripts/mygame/''. Nothing should be missing.
+
== Keep your assets separate ==
  
If you have modified an official SurgeScript file 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.
+
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.
  
==== I have modified the source code of the engine ====
+
The Open Surge Import Utility gives tips on how to keep assets separate:
  
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.
+
* 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 the version 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 their 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.
+
** Text-based files SHOULD be trimmed before computing their checksum
+
*** Note: the presence or the absence of a newline at the end of a text-based file MUST NOT make any difference for the purpose of computing its checksum
+
* 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 process described in this guide.
+
  
If you are a community member interested in contributing to open-source, making this program would be 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.