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.

You can certainly import any old texture and work with it, but if you are importing textures already used by Spring you should know that they are somewhat unusual.

Spring 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.

Modelling for Zero-K

There are not many special considerations when modelling for Zero-K, and a general explanation of modelling and blender is too detailed to go here. However, you could consult tutorials such as Grant Abbitt's beginner series or Imphenzia's introduction and low poly modelling tutorial.

Generally, you should attempt to keep the number of triangles used in a model as low as is reasonable. That number varies depending on how frequent the unit is planned to be - a commander or other functionally unique unit would be fine with up to 30,000 triangles, but for a very spammable unit such as a flea this would be extremely excessive, as you can build a vast number of fleas. Something in the region of 500-1000 would be more appropriate, with less being ideal as long as the model still looks good.

The size of the model (or part of model) and how visible it is also has an impact on how many polygons you should be using. A large model covering a lot of screen space should use more polygons and texels than a small one or a part of the model that people rarely or never see.

Texturing for Zero-K, and Spring texture oddities

As mentioned earlier, spring uses two textures per model and cannot use multiple UV Maps, cannot use vertex colours, and cannot use additional textures other than a normal map.

The tex1 format covers the diffuse colour and whether a pixel is teamcoloured or not, wheras tex2 covers the emissivity, roughness, and metalness of the model in its RGB channels respectively.

Remember that most DDS normal maps are slightly different from typical OpenGL normal maps, and adjust appropriately as needed. Typically inverting the Red and Green channels does the trick.

If you import a texture then the importer will set up the nodes for you, however, if you are starting from scratch then you probably just want to replicate this node setup. This mostly approximates what Spring will do in-engine, giving you a workable preview in Blender when you use a lookdev(Material Preview) view mode.

There are three textures referenced here, which in this case happen to be atlas textures which can be reused for multiple models. The core_color.dds is tex1 and has colours and teamcolours - the alpha channel is split off, inverted, and used to colour the alpha areas green (you can click the green colour to replace it with any other colour, if you like).

The core_other.dds is the tex2 file, so it is split into RGB channels and each of these channels appropriately processed and connected to the relevant part of the material.

Finally the core_normals.dds contains a direct-x formatted normal map, so it is converted to an openGL format by inverting just the Green channel and is then passed through the normal calculation node to convert the image into a vector map, and then the vector map passed to the shader.

TODO: Provide a blend file here that already has this material set up, just need to plug in textures. Or just include atlas texture. Airpad_packed.blend is sadly larger than 2mb so the wiki will not host it.

Export the model to .dae format

Nowadays Spring can read .dae (Collada) files directly via the use of Assimp (Asset Importer). This means the export process is reasonably simple.

Either clean your scene of everything you do not want to be exported, or select only the things you want exported. Go to the File->Export menu and select Collada (.dae) format. A file browser will open with various export settings on the right hand side.

You should pick Selection Only from the Main tab of export options if you want to limit it to selection.

Make sure that the orientation settings are correct. You want to tell the exporter what axes you've been modelling with, not the axes you're looking for. These are the default options and should usually be right, Spring/Assimp will then adjust them for use in engine, but if after checking things in Spring your object is oriented wrongly, you can try adjusting these and exporting again. If all else fails, you can parent the root object(s) to an empty placed at the origin and rotate that.

A note on animation

Although Collada (.dae) files do support exporting animation, you should not do this as Spring cannot read the animation data. Instead, animations in Zero-K are handled by a lua animation script known as LUS.

