Runtime Extensions

We recently developed an extension model for Voxel Studio and Voxel Farm in general. The idea is you should be able to come up with entirely custom procedural content without having to recompile any of the tools, and even your final EXE if you like.

You can achieve this by wrapping your custom code inside an extension. During world design time, Voxel Studio is able to load your extension and allows you to input whatever configuration parameters you have chosen for it. Then, during runtime, the same extension code runs thus guaranteeing you get the same results you saw inside Voxel Studio.

Let's follow a quick example. Imagine we have developed a small scene in Voxel Studio using the default terrain component. At this point we have interacted only with the vanilla settings, so our scene looks like this:

Note this is only terrain, it does not contain other layers like rock and tree instancing, but it should be enough for this example.

Now let's say we want to add a massive sphere somewhere in the image. While we could go in edit mode and add a sphere using a voxel brush, this would set a lot of voxels. Since we know this will be a perfect sphere we can save a lot of data if we just store the center and radius and produce the voxels on the fly. Voxel Studio does not include a layer like that out of the box, but we can create it ourselves. Here is how:

Voxel Studio in Windows OS can load extension DLLs at runtime. You can develop the DLL in any form you like as long as the few required entry-points are found. The first few are functions so Voxel Studio and Voxel Farm in general can ask the extension what parameters it wants to capture. And then there is one function that will return the voxel data for a given chunk of space.

So we create a new DLL project. Just by dumping the binary DLL in the extension folder, Voxel Studio should be able to find it and allow us to use it for a new voxel layer:

Here our extension has identified itself as "Mega Sphere". Clicking on it will add it to the list of voxel layers in the tree.

We then define four properties for the sphere: origin x, origin y, origin z and radius. Exposing property metadata is what allows Voxel Studio to create editors for the extension without really knowing what they are and how they will be used:

Now comes the real work. So far it was mostly about metadata, let's see how we get actual voxels out of the extension. It comes down to implementing a function that looks like this:

        bool getVoxels(

                char* object,

                VoxelFarm::CellId cell,

                double cellOrigin[3],

                double cellSize,

                double voxelSize,

                int blockSize,

                VoxelFarm::VoxelType* changeFlags,

                VoxelFarm::MaterialId* materials,

                VoxelFarm::Algebra::Vector* vectors,

                bool& empty)

I will not go into the implementation this time, but the overall idea is this function is expected to fill the material, vector and flag 3D buffers with voxel data. The requested region of space is defined by cellOrigin and cellSize.

Once we code this to output a sphere, we are finally able to refresh our render view and see the results:

Here you can see some spheres. The one in the last image has a 10 km radius. Naturally we could have developed a more interesting layer, for instance a meteorite impact zone or ore veins, but hopefully you get the idea.

One last thing: Using native code for extensions always brings up the issue of security. We debated this for a while when designing the system. We finally chose to use DLLs just because they allow  to run native code without penalty. You can get really close to the metal. The security aspect can be managed by certification, also by running the DLL in a lower OS integrity mode, thus restricting the kind of access it would have over the system. And of course you can always have a DLL extension you trust that acts as a wrapper for code you do not trust, but runs in Lua or some other form of application language where you are certain it can be contained.