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 here. 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. Make sure to enable the add-on after installation.

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

Importing a model (optional)

With the s3o importer installed and enabled, you should be able to import s3o models from spring into blender by using the File->Import->s3o option. Then navigate to your model file and select it.

s3o models often come in rotated to one side, as Spring uses Y-axis-up and Blender uses Z-axis-up. You can rotate them to look right in Blender, and then when exporting them there are options to deal with this so that they export rotated correctly.

If the importer can find them, it will also import textures and the UV map along with the model. The texture files may need to be placed appropriately or in the same directory as the model file for this to work.

Importing textures

To open a texture you need to set a window to either the Image Editor or UV Editor mode, and then press the Open button in the top menu bar. This will bring up a file menu where you can select a texture to bring into Blender. Blender supports .dds textures by default, as well as most other image formats. However, spring uses textures somewhat uniquely and has two separate texture formats. The first of these, referred to as tex1 or colour texture, uses Red Green Blue (RGB) channels to store colour data, and Alpha (A) to store whether that part of the file is teamcolour or not. This means that by default a tex1 texture looks mostly blank(transparent) with some odd black bits scattered around. You can fix this in Blender by scrolling the menu bar (hold middle button with cursor on menu, drag mouse to side) all the way to the right, and clicking the little drop down which says Display Channels . By default it is set to Colour and Alpha but you should set it to Colour when working with tex1 files to ignore the alpha channel.

Tex2 files are the ones in greenyblue with bits of red. In those files the Red channel is how much that part of the texture emits light, the Green channel is how rough or smooth that part of the texture is (which determines how it reacts to light), and the Blue channel is how metallic and reflective that part of the texture is. Areas which are cyan (full green and full blue) are mirror-smooth metal, so reflect the environment perfectly. These should always have their colourspace set to non-colour data as they use each channel separately. You can find that option in the right hand popout menu when in an image editor viewing them (shortcut key N by default) under the Image tab.

You may also need or want to use Normal map textures, which are the ones that look mostly blue with some oddly coloured parts around the edges. Whenever you use these normal map textures you should always change the colourspace to non-colour data as it can cause visual errors if you do not, since it will process the channels differently in the render pipeline.

If nothing in the scene uses your texture it will be discarded from the file when you save and exit. You may click the shield icon next to the file name to prevent this, if you want to have the textures kept around even with nothing using it. As long as you've assigned the texture to a material, and the material to a model (see below) this will not be a problem, but it's useful to know this option exists and why a texture might be dropped.

Blend files do not by default contain the textures referenced in them, but you 'can' optionally pack the textures into them for easy transfer between users or computers. Explore the File->External Data menu for those options.

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 colourspace to non-colour 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.