DETONATOR 2D 💥💣

An OpenGL ES based 2D game engine and editor for Linux, Windows and HTML5. Designed for simple single player games such as puzzle games, platformers, side scrollers and tile based real time strategy and tactics. �?�🧩🗺�?

This readme and other readme files, are for developers and cover information related to developing and building the engine itself. For end user guide see help instead.

This project would not be possible without the following �?

• Qt, GLM, Freetype, Harfbuzz, Lua, sol3, STB, nlohmann/json, mpg123, libsndfile, Box2D, Emscripten and many others!
• Royalty free art from https://opengameart.com

Other (subsystem) readmes:

• Audio 🎼
• Graphics (todo)
• Game (todo) 👾
• Engine (todo)
• UI
• WDK

Currently, supported major features:

• Qt5 based WYSIWYG editor
• Text rendering (vector and bitmap)
• Various primitive shapes, custom polygon shapes
• Material system with built-in materials and with custom shaders
• Particle system with projectile and linear motion
• Entity system with animation tracks
• Audio engine with approx. dozen audio elements
• Lua based scripting for entities, scenes and UIs
• Built-in Lua script editor with code formatting and API help
• Scene builder
• Styleable UI system (JSON style files and material system integration)
• Physics engine based on Box2D
• Demo content and starter content
• Game content packaging for native and HTML5/WASM (with Emscripten)
• Resource archives, export and import between projects (in zip)
• Tilemap importer, several handy dialogs for materials, fonts, colors etc.
• Several tools for texture packing, font map packing, etc.

Currently, not yet 100% complete major features:

• Continued work on tilemaps
  • Lua APIs for data access etc.
  • Related algorithms such as path finding
  • Compression etc. performance improvements
  • Rendering performance improvements and fixes

Planned major features not yet implemented:

• Partial 3D support for specific objects (think objects such as coins, diamonds, player ship etc.)
• OpenGL ES3 backend and WebGL2 support
• Android support (TBD)
• Mobile web + touch screen support
• Post-processing effects such as bloom, custom render passes
• Vector fields, fluid sims, more elaborate particle effects
• Plenty of asset baking features
• Acceleration structures for game subsystems such as physics and rendering

Planned minor features not yet implemented:

• See issues for more details

Create animated game play characters in the entity editor. Each entity can contain an arbitrary render tree of nodes with various attachments for physics, rendering, text display etc. Animation tracks allow changing the properties of the nodes and transforming the tree itself over time. Each entity type can then be associated with a Lua script where you can write your entity specific game play code.

Create materials using the material editor by setting some properties for the provided default material shaders. Currently, supports sprite animations, textures (including text and noise), gradient and color fills out of box. Custom shaders can be used too.

Create the game play scenes using the scene editor. The entities you create in the entity editor are available here for placing in the scene. Viewport visualization will quickly show you how much of the game world will be seen when the game plays.

Create the game's UI in the UI editor. The UI and the widgets can be styled using a JSON based style file and then individual widgets can have their style properties fine-tuned in the editor. The style system integrates with the editor's material system too!

Create audio graphs using the audio editor. Each audio graph can have a number of elements added to it. The graph then specifies the flow of audio PCM data from source elements to processing elements to finally to the graph output. Currently, supported audio backends are Waveout on Windows, Pulseaudio on Linux and OpenAL on HTML5/WASM. Supported formats are wav, mp3, ogg and flac.

Use the built-in code editor to write the Lua scripts for the entities, scenes, game or UI. The editor has a built-in help system for accessing the engine side Lua API documentation as well as automatic Lua code formatting and linting.

The particle editor allows several types of particle effects to be created conveniently by adjusting several sliders and knobs that control the particle effect.

During the development the game is available for play in the editor. It's possible to do live edits to the game content in the editor and see the changes take place in the play window.

Build Instructions 👨�?��?💻

WASM (Emscripten)

Some notes about building to WASM.

• Building to WASM is currently supported only for the engine but not the editor.
• The build is separated from the main engine build and is in emscripten/ folder.
  • See emscripten/CMakeLists.txt for build details.
• Current Emscripten version is 3.0.0. Using other version will likely break things.
• If using Windows Install Ninja from https://github.com/ninja-build/ninja/releases.
  • Drop the ninja.exe for example into the emsdk/ folder or anywhere on your PATH.

  $ cd detonator
  $ git clone https://github.com/emscripten-core/emsdk.git
  $ cd emsdk
  $ git pull
  $ ./emsdk install latest
  $ ./emsdk activate 3.0.0
  $ source ./emsdk_env.sh

  $ which emcc
  $ /home/user/emsdk/upstream/emscripten/emcc
  $ emcc --version
  $ emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.0.0 (3fd52e107187b8a169bb04a02b9f982c8a075205)

  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ cd emscripten
  $ mkdir build
  $ cd build
  $ emcmake cmake .. -DCMAKE_BUILD_TYPE=Release
  $ make -j16 install

  $ cd detonator
  $ git clone https://github.com/emscripten-core/emsdk.git
  $ cd emsdk
  $ git pull
  $ emsdk.bat install latest
  $ emsdk.bat activate 3.0.0
  $ emsdk_env.bat

  $ where emcc
  $ C:\coding\detonator\emsdk\upstream\emscripten\emcc
  $ C:\coding\detonator\emsdk\upstream\emscripten\emcc.bat
  $ emcc --version
  $ emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.0.0 (3fd52e107187b8a169bb04a02b9f982c8a075205)
  $ where ninja
  $ C:\coding\detonator\emsdk\ninja.exe
  $ ninja --version
  $ 1.10.2

  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ cd emscripten
  $ mkdir build
  $ cd build
  $ emcmake cmake .. -DCMAKE_BUILD_TYPE=Release
  $ ninja -j16
  $ ninja -j16 install

