Game Packaging

Introduction

This page contains information for packaging and distributing freeware games & demos (as DLCs) through in-app DLC downloader.

Platform-specific Guides

1. ScummVM Cloud
2. Android

Packaging tools and scripts

It is a set of tools and scripts to help packaging games in different distribution platform specific formats. Available on https://github.com/scummvm/scummvm/tree/master/devtools/packaging.

There are three main files:

1. dlc-games.json: This contains all the metadata required for creating game packages. The games need to have their metadata described here before they can be packaged using package.py.

You may use the following template to add a new entry (consists of metadata for both ScummVM Cloud and Android Play Store):

"beneath-a-steel-sky": {
		"name": "Beneath a Steel Sky - Freeware CD Version",
		"packname": "beneath_a_steel_sky",
		"scummVMConfigData": {
			"description": "Beneath a Steel Sky (v0.0372 CD/DOS)",
			"engineid": "sky",
			"extra": "v0.0372 CD",
			"gameid": "sky",
			"guioptions": "lang_English (GB) lang_German lang_French lang_English (US) lang_Swedish lang_Italian lang_Portuguese (Brazil) lang_Spanish",
			"language": "",
			"platform": "pc"
		},
		"size": "69377781",
		"url": "https://downloads.scummvm.org/frs/extras/Beneath%20a%20Steel%20Sky/bass-cd-1.2.zip"
	},

Note: "packname"'s value must start with a letter and can only contain letters, numbers, and underscores [1].

2. export-platforms.json: This consists of the description of scripts that prepare/package the game in a specific format recognized by the distribution store and, if possible, upload the game directly to the distribution store. You can include the 3rd party SDK/scripts/tools or self-written scripts in the packaging/scripts directory.

Here is an example for an entry to export-platforms.json (The single $ means variable from packaging/package.py context, double $ means variable from packaging/dlc-games.json, and triple $ means it is an environment variable):

"android": {
		"target": "android",
		"prepare": {
			"type": "python-script",
			"location": "android/generate_asset_pack.py",
			"options": {
				"--packagename": "org.scummvm.scummvm",
				"--assetpackname": "$$packname",
				"--deliverymode": "on-demand",
				"--assetsdir": "$game_location",
				"--outdir": "output/android"
			},
			"successMessage": "Asset pack required for bundling stage is successfully created!"
		},
		"bundle": {
			"type": "python-script",
			"location": "android/add_packs.py",
			"options": {
				"--androidsdk": "$$$ANDROID_SDK_ROOT",
				"--sdkver": "33",
				"--buildtoolsver": "33.0.2",
				"--bundletool": "scripts/android/bundletool-all-1.15.1.jar",
				"--inputbundle": "$binary_location",
				"--packdir": "output/android",
				"--packnames": "$$packname",
				"--output": "output/android/scummvm-bundled.aab"
			},
			"successMessage": "Android App Bundle is successfully created in output/android. You can now manually upload this file on Google Play Console."
		},
		"upload": {
			"type": "none"
		}
	}

Note: The "bundle" and "upload" are optional. "bundle" scripts are only required if the distribution platform does not support standalone DLC upload. It is possible that you might need to change the schema for export-platforms.json and adapt the packaging/package.py accordingly. For more details and reasoning, you may read this blog.

3. package.py: This script utilizes both dlc-games.json and export-platforms.json to get the required metadata and execute the required scripts. The final output is a ready-to-upload file that can be directly uploaded to the distribution platform.

To run, use: python3 package.py --export-platform [platform as per export-platforms.json] --game [game key as per dlc-games.json] --game-location [directory for the extracted game folder] --binary-location [directory for the ScummVM binary]. The --binary-location is optional and is only required if the platform requires bundling the DLCs with the base program (ScummVM). For example, the Android Play Store requires the on-demand assets (DLCs) to be bundled with base APK in AAB format, and thus, we need to first build the ScummVM binary and then provide the --binary-location.

How to extend DLC support to more distribution stores

The general steps/tips are:

1. Identify if the store have DLC support and have appropriate API or SDK for managing on-demand downloads. You may check this sheet containing information about various distribution stores for reference (might be outdated).
2. Create a new class that implements backends/dlc/store.h. See backends/dlc/android/playstore.cpp as an example.
3. Set the dlcspath in appropriate backends.
4. Use #ifdef USE_DLC where applicable. Before building, make sure to enable DLC support by using --enable-dlc with ./configure.
5. Add a new entry to packaging/export-platforms.json.