Blender To Zero-K

Here is a tutorial covering all of the steps to make or edit a model in Blender (a free 3d modelling program) and transfer it to the Spring engine, then have Zero-K load it as a mutator so you can test it in-game.

The contents page here will also act as a quick reference for all of the necessary steps, in order:

Make or Edit the model in Blender

Setting up Blender for use in Zero-K

If you are totally new to blender there are a few things you probably ought to do to set up blender for use with Zero-K. Additionally, this tutorial will assume you are using left-click to select (the new default) and a fairly typical window layout similar to the default.

Blender comes with several add-ons and scripts, not all of which are enabled by default. While there are many additional ones you might have to pay for that could prove useful (meshmachine, decalmachine and hard ops are probably the most well known three) there are a few free add-ons you may wish to consider. You should absolutely go to the Edit->Preferences->Add-ons submenu and enable Node Wrangler, and Looptools.

To import s3o models from spring, you will need an addon which can be found [1]. You need to download the python (.py) file and then use the Install button inside blender's add-ons submenu, pointing it at that .py file, so that blender knows how to import .s3o models.

If you want to export animations, you will also need [2] animation exporter, though the output it produces will likely still require manual adjustment and will not be covered by this tutorial.

The other bits

Ever heard about software development that first you need to complete 90% of the project, and then you need to complete the other 90% of the project? The same sometimes applies to modding.

Even though by this point you should have your unit or building in game and working, there are other things to do before it's ready!

groundplane decal and ao bake

If your unit is a building, you will need to create a ground plane to go underneath it - at the very least an ambient occlusion baked shadow, usually referred to as an aoplane. This is simply a texture which is sized appropriately for your model and is placed underneath it by the engine. This adds a little soft shadowing around the edge of the building which helps immensely to integrate it with the map.

There are a few ways to make these, but the easiest if following this tutorial is probably just to bake your own in Blender.

Create and size the virtual ground plane

First, create a plane and place it under your model. It should be at zero relative to where the model is going to go, but this plane will never leave blender directly - it will be the Spring engine painting the decal onto the terrain. Scale it until it completely covers all of your model, then apply the scale and scale it *again* so that it is appropriately larger than the footprint of your model. This size may need adjusting so that it fits an integer value - for example, if the unitdef lists your unit as 5 footprint-units wide, then (since you can only set the decal footprint size to an integer) you would have to choose 6 (6/5 = 120% of the model size) or 7 (7/5 = 140% of the model size). Somewhere between 120% and 140% is probably fine.

Setup for AO Baking

Once you have the plane appropriately sized, go to the render tab and change the Render engine to Cycles. You may wish to change the feature set and compute device appropriate to your system (especially if you have a powerful GPU) but the defaults should be fine for this.

Make sure you set the number of samples in the Sampling section high enough. 512 is a good number to start from, though as high as 1024 is useful to reduce noise. More samples mean more render time, even for something as simple as baking a simple ambient occlusion map.

Next, go to the world tab and activate Ambient Occlusion. Factor should be 1.0, and the distance parameter depends on how large your model is. You may have to tweak this value until the resulting bake looks correct, but start with a distance parameter somewhere around 25% to 50% of the width of your model, turning it up if this is not sufficient.

To properly bake, we need somewhere to put the texture - so open up a shader node window somewhere, select the ground plane and make sure that it is using a new material and that material is using nodes. Connect a texture node using the Ctrl-T shortcut. Press New to make a new texture, and set it to the appropriate size - typically 512px square for something the size of a factory or 128px square for smaller buildings. Set the image colorspace to non-color data to prevent shading artefacts later. Make sure this texture node has been clicked on and is selected, because it's the last selected texture for each relevant object that receives the bake.

Finally we're almost ready to do the baking! Return to the render tab and scroll down to the Bake section. From the Bake Type dropdown select Ambient Occlusion. Make sure that Selected to Active is OFF, as that is intended to transfer high poly modelling data to low poly objects and we actually do want just a general scene-wide bake of ambient occlusion, it's just we only care about the result on this one ground plane object. Margin can be adjusted but the default of 16px is probably fine.

Do the bake

Press Bake!

If blender crashed that's fine, go check in the log file to see what did it - the last time I had a crash here, I had an addon (bezier tools, totally unrelated to anything to do with baking) going wrong, and so I had to temporarily disable it.

If all went well, you should have seen a few textures render if you were on something with a texture view, and if you go to find your new ambient occlusion texture it should be a black outline in the shape of your building with a white outside, and a blurry shadowy bit around the edge of the black outline, which is what the game will draw onto the ground. Export this as a png.

Touchup and adjust format in external image editor

The next bit you will need to do in GIMP/Glimpse, or any other image processing software capable of exporting DDS textures. Simply load your image file, turn the white colour into transparency by whatever method you prefer such that full black is opaque and full white is transparent, and then export as DDS. Spring wants textures to be DXT5 compressed, with mipmaps generated.

If you want some other decal underneath your unit, perhaps a metallic decal if it is a factory for example, you can add that as another layer in your image editing software here. Ensure that the ambient occlusion layer overlays it where necessary.

Adjust unitdef to include groundplane

Now you've got a groundplane texture, rename it to something like unitname_aoplane.dds and put it into the /unittextures folder. Then go to the unitdef and make sure that these tags are filled out:

buildingGroundDecalDecaySpeed = 30, --Seconds decal fades in or out of existence?
buildingGroundDecalSizeX      = 12, --Size of decal X axis in footprint units 
buildingGroundDecalSizeY      = 12, --Size of decal Y axis in footprint units 
buildingGroundDecalType       = [[unitname_aoplane.dds]], --filename of decal

useBuildingGroundDecal        = true,

After saving the updated unitdef, go and check that the ground plane exists in game. They can be quite subtle, but by toggling on and off the "show ground decals" option, you should be able to see the difference easily.

If needed, you can edit your original png file in the image editor again and apply gaussian blur to the image to spread the shadow out further. Ensure that the shadow's edge doesn't touch the edge of the image, as this tends to look obvious.