If everything went well there should now be GameEngine.js and GameEngine.wasm files in the editor's dist folder. The .js file contains the JavaScript glue code needed to manhandle the WASM code into the browser's WASM engine when the web page loads. When a game is packaged for web these files will then be deployed (copied) into the game's output directory.

Desktop Linux

  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build
  $ cd build
  $ conan install .. --build missing
  $ cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Release
  $ make -j16 install
  $ ctest -j16

  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build_d
  $ cd build_d
  $ conan install .. --build missing
  $ cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Debug
  $ make -j16 install
  $ ctest -j16

  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build_profile
  $ cd build_profile
  $ conan install .. --build missing 
  $ cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
  $ make -j16 install

  $ cd detonator/audio/test/
  $ valgrind --tool=cachegrind ./audio_test --graph
  $ kcaghegrind cachegrind.out.XXXXX

  $ export CC=/usr/bin/clang
  $ export CXX=/usr/bin/clang++
  $ conan profile new detonator-clang --detect
  
  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build
  $ cd build
  $ conan install .. --build missing --profile detonator-clang
  $ cmake -G "Ninja" .. -DCMAKE_BUILD_TYPE=Release -DUSE_MOLD_LINKER=ON 
  $ ninja -j16 install

  $ cd detonator/editor/gui/qt
  $ mkdir build
  $ cmake -G "Unix Makefiles" .. -DCMAKE_BUILD_TYPE=Release
  $ make -j16 
  $ sudo make install

$ conan profile new default --detect

Desktop Windows

These build instructions are for MSVS 2019 Community Edition and for 64bit build.

  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build
  $ cd build
  $ conan install .. --build missing
  $ cmake -G "Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=Release ..
  $ cmake --build   . --config Release
  $ cmake --install . --config Release

  $ git clone https://github.com/ensisoft/detonator
  $ cd detonator
  $ git submodule update --init --recursive
  $ mkdir build_d
  $ cd build_d
  $ conan install .. --build missing -s build_type=Debug
  $ cmake -G "Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=Debug ..
  $ cmake --build   . --config Debug
  $ cmake --install . --config Debug

  $ cd editor\gui\qt
  $ mkdir build
  $ cmake -G "Visual Studio 16 2019" -DCMAKE-BUILD_TYPE=Release
  $ cmake --build . --config Release
  $ cmake --install . --config Release

The Boring Documentation 🥱

Workflow and getting started 📔

Going from a git clone to a running game is known as the "build workflow". This involves various steps involving the source tree of the engine, the source tree of the game, the runtime assets provided with the engine and the runtime assets that are part of the game. Overall this will involve several build and packaging steps.

Currently, only Lua based games are supported. There's a provided game engine that is built into a shared library and which contains all the relevant functionality for running a game. That is it will take care of rendering the scene, ticking the physics engine, handling the UI input as well as invoking the Lua scripts in order to run your game code. It's possible to also not use this provided engine but write a completely different engine. In this case the interface to implement is the "Engine" interface in engine/main/interface.h.

From source code to a running game:

1. Build the whole project as outlined in the Build Instructions previously. You will also need to install the build targets. Installing not only copies the binaries into the right place but also copies other assets such as GLSL shader files. Without the installation step things will not work correctly!
2. After building launch the Editor from the editor/dist folder.
3. In the Editor: Open your game's workspace folder. This is the folder that contains the workspace.json and content.json files. In DETONATOR 2D this is essentially your "project" (It's simply a folder with those two specific files in it).
4. In the Editor: Package your content. (Workspace|Package). Select the assets you want to package (most likely everything). When the packaging process is complete your selected output directory will contain the following:
   1. The game resources copied over, i.e. shaders, textures, font files etc.
   2. A content.json file that contains the resource descriptions for your assets that you've built in the editor
   3. A config.json file that contains the settings for the GameMain to launch the game
   4. A native "GameMain" executable and engine library. These are the default game studio binaries for running your game content after the project has been packaged.
   5. FILESYSTEM, FILESYSTEM.js, game.html GameEngine.wasm, GameEngine.js. These are the HTML5/WASM files that are needed to run the game in the browser.
5. After packaging launch your game by running the GameMain executable in the package output directory.

Running (Unit) Tests 🫣

There's a bunch of unit tests that are built as part of the normal build process. Basically anything that begins with a "unit_test_" is a unit test.
For writing tests there's a very simple testing utility that is available in base. base/test_minimal.h

In addition to having the unit tests both the audio and graphics subsystems also have "rendering" tests, i.e. playing audio or rendering stuff on the screen. The rendering tests rely on a set of gold images a.k.a. known good images. Currently, the images are provided as part of this repository but there's the problem that because of differences in OpenGL implementations it's possible that the rendering output is not exactly the same between various vendors/implementations (such as NVIDIA, AMD, Intel etc. Fixing this is a todo for later). The audio tests, however, don't have any automated way of verifying the test output.

See this list for known Issues

On the desktop (Linux/Windows)

  $ cd detonator/build
  $ ctest -j16

  $ cd detonator/audio/test
  $ ./audio_test --mp3 --ogg --flac --24bit
  $ ...
  $ ./audio_test --help

  $ cd detonator/graphics/test/dist
  $ ./graphics_test --test --msaa4
  $ ...
  $ ./graphics_test --help 

On the Web (WASM+HTML5)

Currently, only some unit tests are available on the web. More tests will be enabled as needed.

  $ cd detonator/emscripten/bin
  $ python -m http.server

System Architecture

See this document

Coding Convention & Design 💭

See this document

Tracing & Profiling 💭

See this document