blend2cs

About

blend2cs is a tool that converts Blender files to CrystalSpace world files. It is a stand-alone tool without dependencies on either Blender or CrystalSpace.

Download

Currently there is only a CVS version available. Have a look at the project page.

Compiling and installing

Compiling blend2cs is easy: fetch yourself a terminal, change to the directory with the sources and type "make". That should be all. It should compile out of the box on Linux and cygwin. Mingw32 probably won't do. If you want to compile on Windows, I'd suggest that you install a cygwin environment.

If all goes well you'll end up with a file called blendconv.

Running

blendconv takes 4 parameters. The first one tells blendconv what it should convert the blender file to:

The second parameter indicates the type of sector management you want to use.  Valid options are None,Scene, and Layer.  See below for descriptions of each type of sector management.

The third parameter is the filename of the input file and the fourth parameter is the output file.

What is converted?

Levels

Currently blendconv tries to convert all meshes, empties, and light sources in your file.

Meshes

The meshes are converted completely with textures and UV coordinates.  Blendconv currently supports CS "thing" meshes and "genmesh" meshes.  Just as in blender, thing meshes may have a different texture on each face.  They may also have portals.  At this time genmeshes may only have a single texture on the mesh, and no portals.

To determine the type of mesh into which a blender object will be converted, use the real-time property buttons (click on the Pac-Man looking button in Blender to get the real-time buttons).  Create a string property with the name "MeshType".  The value of that property will be the type of CS mesh into which the object is converted.  Value property values are "thing","sprite.2D","sprite.3D", and "genmesh", although currently only "thing" and "genmesh" are supported.   Alternatively the property with name "MeshType" can be an integer type with valid values 1, 2, 3, or 4 for "thing","sprite.2D","sprite.3D", and "genmesh" respectively.  If no property "MeshType" is specified, or if an invalid value is specified, the object will default to a "thing" mesh.

Lights

The light source type is not maintained because there is no such thing as directional lights in CrystalSpace. But the light source color and radius is converted.

Empties

Currently Blender empties are converted into CS nodes.  Note that at this time nodes make walktest crash.

Properties

Properties of objects (found under the real-time buttons) are converted into CS keys.  Certain property names are used as keywords by blendconv.  These include "MeshType", "RenderPriority" (currently unimplemented), "Sector", and any name beginning with "Portal".

Camera

Cameras themselves are not converted to cameras in CS, as this is more application dependent, but at this time the location of a camera will be translated into a <start> position in the CS world file.

Objects

This is not yet implemented.

Sector-Portal Management

Sectors

As CS uses sectors and portals to group data and speed drawing, multiple schemes of managing sectors are available with blendconv.  They are specified as the second argument to blendconv.  Below are the options with a short description of each.
  1. None.  With this option all objects are put into a sector named "room" unless they are explicitly specified to be in a different sector via the use of a string property with the name "Sector".   The value of that property will be the name of the sector into which the object is put.
  2. Scene.  With this option scenes become sectors.  All objects in scene X will be put into as CS sector named X.  Note if you want a sector named "room" (an oft default starting point), you need to assign the name "room" to a scene.  This is Frank's favorite scheme.
  3. Layer.  With this option every layer of every scene becomes a different sector.  An object in layer 5 of a scene named "bob" will be placed into a CS sector named "bob+Layer.5". 

Note that the existence of a string property named "Sector" will override all options and place that object into the sector whose name is the value of that property.

Portals

Portals are the mechanism that CS uses to connect one sector to another.  They are particular polygons on a mesh that lead to a specifed sector.  As portals are a per-face information, and the only specifiable information that I can find to attach to faces in blender are images, image names are used to specify portals for blendconv. 

This is a bit kludgey, but it works like this:  To make a face (or faces) on a mesh into a portal to a sector named X, uv map that face with an image whose name begins with "Portal", e.g. Portal001.jpg.  Then on that mesh create a string property whose name is the file name, e.g. Portal001.jpg, and whose value is the sector to which the portal leads, X.  The actual content of the images are unimportant.  Only the names are used to resolve the properties.  This method easily allows for multiple portals on a single mesh.  I keep a bunch of files named Portal1.png, Portal2.png, ... that are all just links to a solid blue image.

Caveats

There are several requirements a .blend file must meet so that it can be converted successfully. If the conversion fails it's likely that you don't get an appropriate error message. But the most likely reason is that of one of these requirements is not met:

Once blendconv emits better error messages it should be far easier to tell what's wrong with the input file.

Gregor Mückl
Last modified: Mon May 19 16:13:15 UTC 2003