Defold for Playable Ads

This repository contains a script for the Gulp build system, which:

1. Downloads bob.jar.
2. Builds the project for the HTML5 platform using bob.jar.
3. Combines all resources into a single HTML file. The asm.js binary of the Defold engine is compressed using Zstd and encoded with Base64.

Open the build result online. Please note that it does not use any external resources as required.

Current Status

Feel free to ask questions: the topic about this asset is on the Defold forum.

Supported Platforms

About A Playable Ad

A playable ad is an interactive advertisement, mostly used to promote mobile games. A playable ad acts as a demo of the game (or product), allowing users to quickly play the game directly in the ad before downloading it.

Accepted sizes for HTML5 playable ad vary between ad networks:

1. Facebook specifications for Playable Ads require that there be a single file for playable ad that contains all assets as part of that single HTML file and assets should be data uri compressed. Also playable asset size should be less than 2MB. And Facebook has started accepting .zip archives with up to 5MB since 2020.
2. Google requires a .ZIP file with a maximum size of 5MB and no more than 512 files within the .ZIP. Plus .ZIP files can contain the following formats: HTML, CSS, JS, GIF, PNG, JPG, JPEG, SVG.
3. ironSource, AppLovin, and Unity Ads require a single HTML file. The maximum ad size is 5MB.

Required Prerequisites

You will need the following apps installed on your environment:

• Node.js 12 or newer.
• Java 11.
• Zstd 1.4 or newer.
• Gulp CLI.

Windows

1. Download and install Java 11.
2. Download and unpack Zstd for Windows 64-bit. Add the path to the zstd.exe executable to the PATH environment variable.
3. Download Node.js Windows Installer (.msi) for 64-bit and install it.
4. Open cmd.exe and run to install Gulp CLI:

npm install --global gulp-cli

Ubuntu/Debian or Windows Subsystem for Linux (WSL)

sudo apt install --no-install-recommends openjdk-11-jre-headless nodejs npm zstd

npm install --global gulp-cli

macOS

Install brew and paste that in a macOS Terminal prompt:

brew install node@14
brew install openjdk@11
brew install [email protected]

npm install --global gulp-cli

Installation & Usage

Copy the playable_ad folder into the root of your project + the .defignore file. Then, in the command line:

cd your_project_folder
cd playable_ad
npm install
gulp

npm install installs required NodeJS packages. gulp builds the project into a single HTML file.

The resulting HTML file is located at /playable_ad/build/output_js-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE.html.

Command Line Arguments

You can pass the following arguments from the command line to the script:

--embed-archive-js <arg>        Embed `_archive.js` file: true/false (default = true).

# The following arguments passed to Bob.jar as is:
--build-server <arg>            The build server (default = https://build.defold.com).
--settings <arg>                Path to a game project settings file. Only one occurrance is allowed.
--variant <arg>                 Specify debug or release (default = release).
--texture-compression <arg>     Use texture compression as specified in texture profiles (default = true).

i.e. run gulp --embed-archive-js=false to build a playable ad with the two files:

• /playable_ad/build/output_js-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE.html
• /playable_ad/build/output_js-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE_archive.js

How to shrink your game size

Follow these steps to decrease the resulting size of the HTML file significantly:

1. Use the Defold App Manifest generator to keep only the necessary parts of the engine.
2. Keep only the core mechanic of your game and all assets that it requires.
3. Toy with the Project / Compress Archive option. Zstd, used by this tool, compresses plain data better than a compressed LZ4 stream.
4. Install the latest version of the Zstd executable (i.e. Zstd 1.5.0 has better compression than Zstd 1.4.x).

License

MIT.

The splash uses an image from iconfinder.com.