minko: a C++ 3D framework that ships as an engine, a plugin set and a bag of examples

A 3D framework split into framework, plugin, template and example

minko is described as a 3D framework for web, desktop and mobile devices, written in C++. The repository layout explains what that means in practice. There is a framework directory holding the sources for the Minko framework itself, a plugin directory holding the plugin sources, a template directory with starting points for new framework, plugin or application work, and an example directory with complete applications. On top of that sits a module directory, a cmake directory, a script directory, a doc directory and a test directory, plus premake5.lua and sdk.lua at the root for alternative build description. The example list reads like a feature catalogue of the engine itself: pbr, shadow-mapping, sky-box, sprite-batch, blending, effect-config, picking, physics, joystick, keyboard, sensors, ttf, stencil, sprite and offscreen rendering each have a folder, alongside assimp, devil, html-overlay and http examples that pair with specific plugins. The point of the arrangement is that a new team starts from a template and a plugin rather than from a blank engine, and the examples double as the documentation of what the framework can already do.

The plugin list is where the feature surface lives

Minko is not one monolithic library. The plugin list given in the README names angle, assimp, bullet, debug, devil, fx, html-overlay, http-loader, http-worker, jpeg, leap, lua, oculus, offscreen, particles, png, sdl, sensors, serializer, video-camera, vr and zlib. Some of these are clear loaders and decoders, such as jpeg, png, assimp and zlib. Some are platform bridges, such as sdl for input and windowing, video-camera for capture and oculus and vr for immersive output. Some are scripting and content hooks, with lua and the http-loader and http-worker pair. Others are diagnostic or engine internals, including debug, offscreen, particles, serializer and fx. Because the build script takes a WITH_PLUGINS switch, the plugin set is part of the build configuration rather than something that is always compiled in. The architecture is the interesting part for an adopter: a Minko application is a host application plus a set of plugins, and the choice of which plugins to enable is a first class decision rather than a link time detail that nobody looks at again.

The build script is the main interface for a developer

There is no package manager entry point in the repository, so the build script is what you actually work with. The script takes a target platform and a build type, and it can be passed extra CMake arguments. The usage text in the README lists three targets, android, html5 and linux64, and two build types, debug and release, plus a single environment variable, MAKE_ARGS, whose default value is -j8.

Usage: ./script/build.sh <target> <build-type> [--cmake '<cmake-args>']

<target>      The target platform of the build. Available targets are:
                  * android
                  * html5
                  * linux64

<build-type>  The type of build to perform. Available types are:
                  * debug
                  * release

ENVIRONMENT VARIABLES
              The following environment variables can customize the build:

              MAKE_ARGS
                  Arguments to pass to the make program. Default value: -j8.

So a release build for the web target is a single command.

./script/build.sh html5 release

The matching commands exist for the other targets, using the same two argument shape, and the script supports a windows64 target as well even though the usage text above only lists three. That inconsistency between the usage block and the documented commands is minor but worth knowing, because a reader who trusts the usage text alone will think windows64 is not a target. The MAKE_ARGS default of -j8 assumes a build machine with enough cores, and on a small machine you would pass your own value rather than let the default oversubscribe.

Building on Windows means fighting for the MSBuild path

The Windows64 target is the one with a documented failure mode. The README warns that if the final command, msbuild, fails, the VCTargetsPath has to be changed and the directory containing msbuild.exe added to the PATH environment variable. The suggested path points at the Visual Studio 2017 Community installation, and the correction is a Windows environment variable assignment.

SET VCTargetsPath=C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\VC\VCTargets

This tells you two things about the project. The engine is expected to be built with a toolchain that is pinned to a specific Visual Studio generation, and the build assumes a local path layout that is unlikely to match a managed workstation exactly. Visual Studio 2017 appears in the prerequisites list next to Docker CE 17 and CMake, which is a narrow combination to reproduce today. For a team evaluating the framework, the practical question is not whether the engine can be built, it is whether your build machines can be pinned to that generation of Visual Studio, because a 2017 era toolchain in a modern CI image is the kind of dependency that quietly becomes the largest maintenance cost of a project.

