Progress Update: November 2018


Hello, November has passed and its time for another progress update!

The biggest things added this month were:

  • Decals
  • Particle system continuous emission
  • Particle system & decal documentation
  • Particle system & decals exposed to scripting

This also means all major features required for v1.1 are now implemented, and I have therefore shifted focus on bugfixing and polish. I also had more time to spend on the editor with some new additions to its inspector and script binding functionality.

Next month I’ll be focusing more on getting all the bugs ironed out, with a special focus on some lingering issues that have remained since v1.0 (such as the Mesa driver issue on Linux, and integrated GPU compatibility issues), which are the last major issues remaining.

For those interested, I’ve included a more detailed breakdown of the new additions below:


Decals are now fully implemented and available on the master branch. They can be used for projecting textures onto other surfaces, either for dynamic gameplay purposes (i.e. bullet holes, explosion marks) or for level design for adding more details to surfaces without having to create new textures.

You can add them to the scene through the CDecal component. You’ll have to orient them and set their size through CDecal::setSize(), as well as set the maximum project distance through CDecal::setMaxDistance(). You’ll also need to assign a material through CDecal::setMaterial(), for which a new builtin shader BuiltinShader::Decal is provided.

// Create the material
HShader decalShader = gBuiltinResources().getBuiltinShader(BuiltinShader::Decal);
HMaterial decalMaterial = Material::create(decalShader);

// Assign material textures
HTexture decalAlbedoTex = ...;
HTexture decalNormalTex = ...;
decalMaterial->setTexture("gAlbedoTex", decalAlbedoTex);
decalMaterial->setTexture("gNormalTex", decalNormalTex);

// Orient the decal
HSceneObject decalSO = SceneObject::create("Decal");
decalSO->setPosition(Vector3(0.0f, 6.0f, 0.0f));
decalSO->lookAt(Vector3(0.0f, 0.0f, 0.0f));

// Make the projected decal 2x2 meters
decal->setSize(Vector2(2.0f, 2.0f));

// Set the project distance to 20 centimeters

// Create the component and set the material
HDecal decal = decalSO->addComponent<CDecal>();

By default the decal shader accepts a full set of PBR textures (albedo, normal, metalness, roughness, emissive) and can project them all onto the surface, but it also has other modes which can be set through the BLEND_MODE variation parameter:

  • 0 - Transparent - This is the default mode where a full complement of PBR textures is provided and blended with the underlying surface.
  • 1 - Stain - Similar to Transparent except the albedo color is multiplied (modulated) with the underlying albedo. This makes it for suitable for stain-like decals that modify the existing color, rather than replace it.
  • 2 - Normal - Only the normal map is projected. This allows the decal to be used for effects such a footsteps in the snow.
  • 3 - Emissive - Only the emissive texture is projected. Useful for making surfaces appear as emitting light.
// Create the material
HShader decalShader = gBuiltinResources().getBuiltinShader(BuiltinShader::Decal);
HMaterial decalMaterial = Material::create(decalShader);

// Enable normal-only blend mode
        ShaderVariation::Param("BLEND_MODE", 2)

// Assign normal texture
HTexture decalNormalTex = ...;
decalMaterial->setTexture("gNormalTex", decalNormalTex);

// Apply the material

Finally, you can mask on which surfaces should the decal projects onto by setting the layer mask through CDecal::setLayerMask.

// Only project onto surfaces rendered with layers 0 to 15

// Set layer 1 on renderable (decal will project on it)
HRenderable renderable = ...;
renderable->setLayer(1 << 1)

// Set layer 20 on renderable (decal will NOT project on it)
HRenderable renderable2 = ...;
renderable2->setLayer(1 << 20)

Decal with masking

New decal manual has also been added to the documentation, which has further details.

Continous particle emission

Particle system emission was improved for systems that emit many particles quickly. The system will now calculate particle properties in a sub-frame increments ensuring all particles spawned during a single frame are distributed across the frame. This yields a continuous stream of particles rather than them clumping together at frame start.

You don’t need to do anything to enable this feature as it is always enabled. It did require a big refactor of the emission system, but this is the type of seemingly little feature that can make a big difference in effect quality, and is not properly accounted for by many open source implementations out there.

Before continuous emission

With continuous emission

Particle system documentation

Complete particle system documentation with 6 new manuals has been added. The manuals go over all the particle system properties, including both CPU and GPU simulated particles.

The documentation is not available online yet, but you can generate it manually from the Documentation folder using Doxygen. I plan on adding an automated documentation generation/upload to the build system, so there is a version that’s always up to date - if I have time I’ll do this in December.

Particles & decals exposed to scripting

Entirety of the particle system API as well as the new decal API has been exposed to scripting, and I’ve made some improvements to the script binding generation along the way to make it more expressive. This means these systems can now be used in the editor through script code, and will be available for the future C# scripting support in the framework itself.


Other smaller improvements were made:

  • Over a dozen bugfixes with a special focus on polishing Vulkan, resolving lingering issues with Linux and macOS as well as problems with integrated GPUs
  • @paolopaoletto has added a DynArray class which will slowly be replacing std::vector, and we’ll expand it with some useful functionality that will benefit both ease of use and performance
  • Improvements to the editor inspector so script-exported types can have a better-looking automatically generated inspector through user-specified properties. Once finished this will hopefully remove the need to write and maintain custom inspector code.
  • Little bit of progress on BSL 2.0. Going slowly but steadily. Still very much excited to get this implemented and to clean up and optimize the shader import pipeline, as well as start extending the language.

What’s next?

All major v1.1 features are now implemented, and I’m the process of polishing and bug-fixing, getting everything ready for release.

Before release I need to do the following:

  • Add two new example projects: Particles and Lighting & shadows
  • Resolve any existing documented issues
  • Do proper testing on all platforms, including the new examples, and resolve any found issues
  • General polish and improvements

I’m hoping to release v1.1 in early January, although I can probably squeeze it in December but this is a perfect time to do some polish before starting on the new feature set.

Post v1.1 there are three major bullet points to handle

  • C# scripting - This is a feature I’d really like to add soon as it will open up the framework to a lot of new users, plus it’s mostly implemented (it’s functional through the editor).

    Translating all the manuals is the biggest issue. I need to modify my documentation generator so it can transparently link to both C++ and C# API, handling that automatically. Also there are most certainly bits of manuals that are going to be quite different regarding native vs. script, which will need to be rewritten. Finally the examples need to be rewritten. Ideally I’d love to set up a cross-compiler that translates example code automatically, which should be a great help when I decide to add more scripting languages.

  • New editor release - Editor is mostly feature complete but needs a significant bugfixing, polish and testing pass. I’ve been constantly improving it, which also means I always break things, but I’m very happy in the direction it is going. It should provide a very solid foundation for future systems once I’m done. Right now I’m planning to releasing a new, significantly more stable version of the editor, before v1.2. Hopefully the editor foundation will then be stabilized and for v1.2 we can just expose new systems to it, without breaking core features.

  • bsf v1.2 - Last but not least, v1.2 plans to add support for networking, pathfinding and new shading models. I’m hoping it will take less time than v1.1 since in that I had to build a pretty large system from the ground up, while this update is more of an integration of existing technologies.

I’m also hoping to squeeze in BSL 2.0 and have some improvements regarding resource packing, multi-scene support and improved text support, but no guarantees on those :wink:

That’s it for now. Huge thanks to the Patreon supporters, not only do you allow me to spend more time on this project, it’s also nice to see someone who cares about it enough to support it!