Upgrading the engine

From Open Surge Engine Wiki
Revision as of 20:40, 26 January 2021 by Alexandre (Talk | contribs) (Upgrading automatically)

Jump to: navigation, search

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

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. 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. For the purposes of this guide, we'll establish the following conventions:
    1. We'll call the folder that stores the game assets of the new version of the engine NEW.
    2. We'll call the folder that stores the game assets of your project, using the old version of the engine, OLD.
  4. 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. If you have modified one or more translation files (.lng extension), copy 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).
    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. Make sure that you can still run your game using the old engine. If any errors arise (should not happen), fix them now.
  5. 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 languages/mygame/ from OLD to NEW, if that subfolder exists.
    3. Copy scripts/mygame/ from OLD to NEW. This folder should store all SurgeScript files written by you.
    4. Make sure you can run the new engine now. If any errors arise, fix them now. Maybe some sprites will be different already.
  6. Now we're going to copy the bulk of the media (images, audio, etc.) to the new engine.
    1. 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.
    2. Copy sprites/from OLD to NEW. Do NOT replace any files.
    3. Copy fonts/from OLD to NEW. Do NOT replace any files.
    4. Copy characters/ from OLD to NEW. Do NOT replace any files.
    5. Copy inputs/ from OLD to NEW. Do NOT replace any files.
    6. Copy levels/ from OLD to NEW. Do NOT replace any files.
    7. Copy musics/ from OLD to NEW. Do NOT replace any files.
    8. Copy quests/ from OLD to NEW. Do NOT replace any files.
    9. Copy samples/ from OLD to NEW. Do NOT replace any files.
    10. Copy themes/ from OLD to NEW. Do NOT replace any files.
    11. 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.
  7. 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. 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. 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. 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.
  11. Now we're going to move 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.

Now your game should be running in the new engine!

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 script that is shipped with Open Surge, we recommend that you drop your modification. Know that this is not recommended practice, because official scripts may receive updates and fixes from time to time. If you need to create such a modification, make a copy of the official script and modify YOUR COPY instead.

I have modified the source code of the engine

When you modify the source code of the engine (in C language), you lose compatibility with the official releases. You must carefully merge the changes by yourself and then recompile the project. This is an advanced operation, not meant for the average user.

Upgrading 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, this would make a valuable contribution.