Developer Central

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of ScummVM.

Getting started

• The first thing you need to be able to do is get the ScummVM code from our Git repository.
• Fork ScummVM main Git repository, this will be your working space
• Then you should compile ScummVM.
• If you are new to open source, you can also try reading https://opensource.guide/how-to-contribute/
• Then read Help! Where do I start with the code base?

That was easy, right? Here are some more tips:

• Some hints on debugging ScummVM.
• Before you write/submit code, you must read our Code Formatting Conventions.
  Patches which do not follow them will be rejected or at least delayed until they are cleaned up to comply to them.
• Also, you should read and respect the general Coding Conventions.
• Our bug tracker might provide some easy tasks to start with and familiarise yourself with the ScummVM code base.
• If you have write (push) access to our repository, you are expected to have read and to comply with our Commit Guidelines.
  Also, please read the tips for using Git here: Git tips.
  In particular, note the use of feature branches, when working on refactoring or other large connected changes, rather than committing directly to scummvm/master.
• If you do not have write (push) access to our repository, you should submit your contributions by one of the following methods:
  • Using a Github Pull Request.
    This requires you to have/register a github account, fork our repository, commit your changes to a branch and then issue a Pull Request.
    This is the current preferred method as it is easier for the team to review, discuss and amend prior to merging.
    You are expected to have read and to comply with our Commit Guidelines.
  • Using the patch tracker.
    This requires you to have/register a github account, and generate a patch file, but this may be easier for developers unfamilar with Git or for small single commit changes, where a Pull Request might be considered overkill.
  • If neither of the above methods are suitable, individual developers may be willing to accept patches or amended source files by other methods i.e. e-mail, but please ask in the project IRC channel or by e-mail before doing this.
• Our Doxygen source code documentation may help you to get the big picture about ScummVM.
• Also, you might want to check our list for current Platform Limitations.

Help! Where do I start with the code base?

The main programming language used for ScummVM is C++. It also uses a mix of other languages, such as Python (for some dev tools), ObjectiveC (in the macOS and iOS backends) or Java (in the Android backend). But those account only for a very small portion of the source code.

Code base structure

The ScummVM code base is quite big, but well structured with five main components:

Component	Source code location
The OSystem API, which defines available features a game can use, such a drawing on screen or receiving keyboard and mouse events.	common/system.h
The backends, which implement the OSystem API for various platforms.	backends/
The game engines.	engines/
Common code, that provides various utility classes (for example containers) and audio, image, and video codecs that game engines can use.	common/ audio/ image/ video/
Gui code, that provides a graphical user interface for the game launcher and options dialog.	gui/

And then you have a few more directories:

• base/

This is the entry point for the application. It for example handles command line argument parsing and the main loop. See Entry points below.

• test/

Contains unit tests for some utility classes from the common code.

• po/

Contains translation of the ScummVM GUI into various languages

First steps

The OSystem API shields game engines and gui code from the actual platform the software is running on. The backends code is the only part of the code base that is platform dependent. So if you want to work on a game engine for example you will need to look at the OSystem API to know what you can do in the engine, but you can ignore everything in the backends code as you don't need to know how the OSystem API is actually implemented. On the other hand if you want to port ScummVM to a new platform, the backends code is what you will want to look at.

You can start by browsing a bit the source code to see how it maps to the description above, and then depending on your interests select one piece of code to look at in more details. For example if you are interested in ports, look at how one specific port is implemented. Or if you are interested in game engines, look at one engine.

In you are interested in game engines, the plumber engine is the simplest one by far, and you can start from there to see the overall structure of an engine. Then you can select an engine for one of the free games we have on our download page (for example Flight of the Amazon Queen, with the corresponding engine source code in engines/queen/), or a game you already own. You can make changes and see how it behaves, run the engine with a debugger, and use an hexadecimal editor to look at the game data file and map them to what the engine does. At first you can in particular look at the engine's use of the classes in the common/ folder, such as Common::File, Common::Array. Start getting a feel for what classes are available before you move onto the graphic and event handling stuff.

If you interest lies with ports and how ScummVM interacts with various operating systems, take a look at the source code in backends/. There are two main categories of backends: monolithique ones and modular ones. The modular backends split the OSystem API implementation between several modules, the GraphicsManager being maybe the most important. Most modular backends use the SDL library and share some code between them.

Our doxygen documentation might help to grasp class hierarchy and navigate the source code at first. In particular it provides a visual representation of the relationship between classes. Using an IDE such as Visual Studio, Xcode, Eclipse, QtCreator or CLion can also be a big help. See the create_project tool to generate projects for various IDE.