Although you cannot export the animations to Collada, you can still do your animations in Blender and use the Blender2Lus export script linked earlier to export a starting animation script. It has several limitations, such as only exporting the active action from each object in the scene, but running it several times and tweaking and combining the generated scripts can reduce the amount of work in generating animation scripts immensely. Further use of this script is, for the moment, outside the scope of this tutorial (because I haven't done it myself yet - feel free to replace this with detailed explanation if you have, though!)

Set up texture associations and .dae.lua metadata

Although Spring can read .dae files and the contained UV map, it does not support any sort of material or texture import, so you have to specify these manually. Since at this point you have already set Blender up with a reasonable approximation of the texture process it should not be especially difficult.

You will need to provide a .dae.lua file with the same name as your model file, in the same directory, to tell Spring which texture files and associated data to use with the model.

For example, if your model export is snazzyUnit.dae and it is present under the /objects3d folder of your testing mod, you should make a snazzyUnit.dae.lua file and place that at /objects3d/snazzyUnit.dae.lua .

The documentation for these metadata files is here, but they are reasonably simple and a minimal example file is provided below:

return {
	tex1 = "core_color.dds",
	tex2 = "core_other.dds",
	invertteamcolor = false
}

Obviously if you are not using the atlas textures you will need to replace those names with the actual texture files you intend to use. There are several other things that may need to be in this file, but as these differ per-unit you will need to decide what, if anything, to provide. You should probably also decide on a radius to set - leaving it out autogenerates a large radius covering the entire model, but for many reasons it's not always appropriate. Examine similar units in game (ctrl-alt-B shows collision bounds, radius is the grey sphere) and match them if necessary.

Set up Zero-K mod that contains and uses your files

To get Zero-K to see your files and locally test your units (new or otherwise) you can use a mod, or download all the source and point your original version at it. I will use a mod.

This is selectable in local skirmish mode (and theoretically you can distribute them to test in multiplayer) which allows you to check everything works in the engine without requiring any changes to the official repositories or a local development copy of the game - all you need is a working copy of Zero-K. You should eventually check it works with a properly set up dev copy (and that copy can be used for many changes, if necessary) but for now a mod is simpler.

Making the mod

Inside the Zero-K folder there is a games subfolder. Inside that are numerous things, but if you make a new subfolder with a name ending in .sdd it will be read by the engine on startup. A base mod is available to download [File:BaseMod.sdd.zip here] to build from if you would like an example. More details on mod creation can be found here: Mod Creation

Create a mod and fill out the modinfo.lua, making sure to change the name and description so you can tell it apart when you are selecting it. If the depends tag is listed as [[rapid:/zk:stable]] you will have to manually change it to the latest ZK version in this format:

depend = {
		[[Zero-K v1.8.10.0]]
	},

Update the version number appropriately.

File locations

Like many mods, the file structure downwards from the modname.sdd folder should exactly match the Zero-K internal virtual file system, and if there are any files in your mod that match names with base files, Zero-K will use your mod's file instead of the base file.

This allows you to selectively replace any files with whatever changed version you want, which is ideal for our purposes of testing a mod. Any new files will also be loaded, allowing you to test entirely new units - although you may have to modify the buildoptions list of an existing factory or constructor to allow them to build your new unit.

AN IMPORTANT NOTE: You should keep all of filenames and folder names lower case, as the virtual file system lowercases everything. Double check your filenames, it needs to match exactly if you are replacing things.

Testing your mod

Once you have filled out your folders and files, probably (but not exclusively) using /objects3d , /units and /unittextures , you can progress to actually testing it works in-engine.

Load up Zero-K and go to singleplayer, then Skirmish. The map and opponents do not especially matter, though if you are testing a lot you probably want to use an inactive AI (check through main lobby options for additional AI types if it's not there by default).

Go into Adv Options, and pick 'Select Mod'. If the folder and modinfo are correct you should see your mod on the list. If you do not, download the base mod, unzip it to the appropriate place and check if that shows up - if it does, the problem is with your mod. If it does not, then something is probably in the wrong place.

Once you've selected your mod you should start the skirmish and attempt to test whatever you've actually changed. At one point while doing this, Zero-K would not load because the interpreter for the mod's unitdef files was more strict than the main game's, so you may wish to follow the format used in the base mod (it overwrites lotus turrets) more exactly if you have this problem.

Fix whatever isn't right

Do not expect everything to be perfect. This is a very complicated process and something is probably broken somewhere - either way, check everything, and get used to the idea that you may have to edit, re-export, then restart the game a lot to retry with changes quite often. Although unit definitions and such may be reloaded without quitting the game (TODO: what is the command to do this? How reliable is it?) you should eventually restart Zero-K to do a round of final testing just to ensure that everything loads correctly from startup.

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 takes to fade out of existence
buildingGroundDecalSizeX      = 12, --Size of the decal's X axis in footprint units 
buildingGroundDecalSizeY      = 12, --Size of the decal's 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.

unitpic

Unit pictures in the buildmenu are generated by an automated script. This script lives as a Lua gadget within the Zero-K base content, so if you have your mod working you can load that up and generate a buildpic.

First, press F8 to show the debug console, then turn on cheats with /cheat (or !cheats in multiplayer, which will require host permissions.)

Then run

/luarules buildicon {unitname}

. You can run it with no unit name and instead buildicons if you want to generate buildicons for every unit in the game. It should output the icons to your Zero-K folder under the /buildicons folder. You will then have to move it to the /unitpics folder of your mod, name it appropriately, and check it works.

Developer mode test with full file system

Now is the time to test against the full developer mode run - see Developing for information on how to set that up. Copy your files to an up to date copy of the latest source files from GitHub and check if they work there.

Once they do you should be ready to make a pull request. If you forked from the development version as the linked instructions suggest, you should be able to use your fork to do this.