Two build routes, and the older one is a private Docker registry

The README documents two eras of build process, separated by the [email protected] tag, and they differ in a way that matters for anyone outside the organisation. From 10.2.0 onwards, the build script drives the process on the host. Before that tag, the build ran inside a Docker image pulled from registry.aerys.in, with the current directory mounted into the container, the container running as the invoking user id, and CMake invoked inside with flags such as -DWITH_EXAMPLES=OFF, -DWITH_PLUGINS=ON and, for the web target, a toolchain file pointing at an Emscripten installation inside the image. The HTML5 container run looks like this.

docker run -it --rm \
   -v ${PWD}:${PWD} -w ${PWD} \
    -v /etc/group:/etc/group:ro -v /etc/passwd:/etc/passwd:ro -u $(id -u $USER):$(id -g $USER) \
   registry.aerys.in/aerys/smartshape-docker/html5:{TAG} \
    bash -c "
        mkdir -p build && cd build
        cmake .. \
            -DCMAKE_BUILD_TYPE=Release \
            -DWITH_EXAMPLES=OFF \
            -DWITH_PLUGINS=ON \
            -DCMAKE_TOOLCHAIN_FILE=/emsdk_portable/sdk/cmake/Modules/Platform/Emscripten.cmake
        make
    "

The prerequisites also say you have to be logged on to GitLab's Container Registry to pull the images, and that the repository to clone is smartshape-engine from the same private host, not the public one. So the older route is closed to outsiders, and the newer script route inherits some of that environment through its images and toolchain assumptions. This is the single biggest adoption constraint in the repository, and it is stated plainly rather than hidden, which is at least honest.

The engine is a base, not a program you run

The Run section is short and says something that explains the whole shape of the project: the engine does not have to be run, because it is used by the other parts of SmartShape as a base. There is no demo binary to launch from this repository, and no command line tool to drive. The development section adds that when you modify the engine code you have to build the engine again once your modifications are done, which is the build cost of a source distributed engine rather than a published package. For an adopter this reframes the evaluation. You are not installing a 3D library into an application, you are compiling one and then building applications on top of it, with the plugin set and the framework sources in your own tree. The template directory exists for exactly this reason, giving you a starting point for the framework, for a plugin, or for an application, so the intended path is to copy a template and build upward from there.

Licence, release history and the state of the tree

The licence field is the one to read before anything else. The repository is not covered by a standard open source identifier that GitHub can classify, and the licence text sits in LICENSE.md at the root. Anyone planning to use the framework in a commercial product has to read that file directly, because the customary shortcut of checking the licence badge tells you nothing here, and this article is not in a position to interpret the terms. On maintenance, the repository is not archived and the last push was on 2026-07-04, with the branch and file set in a state that suggests ongoing work rather than a finished snapshot. There are no GitHub releases at all, so there is no tagged version to pin, no changelog to read and no upgrade notes to weigh. The version information is instead carried in a VERSION file at the root and in the [email protected] tag referenced by the build documentation, so a team that needs reproducibility has to derive its own versioning discipline from the source tree rather than from published artefacts. The repository also carries a .gitlab-ci.yml and a .travis.yml, so continuous integration was configured at some point, and .gitmodules, which is consistent with the dependency and plugin structure described above.

Editorial conclusion

minko suits teams already building inside the SmartShape ecosystem on Android, HTML5, Linux64 or Windows64 who want a 3D engine with a plugin architecture instead of a self contained library. It is a poor fit for a web team that wants to ship a 3D scene from a browser tab, and for anyone who cannot reach the registry.aerys.in container images or a Visual Studio 2017 toolchain, since the documented build assumes both. Before you adopt it, read LICENSE.md, because the repository is not covered by a standard licence identifier, and confirm that the framework folder and the plugin sources you intend to use are present in the copy you obtain, since the engine build in the README points at a separate smartshape-engine repository.

Frequently asked questions

Official sources

1. aerys/minko on GitHub
2. Issues
3. Project website
4. README