About

This is a part of my Audiosurf 2 scripting documentation.

Contents

Basics

Blender (www.blender.org) is a free open-source 3D graphics design program. It can be used for many things but in our case we want to use it to create a model for use in Audiosurf 2 skins and mods. As far as I know, it is the most feature-complete free 3D modeler available. Another relatively powerful free modeler is Wings 3D. Common commercial alternatives are 3ds Max, Lightwave, Maya, and ZBrush.

This article will explain how to get models from Blender into Audiosurf 2. Actually learning to make something in Blender is outside the scope of this article. If you don't know how to use Blender, there are many resources out there to help you learn it. The resource you should choose depends on how much you already know about 3D graphics and your preferences. The official Blender tutorials page is here. There are many other good resources on other sites and there are several books as well. A 3D modeling class, if available to you, might not teach you Blender specifically but many of the things you learn there can be applied to Blender. Blender is an intimidating program but it is possible to produce simple models with only basic knowledge about how to use it. Just be careful not to make a model with a million polygons.

An important thing to understand about Blender and most 3D modeling programs is they aren't specifically designed to make models for video games. Many of them, including Blender, focus on "rendering" capabilities for producing photorealistic images or videos from your models. Many 3D modeler features cannot survive the conversion process needed to load the model into a game. Features like shaders, materials, animations, and lighting typically cannot be converted or can only be partially converted with some extra work. In some cases Blender lacks simple functionality that would make producing game models much easier. Blender also has "game creation" tools, but they are used for Blender's own game engine and generally should be ignored. Keep this in mind when you look at Blender documentation and tutorials. Also, be aware of the version of Blender you are using. For example, Blender 2.6 had a big facelift and made the old "Doc:2.4" pages useless.

• model
• mesh
• Meshes in Audiosurf 2
• Blender Reference Manual

Exporting from Blender

To create an OBJ file of your model, go to File -> Export -> Wavefront (.obj). On the left there are some settings that change how the model is exported. The official documentation for OBJ export is here. You should read the "Export Options" section before reading the rest of this.

Selection Only

Useful if you want to make a scene around your object to preview how it will look in-game. If you don't want to export hidden objects you can do a "select all" before exporting and use this.

Animation

Might be useful when making models for mesh morphing.

Apply Modifiers

If you don't know what modifiers are then you haven't used any and this setting doesn't concern you.

Include Edges

Only matters if you have edges that aren't part of a face. In that case you should usually leave this off. AS2 will ignore the two-point faces this generates.

Smooth Groups, Bitflag Smooth Groups

Pretty sure AS2 doesn't support reading this. Include normals instead.

Include Normals

If you leave this off, AS2 can still automatically generate normals. I'm not sure if normal generation is faster or slower than parsing them from the obj file. Smoothing groups will influence the normals that Blender exports so you should turn this on when using them. Warning: AS2 normal options have misleading names like "recalculateNormals". What they actually do is enable or disable normals. Normals in the file are ignored when it's turned off and loaded or calculated when it's turned on.

Include UVs

AS2 supports OBJ files without UVs so you can turn this off if using a shader that doesn't need them.

Write Materials

This is mandatory. You can delete the MTL file afterward but AS2's OBJ reader will crash if the OBJ doesn't contain any material settings.

If you leave it off then AS2 will completely fail to load the model and this message will appear on-screen:

failed:example.obj. check output_log.txt for details

In the log file you will see the same message and this will be above it:

Argument is out of range.
Parameter name: index

Triangulate Faces

AS2 can only load faces with 3 or 4 points. All others will be ignored. This probably bloats the file size so I only turn it on when the model looks wrong without it. If you want to avoid this setting and your model is mostly triangles and quads you might consider manually splitting the unsupported faces.

Leaving this off can generate the following messages in output_log.txt:

At least one object uses quads...automatic triangle conversion is being used, which may not produce best results
Polygons which are not quads or triangles have been skipped

Write Nurbs

Yeah keep this turned off.

Polygroups, Objects as OBJ Objects/Groups, Material Groups

You can switch these off unless you're doing multiple materials or want to make it easier for other people to import your OBJ files back into Blender. By default AS2 combines the groups/objects into a single model.

Keep Vertex Order

Consistent vertex order is needed for mesh morphing and for modifying the model via BuildMesh.

Exporting Sub-Meshes

• sub-mesh
• Sub-Meshes in Audiosurf 2

In the OBJ exporter, these are options that control how groups are created:

Objects as OBJ Groups

Each blender object goes into its own group. This is the most straightforward way of creating groups. By joining and splitting objects you can get exact control over how groups are made without having to mess with Blender materials.

Objects as OBJ Objects

This is like the above, but puts them in "objects" instead. It overrides the above setting, completely replacing the group definitions with object definitions. I think AS2 will treat objects the same as groups but I suggest leaving this off to keep things simple. I haven't tested how it interacts with the other export options.

Material Groups

Groups individual faces based on what material is assigned to them in Blender. According to my tests, each Blender object gets its own set of unique material groups even if two objects are using the same material and "Objects as OBJ Groups" is disabled. If you're trying to consolidate groups across multiple Blender objects this option won't work for you. On the other hand, if you want to keep everything inside of a single Blender object then this is the ideal option for you. This option still works when "Write Materials" is disabled.

Polygroups

Groups faces based on the vertex groups its vertices are in. It "guesses" in cases where not all of the face's vertices are in the same group. I haven't tested this option.

Here is an example scene with multiple materials set up:

Exporting with "Objects as OBJ Groups" creates these groups in this order:

• objectB_meshB (6 faces)
• objectA_meshA (6 faces)

Exporting with "Material Groups":

• objectB_meshB_materialB (6 faces)
• objectA_meshA_materialA (5 faces)
• objectA_meshA_materialB_a (1 face)

Vertex Colors

OBJ files can't contain vertex colors but the script can add some by loading it with BuildMesh then calling BuildMesh a second time with the colortable setting included. colortable, unfortunately, is simply a flat list of colors that matches up with the order vertices are specified in the OBJ file. Writing them all into the script by hand would be tedious, but might be feasible in some scenarios:

cube_mesh = BuildMesh{mesh="cube.obj"}

BuildMesh{
	mesh = cube_mesh,
	colortable = {
		{1,1,1},
		{1,1,0},
		{1,0,0},
		{0,0,0},
		{0,0,1},
		{0,1,1},
	},
}

CreateObject{
	name="colorful cube",
	railoffset=0,
	floatonwaterwaves = false,
	gameobject={
		mesh=cube_mesh,
		shader="VertexColorUnlitTinted",
	}
}

Another possibility is exporting to OBJ and also to an alternative format like Stanford .PLY or Collada .DAE which supports vertex colors, then gathering all the colors from the file's source code using regular expressions.