Difference between revisions of "Upgrading the engine"

From Open Surge Wiki
Jump to: navigation, search
(Future work)
m (A simpler way)
 
(24 intermediate revisions by the same user not shown)
Line 7: Line 7:
 
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'''.
 
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).
+
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.
  
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.
+
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.
  
 
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].
 
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].
  
== Step by step ==
+
== Upgrading manually ==
  
This is the outline of the upgrade process. The steps below must be followed in order:
+
=== Step by step ===
 +
 
 +
This is the outline of the upgrade process. 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''.
 +
 
 +
The steps below must be followed in order:
  
 
# First of all, make a backup of your game. '''THIS IS MANDATORY!'''
 
# 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.
 
# 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).
 
## 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:
+
# PRELIMINARIES. Inside the OLD folder, '''make a clear distinction between which assets belong to your game and which do not'''.
## 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 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 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.
 
## 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.
 
## 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.
 
# 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/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 ''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 ''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.
+
## Copy ''languages/extends/'' from ''OLD'' to ''NEW''. This folder should have your .lng files in it.
# 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 ''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.
+
## Make sure you can run the new engine now. If any errors arise, fix them now. Maybe some sprites will be different already.
## Copy ''fonts/''from ''OLD'' to ''NEW''. Do NOT replace any files.
+
# 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 ''characters/'' from ''OLD'' to ''NEW''. Do NOT replace any files.
 
## Copy ''inputs/'' from ''OLD'' to ''NEW''. Do NOT replace any files.
 
## Copy ''inputs/'' from ''OLD'' to ''NEW''. Do NOT replace any files.
Line 45: Line 51:
 
## Copy ''themes/'' 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.
 
## 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.
+
# 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 ''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.
 
## 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.
+
# 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).
 
## 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''.
+
# 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''.
 
## 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.
+
# 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''.
 
## 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!
 
Now your game should be running in the new engine!
  
== Troubleshooting ==
+
=== A simpler way of upgrading ===
  
=== I lost some of my sprites ===
+
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:
 +
 
 +
# Make sure you have a backup stored somewhere else
 +
# 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.
 +
 
 +
=== Troubleshooting ===
 +
 
 +
==== 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.
 
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 ===
+
==== 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.
 
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).
 
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.
 
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 ===
+
'''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.
 +
 
 +
==== 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.
 
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.
+
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.
  
=== I have modified the source code of the engine ===
+
==== 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.
 
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.
  
== Future work ==
+
== Upgrading automatically ==
  
Upgrading a game to a new version of the engine is a process that can be automated. An automated process is less error-prone. If a program would automatically upgrade a game, here's a sketch of a spec:
+
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:
  
* The program SHOULD display some sort of logging mechanism to provide information to the user
+
* The program MUST 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
 
* 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
 
** 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 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 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
 
** 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
 
** 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
Line 102: Line 118:
 
** The program MUST use relative paths to store the listing (e.g., images/surge.png, musics/sunshine.ogg, and so on)
 
** 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
 
* 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
+
** 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.
 
*** 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 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 added files can be determined by comparing the directory tree of the game to the directory tree of the official release of the engine
Line 110: Line 128:
 
* The program SHOULD write the list of added files to its logs
 
* The program SHOULD write the list of added files to its logs
 
* The program MUST write the list of modified 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 read the logs to know which files he or she has modified.
+
** 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.
+
* 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, this would make a valuable contribution.
+
If you are a community member interested in contributing to open-source, making this program would be a valuable contribution.
  
 
[[Category:Users]]
 
[[Category:Users]]
 
[[Category:MODs]]
 
[[Category:MODs]]

Latest revision as of 20:36, 22 May 2022

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.

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.

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 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.

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.

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.

Upgrading manually

Step by step

This is the outline of the upgrade process. 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.

The steps below must be followed in order:

  1. First of all, make a backup of your game. THIS IS MANDATORY!
  2. Get a clean build of the new version of the engine. Make sure you are able to run it correctly.
    1. 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).
  3. PRELIMINARIES. Inside the OLD folder, make a clear distinction between which assets belong to your game and which do not.
    1. 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.
    2. 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.
      1. 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.
    3. 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.
    4. 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.
    5. Make sure that you can still run your game using the old engine. If any errors arise (should not happen), fix them now.
  4. Now we're going to copy the assets we have just moved into the new engine.
    1. 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.
    2. Copy sprites/mygame/ from OLD to NEW. This folder should store all original .spr files written by you.
    3. Copy scripts/mygame/ from OLD to NEW. This folder should store all SurgeScript files written by you.
    4. Copy languages/extends/ from OLD to NEW. This folder should have your .lng files in it.
    5. 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.
    6. Make sure you can run the new engine now. If any errors arise, fix them now. Maybe some sprites will be different already.
  5. Now we're going to copy the bulk of the files to the new engine.
    1. 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.
    2. Copy characters/ from OLD to NEW. Do NOT replace any files.
    3. Copy inputs/ from OLD to NEW. Do NOT replace any files.
    4. Copy levels/ from OLD to NEW. Do NOT replace any files.
    5. Copy musics/ from OLD to NEW. Do NOT replace any files.
    6. Copy quests/ from OLD to NEW. Do NOT replace any files.
    7. Copy samples/ from OLD to NEW. Do NOT replace any files.
    8. Copy themes/ from OLD to NEW. Do NOT replace any files.
    9. 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.
  6. Now we're going to copy two standard quest files to the new engine:
    1. Copy quests/intro.qst from OLD to NEW. Replace the file.
    2. Copy quests/default.qst from OLD to NEW. Replace the file.
    3. Make sure you can run the new engine now. If you find any errors, fix them now.
  7. OPTIONAL. If you have replaced some musics and/or sound effects in your game, you may want to keep them.
    1. Optionally, copy your own files inside samples/ from OLD to NEW. Replace the files you want to replace.
    2. Optionally, copy your own files inside musics/ from OLD to NEW. Replace the files you want to replace.
  8. OPTIONAL. If you have modified the default controls of the game, you may want to keep your modification.
    1. Optionally, copy inputs/default.in from OLD to NEW (or merge the file manually for greater control).
  9. OPTIONAL. It may be desirable to keep your save state. Save states are stored in a file called surge.prefs.
    1. Optionally, copy surge.prefs from OLD to NEW.
  10. OPTIONAL. If you have created new files for your game (example: your own user manual), you should keep them.
    1. 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!

A simpler way of upgrading

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:

  1. Make sure you have a backup stored somewhere else
  2. Extract NEW on top of the OLD and replace all files
  3. 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.

Troubleshooting

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).

If you can't solve the error, ask the community for help. Reach out on Discord or on the forums.

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.

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 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.

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 automatically

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:

  • The program MUST 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 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.