.. contents:: Table of Contents Mbm Engine ========== **MBM** is a given name to a graphics engine which provides basic and essential resources to develop games or graphics applications 2D or 3D. For now, is possible to develop games for :guilabel:`Windows` , :guilabel:`Linux` , :guilabel:`Android` , :guilabel:`iOS` , and :guilabel:`macOS` . The intention is to provide the minimum necessary for game development or graphics application using minimal dependencies. The engine is written in `C++11 `__ language using `OpenGL-ES `__ / `Metal `__ / `DirectX 9 `__ on its core and `LUA `__ as a scripting language. .. note:: Although there is an effort to migrate the whole project to `C++11 `__ still there is a lot of mixed `C `__ code and maybe is not the best project to be as an example! Another Game Engine! -------------------- .. figure:: _static/emoji.png :align: left Yes I know! This is a personal project that I have been working for a long time (~ 2004). It started as a way to understand :guilabel:`C++`, :guilabel:`DirectX`, :guilabel:`2D`, :guilabel:`3D`, :guilabel:`geometry` etc (at the time). How games in general works. Then, I have learned more about game programming and, in the beginning, it was used the concept of :guilabel:`framework` a lot, which later, became a :guilabel:`game engine` embeding :guilabel:`LUA` script. Of course, I had (and still have) to do a lot of improvement/refactoring and also make **new features** as well! (You might find some comments or variable names in **portuguese BR** since at the time I used to program in my on language ¯\\_(ツ)\_/¯) But life is the greatest teacher and I have decided to go ahead and make **new features**, **improvements** or **refactoring** according to the demands. It means that when some work in as a new game requires some **feature** or **improvements** it is implemented. So, if you want to use it, go ahead and occasionally **new features** or **improvements** will come (¬‿¬). Which version should I get? --------------------------- I occasionally tag versions however it is generally safe and recommended to sync to the master. The library is fairly stable for :guilabel:`2D` applications and issues tend to be fixed as fast as reported/faced. Looking for binary? ------------------- Here the latest binaries for :ref:`Windows `. Here the latest binaries for :ref:`Android `. For :ref:`Linux ` you must compile by yourself. For :ref:`MacOs ` you must compile by yourself. For :ref:`iOS ` you must compile by yourself. .. _lib_versions: Main Libraries And Status ------------------------- +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | Library | Version | Windows | Linux | Android | macOS | iOS | Required | Status | +========================================================================+============+==============+===============+==============+==================+===================+=============+=============+ | `OpenGL ES `__ | 2.0 | YES | YES | YES | NO | NO | YES | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `DirectX 9 `__ | 9.0 | YES | NO | NO | NO | NO | Windows | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `Metal `__ | - | NO | NO | NO | YES | YES | macOS/iOS | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `LUA `__ | 5.4.1 | YES | YES | YES | YES | YES | NO | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `LodePNG `__ | 20151024 | YES | YES | YES | YES | YES | YES | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `Box 2D physics `__ | 2.4.1 | YES | YES | YES | YES | YES | NO | Stable | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | | `Liquidfun `__ | | 1.1.0 | YES | YES | YES | YES | YES * | NO | Stable | | | `Box 2D physics `__ | | 2.3.0 | | | | | | | | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `Bullet 3D physics `__ | 2.84 | YES | YES | YES | YES | YES | NO | in Progress | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `LuaSQLite 3 `__ | 0.9.5 | YES | YES | YES | YES | YES | NO | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `SQLite 3 `__ | 3.24 | YES | YES | YES | YES | YES | NO | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `AESCrypt `__ | 3.0.9 | YES | YES | YES | YES | YES | NO | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `PortAudio `__ | 19 | YES | YES | NO | NO | NO | Win / Linux | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `AVFoundation `__ | - | NO | NO | NO | YES | YES | macOS/iOS | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `OpenSL ES `__ | - | NO | NO | YES | NO | NO | Android | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `PlusWindows `__ |1.0 | YES | NO | NO | NO | NO | Windows | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `STB True Type `__ | 1.11 | YES | YES | YES | YES | YES | YES | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `MiniZ `__ | 1.16 | YES | YES | YES | YES | YES | YES | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `ImGui `__ | 1.92.6 | YES | YES | NO | YES | YES | NO | Stable | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ | `Audio` | - | ``PortAudio``| ``PortAudio`` | ``OpenSL`` | ``AVFoundation`` | ``AVFoundation`` | NO | Complete | +------------------------------------------------------------------------+------------+--------------+---------------+--------------+------------------+-------------------+-------------+-------------+ .. note:: * On iOS, ``box2d`` and ``box2d-liquid-fun`` cannot be used together. Pass ``-DUSE_BOX2D=0 -DUSE_BOX2D_LIQUID_FUN=1`` explicitly to use Liquidfun on iOS. :OpenGL ES: OpenGL ES is a royalty-free, cross-platform API for rendering advanced 2D and 3D graphics on embedded and mobile systems - including consoles, phones, appliances and vehicles. It consists of a well-defined subset of desktop OpenGL suitable for low-power devices, and provides a flexible and powerful interface between software and graphics acceleration hardware. Used on :guilabel:`Windows`, :guilabel:`Linux`, and :guilabel:`Android`. :DirectX 9: DirectX 9 is Microsoft's graphics API used as the default rendering backend on :guilabel:`Windows`. It provides a hardware-accelerated path without requiring additional OpenGL drivers. :Metal: Metal is Apple's high-performance graphics API, used as the only rendering backend on :guilabel:`macOS` and :guilabel:`iOS`. OpenGL ES is not available on Apple platforms. :LUA: LUA is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description. Although the main feature of this engine is to have LUA script as main way to develop, is not mandatory. You can, if you want, develop in pure C++. :LodePNG: LodePNG is a PNG image decoder and encoder, all in one, no dependency or linkage to zlib or libpng required. It's made for C (ISO C90), and has a C++ wrapper with a more convenient interface on top. :Box2D: Box2D is an open source C++ engine for simulating rigid bodies in 2D. it is available as :guilabel:`plugin`. The flag to use it in :guilabel:`Android` is ``USE_BOX2D``. :Liquidfun: Liquidfun is a 2D rigid-body and fluid simulation ``C++`` library for games based upon `Box2D `__ . This version forces to drawback Box2D to 2.3.0. The Liquidfun is under the :guilabel:`feature/liquid_fun` branch. :Bullet 3D: Bullet 3D is an open source C++ engine for simulating rigid bodies in 3D. It is available as external plugin/module however it is not ready yet :/. :LuaSQLite 3: Available as :guilabel:`plugin`, LuaSQLite 3 is a thin wrapper around the public domain :guilabel:`SQLite3` database engine. The flag to use it in :guilabel:`Android` is ``USE_LSQLITE3``. :SQLite 3: `SQLite `__ is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. It is part of the :guilabel:`lsqlite3`. :AES Crypt: AES Crypt is a file encryption API that uses standard Advanced Encryption Standard (AES) to easily and securely encrypt files. Although is not mandatory, it is implicit added to the engine. :PortAudio: `PortAudio `__ is a free, cross-platform, open-source, audio I/O library. It is the default audio backend on :guilabel:`Windows` and :guilabel:`Linux`. It supports `WAV `__ and OGG Vorbis (via ``stb_vorbis``). :AVFoundation: `AVFoundation `__ is Apple's native multimedia framework, used as the default audio backend on :guilabel:`macOS` and :guilabel:`iOS`. It supports WAV, MP3, AAC/M4A, OGG Vorbis (via stb_vorbis), AIFF, and more. :OpenSL ES: `OpenSL ES `__ is the native audio API for :guilabel:`Android`, replacing the legacy JNI audio backend. Use the flag ``-DAUDIO=opensl`` when building for Android. :PlusWindows: PlusWindows is a simple library for creating Owner-Drawn components on :guilabel:`Windows` . It is required only on :guilabel:`Windows`. :STB True Type: Do parse, decode, and rasterize characters from true type fonts. :MiniZ: Miniz is a lossless, high performance data compression library that implements the zlib (RFC 1950) and Deflate (RFC 1951) compressed data format specification standards. :ImGui: An immediate graphical user interface for C ++ with minimal dependencies. It is mainly used for editor. it is available as :guilabel:`plugin`. Supported on :guilabel:`Windows` (DirectX 9), :guilabel:`Linux` (OpenGL ES), :guilabel:`macOS`, and :guilabel:`iOS` (Metal). The flag to use it is ``-DUSE_IMGUI=1``. :Audio: Each platform uses its own native audio backend: ``PortAudio`` on :guilabel:`Windows` and :guilabel:`Linux`, ``OpenSL ES`` on :guilabel:`Android`, and ``AVFoundation`` on :guilabel:`macOS` and :guilabel:`iOS`. All backends share the same Lua API. Dependency Chart ---------------- Here a table showing the dependencies between the main modules of the engine: +-------------------+--------------------------------+ | Component | Depends On | +===================+================================+ | mini-mbm | | core_mbm | | | | lua | | | | plugin_helper | +-------------------+--------------------------------+ | core_mbm | | portaudio | | | | lodepng | +-------------------+--------------------------------+ | plugin_helper | | lua | | | | core_mbm | +-------------------+--------------------------------+ | box2d | | lua | | | | plugin_helper | +-------------------+--------------------------------+ | box2dLiquidFun | | lua | | | | plugin_helper | +-------------------+--------------------------------+ | bullet3d | | lua | | | | plugin_helper | | | | core_mbm | +-------------------+--------------------------------+ | ImGui | | lua | | | | plugin_helper | | | | core_mbm | +-------------------+--------------------------------+ | tilemap | | lua | | | | plugin_helper | | | | core_mbm | +-------------------+--------------------------------+ | lsqlite3 | | lua | | | | core_mbm | +-------------------+--------------------------------+ The following dependency is true for :guilabel:`Android` only +-------------------+--------------------------------+ | Component | Depends On | +===================+================================+ | mini-mbm | | core_mbm | | | | lua | | | | plugin_helper | | | | **box2d** | | | | **box2dLiquidFun** | | | | **bullet3d** | | | | **ImGui** | | | | **tilemap** | | | | **lsqlite3** | +-------------------+--------------------------------+ | core_mbm | | OpenSL ES | +-------------------+--------------------------------+ .. Important:: Since :guilabel:`Android 7.0`, the system prevents apps from dynamically linking against non-NDK libraries. Reference: https://developer.android.com/about/versions/nougat/android-7.0-changes.html#ndk For this reason, it is specified the dependency libraries in :guilabel:`Android` build. For example, if you want to use :guilabel:`box2d` in :guilabel:`Android` you must to include the flag ``-DUSE_BOX2D=1`` when invoking :guilabel:`Cmake`. More details in `Android dependencies `__. Games made with mbm ------------------- Here some games made using the engine: Tower defense ^^^^^^^^^^^^^ .. image:: _static/tower_defense_preview.gif :align: center .. image:: _static/google-play-badge.png :width: 210px :align: center :target: https://play.google.com/store/apps/details?id=com.mini.mbm.towerdefense .. image:: _static/badge-itch.png :width: 210px :align: center :target: https://mbm.itch.io/tower-defense-monster Space ship combat ^^^^^^^^^^^^^^^^^ .. image:: _static/space_ship_combat.png :align: center .. image:: _static/google-play-badge.png :width: 210px :align: center :target: https://play.google.com/store/apps/details?id=com.mini.mbm.spaceshipcombat :download:`download for Windows ` Puzzle from photos ^^^^^^^^^^^^^^^^^^ .. image:: _static/puzzle_from_photos.png :align: center .. image:: _static/google-play-badge.png :width: 210px :align: center :target: https://play.google.com/store/apps/details?id=com.mini.mbm.puzzlefromphotos2 *Let us know if you have some game built using the engine :)* App made with mbm ------------------- Here some APP made using the engine: Easy Contour to SVG ^^^^^^^^^^^^^^^^^^^ .. image:: _static/easy-contour-circle.gif :align: center .. image:: _static/easy-contour-Bezier.gif :align: center .. image:: _static/easy-contour-line.gif :align: center .. image:: _static/easy-contour-rectangle.gif :align: center .. image:: _static/easy-contour-usage.png :align: center .. image:: _static/easy-contour-usage-result.jpg :align: center :download:`download for Windows <_static/Easy-Contour-to-SVG.zip>` Quick start guide ----------------- .. _quick_start_guide: Here a quickly description how to build the engine selecting the environment. The engine is available for :guilabel:`Windows`, :guilabel:`Linux`, :guilabel:`Android`, :guilabel:`macOS`, and :guilabel:`iOS`. Getting the source code ^^^^^^^^^^^^^^^^^^^^^^^ Here the needed steps: :Get git: Install `git `__ and clone the project: .. prompt:: bash $ git clone https://github.com/michelmorais/mini-mbm.git :Download instead: You also can download the project: https://github.com/michelmorais/mini-mbm Build for Windows ^^^^^^^^^^^^^^^^^ The Windows build uses a pre-configured :guilabel:`Visual Studio 2022` solution — no CMake step needed. Open ``mini-mbm.sln`` and build directly. The README covers prerequisites, solution structure, and first-run setup. `Full build instructions for Windows `__ .. _binary_for_windows: Binary for Windows ^^^^^^^^^^^^^^^^^^ You can get the binaries for :guilabel:`Windows` here: :download:`download stand alone mini-mbm-release-3.6.7z `. What's in this folder? (Version 3.6) .. figure:: _static/content_of_folder_windows.png :align: center :figclass: align-center Content of :guilabel:`mini-mbm-release-3.6.7z` for :guilabel:`Windows` :download:`download stand alone mini-mbm-release-4.2.7z `. What's in this folder? (Version 4.2) .. figure:: _static/content_of_folder_windows4.2.png :align: center :figclass: align-center Content of :guilabel:`mini-mbm-release-4.2.7z` for :guilabel:`Windows` Or the Dev tool Kit for Windows :guilabel:`Windows` here: :download:`download dev kit for Windows `. .. figure:: _static/mini-mbm-dev-tool-kit.png :align: center :figclass: align-center :guilabel:`mini-mbm-dev-kit` for :guilabel:`Windows` .. _build_for_linux: Build for Linux ^^^^^^^^^^^^^^^ The Linux build uses CMake with GCC/Clang. The README covers prerequisites (including :guilabel:`cmake`, :guilabel:`build-essential`, :guilabel:`libgles2-mesa-dev`, and :guilabel:`portaudio19-dev`), cmake flags, and make commands. `Full build instructions for Linux `__ .. _build_for_macos: Build for MacOS ^^^^^^^^^^^^^^^ The :guilabel:`macOS` build uses **Metal** for rendering and **AVFoundation** for audio — no OpenGL ES, XQuartz, or Vulkan SDK needed. The README covers Xcode Command Line Tools prerequisites, cmake flags, and make commands. `Full build instructions for macOS `__ .. _build_for_ios: Build for iOS ^^^^^^^^^^^^^ The :guilabel:`iOS` build uses **Metal** for rendering and **AVFoundation** for audio. All plugins are compiled as **static libraries**. Two CMake generators are supported: ``make`` (unsigned binary, for CI) and ``-G Xcode`` (for device deployment and App Store). The README covers prerequisites, cmake flags, and signing setup. `Full build instructions for iOS `__ Build for Android ^^^^^^^^^^^^^^^^^ The :guilabel:`Android` build requires **NDK r29** and uses **OpenSL ES** for audio. Due to Android 7.0+ dynamic linking restrictions, plugins (:guilabel:`box2d`, :guilabel:`ImGui`, :guilabel:`lsqlite3`, etc.) must be declared explicitly as CMake flags. The README covers NDK setup, cmake/make commands, and Android Studio integration. `Full build instructions for Android `__ .. _binary_for_android: Binary for Android ^^^^^^^^^^^^^^^^^^ Even though you have some doubt? Here the project using **Android Studio** version **3.5.3** : :download:`Example full project here ` Or just would like to take a look on the :guilabel:`apk` generated? :download:`download example apk for Android ` Or the latest libraries to get start at :guilabel:`Android`? :download:`binary libs for Android version 3.2.a ` It contains the core of engine and :guilabel:`LUA` script support to start to develop on :guilabel:`Android`: .. figure:: _static/libs_android-1.png :align: center :figclass: align-center .. figure:: _static/libs_android-2.png :align: center :figclass: align-center .. Note:: | The needed libraries are :guilabel:`libcore_mbm.so`, :guilabel:`libmini-mbm.so`, :guilabel:`liblua-5.4.1.so` and :guilabel:`libc++_shared.so`. | The libraries like :guilabel:`ImGui.so`, :guilabel:`box2d.so`, :guilabel:`lsqlite3.so` and others are *plugins* and they are only necessary if will be used in your project. | If you wish to add any of libraries (plugins) it is necessary to compile with theirs respective ``flags``. .. Important:: Since :guilabel:`Android 7.0`, the system prevents apps from dynamically linking against non-NDK libraries. https://developer.android.com/about/versions/nougat/android-7.0-changes.html#ndk For this reason, you have to specify which libraries are you going to use together (:guilabel:`box2d`, :guilabel:`ImGui`, :guilabel:`sqlite`, etc ). We do this through the flag ``USE`` when invoking :guilabel:`Cmake`: ``-USE_LSQLITE3=1``, ``-DUSE_IMGUI=1``, ``-DUSE_BOX2D=1`` etc... On :guilabel:`Android` it is possible to list the files in the cache folder through command line using :guilabel:`adb` from folder ``~/Android/Sdk/platform-tools``: .. prompt:: bash $ ./adb exec-out run-as com.mini.mbm.yourcompany ls -R /data/data/com.mini.mbm.yourcompany More information at https://developer.android.com/studio/command-line/adb .. Warning:: known **issue**. The current implementation does not load *sound stream* from cache folder in :guilabel:`Android`. This is a **TODO**. You can leave the *sound stream* in asset folder (**NOT** inside of your database) then it will works. Command line usage ^^^^^^^^^^^^^^^^^^ Command line options: .. code-block:: php mini-mbm Version:3.1.b Usage: mini-mbm [options]... [file_name.lua] or [--scene file_name.lua]... --help display this help -w, --width set window's width -h, --height set window's height -ew,--expectedwidth set expected window's width -eh,--expectedheight set expected window's height --stretch stretch to axis ('x', 'y', or 'xy') default is 'y' --nosplash do not display logo -x, --posx set x window's position -y, --posy set y window's position -s, --scene set scene to load (e.g.: main.lua) -n, --name set window's name -a, --addpath add path to search file at run time --noborder new window without border note: to add a global variable use '='. example: 'myVarNumber=5.0' 'stringVar=someString' the variable will be stored as number when is number. otherwise the variable will be stored as string. use getGlobal function to get variable at lua script (see doc for more information) use space to separate arguments: usage example: mini-mbm --scene main.lua -w 800 -h 600 mini-mbm -s main.lua -w 800 -h 600 'myVarNumber=5.0' 'stringVar=someString' --nosplash