Once you are no longer completely lost and have a grasp of the code base structure, a good way to dive deeper might be to find a task to work on. You can have a look at the bug tracker and the various TODO lists on this wiki. See the Projects, plans, things to do section. Once you have a sense of something concrete you want to work on, you are highly encourage to visit our IRC channel (#scummvm on libera.chat) or Discord server (see our Contact page) where you can ask for helps and guidance from fellow developers.

Entry points

1. The executable entry point varies depending on the platforms (and therefore it is in backends/). For example for Linux you will find it in backends/platform/sdl/posix/posix-main.cpp while for macOS it is in backends/platform/sdl/macosx/macosx-main.cpp.
2. From there it goes into the actual ScummVM main entry point, scummvm_main() implemented in base/main.cpp.
3. It alternates between showing the Game Launcher and running a game.
   1. While the GUI is running (in the game launcher or options dialog) the main loop is GuiManager::runLoop() in gui/gui-manager.cpp.
   2. Each game engine has its own entry point, which is its implementation of the pure virtual Engine::run() function.

Pull Request approval process

The current procedure is as follow:

1. For a sizeable, significant changes it is advised to make a Pull Request on GitHub.
2. Such Pull Request will have to stay for at least a week open for the comments.
3. Everyone is invited to comment and review and voice their opinion (views of non-team members are valuable, but have no decisive power).
4. If there are no unaddressed objections after 2 weeks, the PR could be merged. Exception could be made if there are suggestions over refactoring or tidying up the code, granted that they will be addressed in-tree.
5. Immediately after the merge the PR maker ensures that the buildbot stays happy and is not worsened (historically we had few ports broken for months).

The definition of what makes a sizeable changes not cast in stone. This is up to the discretion of the PR creator, but normally we would expect that anything which breaks existing OSystem API and the Common code, or significantly extends these, especially if it requires more work from the Porters, should go via a Pull Request process. The goal is to ensure that everything stays maintainable.

Any developer is free to open a PR for less significant changes, and that process could be used for facilitating the discussion and collecting feedback, but when there are no big changes involved, no 2 weeks timeout is enforced.

Individual engine sub-teams decide by themselves on the process. For example currently the SCI development is performed via PRs as well for any sizeable changes. It is up to that sub-team to drop this rule any time or make something even stricter. Just make sure you continue enjoying hacking the ScummVM code.

Joining the Team and expectations

There are covered on the Team Onboarding page.

For Engine authors

• If you want to provide a new Engine for ScummVM, check out our Engines HOWTO.
• If you work on a game engine for ScummVM, consider implementing Advanced Engine Features.
• If your engine supports multiple games / game variants, properly detecting and differentiating them all can be a nuisance. Use the Advanced Detector to overcome this hurdle.
• Accessing files in a portable fashion is non-trivial. Read all about how to open files.
• Define remappable input handing using the Keymapper.
• Debugging endian issues can be tricky. This page gives some solutions.
• If you want to have your engine merged into the ScummVM mainline, check out our Engine Inclusion HOWTO.
• For those starting out with reverse engineering, check out our Reverse Engineering HOWTO.
• Apart from git bisection to locate regressions in gameplay, the (experimental) Event Recorder provides a framework for recording and replaying gameplay to detect regressions.
• For some general suggestions on developing engines, see the Engine Development Tips & Tricks
• When your engine is ready to be playtested and supported, please follow the How To Release Engine guide
• On October 3, 2020, we have our engine plugins API changed please follow How to Convert Plugins guide if you started your engine development prior to that
• See the List of External Projects for a list projects and tools that might be candidates for merging into ScummVM in the future. Or It may at least save some duplication of effort if a game you want to add support for has already had work done on it.

For Backend authors

• If you want to port ScummVM to a new platform, check out our Backends HOWTO.
• The Dynamic Modules HOWTO describes how to implement loadable modules on a smaller backend, even without operating system support.

For Web site maintainers

If you want to update the main web site:

1. Update the files you want in the scummvm-web project
2. Go to https://www.scummvm.org/admin/ and log in (ask sev for an account)
3. Click "ScummVM.org manual site update"

This is also covered in more detail by the relevant section of the Admin HOWTO here.

If you want to regenerate from the data spreadsheet:

• composer update-data

Contribution guide for technical writers

The user documentation is located at docs.scummvm.org. It is written in reStructuredText or markdown, built using Sphinx, and deployed by Read the Docs. The recommonmark extension enables parsing of markdown files. The sphinx-panels extension uses custom rST directives to provide Bootstrap functionality. All documentation is written to conform to the Google developer documentation style guide.

For small changes

For small changes to existing documentation, such as fixing spelling, grammar, or correcting a mistake:

The easiest way to make a change is to use the Edit this page on GitHub link on the applicable page to edit documentation online, on GitHub. Bear in mind that you won’t be able to upload images while working in this way. Once you are happy with your changes, create a pull request (PR). The ScummVM team will review the pull request, and if there are no issues, it will be merged into the existing code.

For large changes

For larger changes, such as documenting a new feature, documenting a new (or existing) port, or writing a guide:

Set up your environment

1. Install Python3.

• Linux: Comes with Python3 installed

• macOS

• Windows.

2. Install pip3.

• Linux: Install pip3 from the software repository. For a Debian-based distro, use sudo apt install python3-pip
• Windows: Pip3 is installed when you install Python3.
• macOS: Pip3 is installed if you install Python3 with Homebrew.

3. Use pip3 to install sphinx, sphinx-panels, sphinx-tabs, m2r2 and sphinx-rtd-theme.

4. Install Git, if you don’t have it already.

5. Fork and clone the scummvm repository.

6. Create and checkout a new branch.

Create and edit documentation

Documentation files are found in scummvm/doc/docportal/ .

Images, screenshots and GIFs are found in scummvm/doc/docportal/images/ .

There are many options for editing and creating documents. A particularly good one is VS Code, which features extensions to help you write in reStructuredText/markdown, as well as Git integration.

Here is a handy guide to reStructuredText, as it is used by Sphinx.

If you are creating a new Platform or Settings page, use the template provided in the scummvm/doc/docportal/contribute/ directory: platform_template.rst or settings_template.rst. This is to ensure our documentation remains consistent and predictable for the end user.

Preview your documentation

To build a preview of the documentation, open a new Terminal window, and change your working directory until you are in the docportal directory. Use the make html command. The output HTML files are in the scummvm/doc/docportal/_build/html/ directory. Open the index.html file in a browser to view the index page of the site.

Note: Do not commit the _build folder to your branch. The documentation is built by Read the Docs before deployment, so the local build is not required.

Commit your work

Follow the ScummVM Commit Guidelines when you make a commit.

Create a Pull Request

For documentation related to the CURRENT release, create a pull request against the branch for the current version. For example, to make a change or add documentation applicable to ScummVM version 2.2.x, open a pull request against branch-2-2. For documentation related to the NEXT release, open a pull request against the master branch.

Projects, plans, things to do

We are usually happy to receive any kind of help with the things listed below.

• List of open tasks, with relatively detailed descriptions, and contact points. Some rather small ones, some bigger ones, take a look. GSoC Ideas also has some ideas, intended for students applying for Google's Summer of Code.
• Main TODO list (contains links to many further specialized TODO pages, e.g. for specific engines).
• Our bug tracker lists bugs that need to be resolved and also lists features requested by all kinds of people.

The following are partially outdated, but kept for now for the sake of reference.

• Small Devices Backend -- this was under development as part of the GSoC, but additional help is welcome.
• Keymapping Improvements -- still in the design stage. Help is welcome.
• Music drivers redesign -- in phase of discussion

New GUI

Our "new" GUI is themeable and translatable. If you are interested in writing a custom theme, the following may be of help for you:

• GUI Themes
• GUI Theme Specs
• GUI Translation Support in code
• Translation HOWTO for translation authors
• RTL (Right-to-Left) based GUI
• GUI TODO

Networking

• Cloud Storage Support
• Local Webserver

Release Management

• Our release guideline for ScummVM Release HOWTO
• Our release testing status for the latest stable release Release Testing
• Anyone who wishes to bundle ScummVM with games for legal commercial and non-commercial release should read the notes here.

Code statistics

Our commit logs are fed to several freely available statistics tools:

• OpenHub project analysis nice graphs and devs activity
• CIA.vc statistics, current development
• GitHub page, current development on github

Team Member Benefits

Every active ScummVM Team member is eligible for enhanced access to our Project Services and some further benefits:

• being added to our main credits (do it by yourself in scummvm/devtools/credits.pl)
• @scummvm.org forwarding address
• DEVS status in our Discord Server
• operator status in our IRC Channel #scummvm @ libera.chat
• moderator status on ScummVM Forums and appropriate badge "ScummVM Developer" or "ScummVM Porter" or special one
• ScummVM Wiki account
• having development blog displayed on ScummVM Planet
• using project donations for purchasing necessary things for the development, such as game copies, software licenses, etc.

If you need any of the above, talk to sev.

If you do admin tasks e.g. responding to bugs, moderating the forums, you should read the Admin HOWTO here for tips and guidelines on doing this.

Tools

• IDA Freeware Version 5.0 - IDA is the preferred tool for disassembling old games from scratch. The most recent freeware version no longer supports disassembling DOS games, but this earlier version still supports it.

Misc

• List of Defines used in the source code.
• Documentation on how we performed our CVS to Subversion conversion.
• Old page listing pros and cons between CVS and SVN before the conversion was made.
• A guide on submitting Screenshots for use on our website.