HOWTO-Backends

Introduction

This page is meant as a mini-HOWTO which roughly outlines the steps needed to add a new backend (port) to ScummVM. Before you embark on this quest, however, you should first check if one of the existing backends already suits your needs. In particular the SDL backend already supports many platforms, since SDL itself is quite portable.

But if you have determined that a new backend is what you need, the following should hopefully help you a bit with that. Feedback is welcome :-).

I will assume that you are at least roughly familiar with ScummVM, and have a fresh checkout of our source code repository. Note that it's strongly advised to base your work on the current development version of ScummVM, and not on a release version. This will ease integration of your work.

Overview

Essentially, you will have to implement a subclass of the OSystem class. Our Doxygen documentation is your friend and should hopefully explain enough about this, see OSystem class.

You also need to either hook yourself into the regular ScummVM build system, or provide your own. Finally, you need to make ScummVM aware of your new backend by updating a couple source files (see below).

Step by step

In the following I assume your port is named "foobar" (very clever, isn't it? :-)).

Create a new backends/platform subdirectory matching your port name, i.e. backends/platform/foobar/.
Populate the new directory as you need to. If you want to use our regular build system, you will want to provide a backends/platform/foobar/module.mk file. Take a look at backends/platform/sdl/module.mk for an example.
Subclass OSystem. You could copy the content of backends/platform/null/null.cpp to backends/platform/foobar/foobar.cpp to get a skeleton. As you progress, it might be helpful to look at other backends to learn how they do things.
Make sure to provide the main function in your backend (the actual main function of ScummVM is scummvm_main, which your backend must invoke at some point).
Instantiate the OSystem class and assign it to g_system, do that before calling scumm_main.
Deinit properly after calling scumm_main, particularly call g_system->destroy().
If appropriate, edit configure to add your backend (this is only necessary if you are going to use the "./configure && make" build system).

Example of minimal main()

int main(int argc, char *argv[]) {
	// Create our OSystem instance
    g_system = new OSystem_Foobar();
    assert(g_system);
    
    // Invoke the actual ScummVM main entry point:
    int res = scummvm_main(argc, argv);

	// Free OSystem
	g_system->destroy();

    return res;
}

That's it. The difficult part is of course writing the OSystem subclass. More on that in the next section!

Subclassing OSystem

TODO: This section is meant to give some specific hints on creating a useful OSystem subclass. For now I can't really think of anything useful besides the obvious, and besides what we already say in other places... Take a look at OSystem class which contains lots of useful information. Also take a look at null.cpp to see what you have to implement, and peek at the SDL backend (which is our main backend and thus kind of a reference for all the others). And finally, take a look at common/system.h to see which methods are pure abstract, and thus must be implemented by you. Oh and of course: You can always talk to us on IRC or via email :-).

Implementing subsystems

Testing your backend

We have a special game engine, called 'testbed'. Its only purpose is to perform series of tests which help backend authors to see correctness of their implementation.

To run the game, point ScummVM to directory <scummvm sources root>/dists/engine-data/testbed-audiocd-files/ and then run. Follow the on-screen instructions.

Misc notes

There is a Small Devices Backend in the works which is planned to be common for all devices with limited resources. If you are working on a backend for such a system, you may want to take a look on that page!