ASE File Format

The ASE file format, short for Wikipedia logo ASCII Scene Exporter, is the prefered format to import static meshes into UnrealEd from anything except Lightwave. The format is native to 3D Studio Max, but ActorX for Maya can also export it. The format is based on identifiers, all in the form *ASTERISK_THEN_NAME, which are followed by zero or more values, and then for a few a block of further identifiers surrounded by curly braces. As there is no official specification, it is unknown whether there is differentiation of whitespace, but for UnrealEd, each identifier must start on its own line, preceded only by spaces, tabs and closing curly braces.

Top Level Identifiers

*3DSMAX_ASCIIEXPORT version: ignored by UnrealEd. indicates the version of the file. typical value for 'version' seems to be 200.
*COMMENT "comment": ignored by UnrealEd. Contains version of the exporter and export date in files generated by 3D Studio Max. Presumably could contain anything you want and might occur in any block.
*SCENE: ignored by UnrealEd. Block contains information about the scene, animation, ambient light, background color. See Scene Identifiers.
*MATERIAL_LIST: Block contains all materials used by the objects in this file. See Material List Identifiers.
*GEOMOBJECT: Block contains actual geometry of objects in the file. See Geometry Object Identifiers.
*LIGHTOBJECT & *CAMERAOBJECT: ignored by UnrealEd. Blocks contain information about lights and cameras in the scene. They're pretty straightforwards and not at all relevant to UnrealEd, so I'm not covering them.

Scene Identifiers

*SCENE_FILENAME "filename": ignored by UnrealEd. Orignal .max file name that this ASE was generated from
*SCENE_FIRSTFRAME frame: ignored by UnrealEd. Unknown, presumed to be frame on which animation begins.
*SCENE_LASTFRAME frame: ignored by UnrealEd. Unknown, presumed to be frame on which animation ends.
*SCENE_FRAMESPEED frames_per_second: ignored by UnrealEd. Unknown, presumed to be frame rate for scene (whether it's rendered or keyed frame rate is unknown).
*SCENE_TICKSPERFRAME frame: ignored by UnrealEd. Unknown.
*SCENE_BACKGROUND_STATIC red green blue: ignored by UnrealEd. Unknown, presumed to be background color. The three variables are floats between 0.0 and 1.0.
*SCENE_AMBIENT_STATIC red green blue: ignored by UnrealEd. Ambient light color and brightness. The three variables are floats between 0.0 and 1.0.

Material List Identifiers

*MATERIAL_COUNT num: Must be first identifier in *MATERIAL_LIST. num is the number of materials contained in the *MATERIAL_LIST block.
*MATERIAL index: Block contains specification of a material. index is the index of the material, counting from zero. UnrealEd ignores the index and assigns material indices starting from zero in the order they occur in the file. See Material Identifiers. Unlike the previous block identifiers, UnrealEd needs to see this one to function properly.

Material Identifiers

*MATERIAL_NAME "name": Name of the material. UnrealEd may look for a texture by this name, but it has not been tested.
*MATERIAL_CLASS "class": ignored by UnrealEd. Unknown. Usually "Standard", but "Multi/Sub-Object" has been observed.
*MATERIAL_AMBIENT red green blue: Ambient glow of this material. It is unknown if this adds to or overrides *SCENE_AMBIENT_STATIC. UnrealEd appears to interpret this identifier, but it is unknown what it does with it. The three variables are floats between 0.0 and 1.0.
*MATERIAL_DIFFUSE red green blue: Diffuse color material. UnrealEd appears to interpret this identifier, but it is unknown what it does with it. The three variables are floats between 0.0 and 1.0.
*MATERIAL_SPECULAR red green blue: Specular highlight color material. UnrealEd appears to interpret this identifier, but it is unknown what it does with it. The three variables are floats between 0.0 and 1.0.
*MATERIAL_SHINE shine: ignored by UnrealEd. Defines how focused the Specular shine is.
*MATERIAL_SHINESTRENGTH strength: ignored by UnrealEd. Unknown.
*MATERIAL_TRANSPARENCY transparency: ignored by UnrealEd. Unknown, presumed to be transparency of the material represented as a float from 0 to 1.
*MATERIAL_WIRESIZE size: ignored by UnrealEd. Unknown, presumed to be the pixel width that wires should draw as when viewed as wire frame.

Now, if the material has submaterials, you'll have this:

*NUMSUBMTLS num: Number of sub-materials for this material;
*SUBMATERIAL index: Block containing a complete material definition. indexes start at 0 and count up to NUMSUBMTLS-1. This block contains a complete material definition, but may not contain submaterials.

If the material is regular (no submaterials, you'll have this the rest of this stuff:

*MATERIAL_SHADING mode: ignored by UnrealEd. Shading algorithm to use. Observed values are Blinn and Phong. Note that this value is not quoted.
*MATERIAL_XP_FALLOFF falloff: ignored by UnrealEd. Unknown, presumed to be exponential falloff of something related to lighting. Float.
*MATERIAL_SELFILLUM illum: ignored by UnrealEd. Unknown, presumed to be some sort of ambient glow. Float.
*MATERIAL_FALLOFF falloff: ignored by UnrealEd. Unknown. Only observed value is "In" (whout quotes).
*MATERIAL_XP_TYPE type: ignored by UnrealEd. Unknown. Only observed value is "Filter" (whout quotes).
*MAP_DIFFUSE: Block containing a texture map specification for the diffuse channel. See Map Identifiers.

There may be other MAP types (for example MAP_AMBIENT, MAP_OPACITY or MAP_SPECULAR) but I don't know of them.

Map Identifiers

*MAP_NAME "name": ignored by UnrealEd. Unknown, presumed to be the name of this texture map for display in the editor.
*MAP_CLASS "class": ignored by UnrealEd. Unknown. Observed value is "Bitmap".
*MAP_SUBNO subno: ignored by UnrealEd. Unknown. Observed value is 1.
*MAP_AMOUNT 1.0000: ignored by UnrealEd. Unknown, presumed to be
*BITMAP "path": UNREALED USES THIS ONE!. It appears to be a path to a BMP file. I'm not sure if UnrealEd will add the texture or what, but this identifier appears in UnrealEd's strings.
*MAP_TYPE type: ignored by UnrealEd. Unknown. Observed value is "Screen" (without quotes).
*UVW_U_OFFSET value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_V_OFFSET value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_U_TILING value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_V_TILING value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_ANGLE value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_BLUR value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_BLUR_OFFSET value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_NOUSE_AMT value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_NOISE_SIZE value: ignored by UnrealEd. Unknown. Value is a float.
*UVW_NOISE_LEVEL level: ignored by UnrealEd. Unknown. Observed value is 1.
*UVW_NOISE_PHASE value: ignored by UnrealEd. Unknown. Value is a float.
*BITMAP_FILTER filter: ignored by UnrealEd. Unknown, presumed to be filter for generating [MIP Maps]?. Only observed value is "Pyramidal" (without the quotes).

Geometry Object Identifiers

*NODE_NAME "name": ignored by UnrealEd. Name of this object.
*NODE_TM: Block containing information about the transformation matrix on this object. Like the outer blocks, UnrealEd doesn't care about seeing this identifier, just the ones that are supposed to be inside it. See Node Transformation Matrix Identifiers.
*MESH: Block containing the actual mesh and texturing info. Like the outer blocks, UnrealEd doesn't care about seeing this identifier, just the ones that are supposed to be inside it. See Mesh Identifiers.
*PROP_MOTIONBLUR bool: ignored by UnrealEd. Unknown, presumed to indicate that this object should be motion blurred if 1, and not if 0.
*PROP_CASTSHADOW bool: ignored by UnrealEd. Unknown, presumed to indicate that this object should cast shadows if 1, and not if 0.
*PROP_RECVSHADOW bool: ignored by UnrealEd. Unknown, presumed to indicate that this object should receive shadows if 1, and not if 0.
*TM_ANIMATION: Block containing information about the transformation of the animation. I don't understand this block. (Different Editor: I understand this block, however, I have lost my example ASE files and have forgotten the identifiers for within this block. There's a section at the bottom of the page allocating space for when I get my hands on another animated ASE file.)
*MATERIAL_REF index: Index of the texture to use for this object. Default for faces without a *MESH_MTLID.

Node Transformation Matrix Identifiers

*NODE_NAME "name": Should be same name as the containing *GEOM_OBJECT.
*INHERIT_POS int int int: ignored by UnrealEd. Unknown.
*INHERIT_ROT int int int: ignored by UnrealEd. Unknown.
*INHERIT_SCL int int int: ignored by UnrealEd. Unknown.
*TM_ROW0 float float float: First row of the transformation matrix.
*TM_ROW1 float float float: Second row of the transformation matrix.
*TM_ROW2 float float float: Third row of the transformation matrix.
*TM_ROW3 float float float: Fourth row of the transformation matrix.
*TM_POS float float float: ignored by UnrealEd. The translation part of the transformation. It's here just for convenience, as the information is also in the matrix.
*TM_ROTAXIS float float float: ignored by UnrealEd. Axis of the rotation part of the transformacion. Also extracted from the matrix, it's not really needed if you already use the full matrix.
*TM_ROTANGLE float: ignored by UnrealEd. Angle of rotation part of the transformation.
*TM_SCALE float float float: ignored by UnrealEd. Scale of the transformation. Also from the matrix.
*TM_SCALEAXIS float float float: ignored by UnrealEd. The axis of the scaling. Not sure how to use it, but the information is also on the matrix.
*TM_SCALEAXISANG float: ignored by UnrealEd. Angle of the scaling.. Ditto.

Mesh Identifiers

*TIMEVALUE int: ignored by UnrealEd. Represents the frame of animation for which this mesh represents (This generally means there are more *MESH declarations within the *GEOMOBJECT block to represent the vertex positions in different frames).
*MESH_NUMVERTEX num: Number of vertices used in the model. Vertex indices range from 0 to num-1.
*MESH_VERTEX_LIST: Block containing vertex positions. UnrealEd doesn't care about this identifier, just the ones inside of it. See Mesh Geometry Specification.
*MESH_NUMFACES num: Number of faces used in the model. Face indices range from 0 to num-1.
*MESH_FACE_LIST: Block containing face definitions. Again, UnrealEd only care about the identifiers inside. See Mesh Geometry Specification.
*MESH_NUMTVERTEX num: Number of vertices used in the first UV set of the model. Texture vertex indices range from 0 to num-1.
*MESH_TVERTLIST: Block containing texture vertex positions for the first UV set. Just like the others UnrealEd doesn't actually need to see this identifier. See Mesh Texture Specification.
*MESH_NUMTVFACES num: Number of texture faces used in the first UV set of model. Should always be identical to *MESH_NUMFACES.
*MESH_TFACELIST: Block containing texture face definitions for the first UV set. Do I need to say it again?
*MESH_MAPPINGCHANNEL number: Block containing the an additional UV set. a single *MESH can conatin multiple *MESH_MAPPINGCHANNELs. Each one has a number starting at 2 and counting upwards. See Mesh Texture Specification.
*MESH_NUMCVERTEX num: Number of color vertices. Usually same as *MESH_NUMVERTEX.
*MESH_CVERTLIST: Block containing vertex color information. See Mesh Color Specification.
*MESH_NUMCVFACES num: Number of color faces. Should always be identical to *MESH_NUMFACES.
*MESH_CFACELIST: Block containing color face definitions. See Mesh Color Specification.
*MESH_NORMALS: Ignored by UnrealEd??? Block containing normal information for faces and vertices. See Mesh Normal Specification.

At this level the consistency of the file format breaks down, so will my consistency of presentation.

Mesh Geometry Specification

A Mesh is made up of a set of triangles built by selecting 3 vertices. the "front" of this triangle is the side that when viewed from causes the vertices to rotate in a counter-clockwise direction around the middle. The mesh is specified by listing all the verticies, and then listing polygons that use them. The vertices are specified as follows:

 *MESH_NUMVERTEX 4
 *MESH_VERTEX_LIST {
     *MESH_VERTEX  0  -128.0  -128.0  0.000 
     *MESH_VERTEX  1   128.0  -128.0  0.000
     *MESH_VERTEX  2   128.0   128.0  0.000
     *MESH_VERTEX  3  -128.0   128.0  0.000
 }

Each *MESH_VERTEX line contains 4 numbes, which are the vertex's index followed by it's X, Y, and Z coordinates. The vertex indices start at 0 and count upwards to one less than the value in MESH_NUMVERTEX. Once the vertices are specified, the faces are defined like this:

 *MESH_NUMTVFACES 2 
 *MESH_TFACELIST { 
     *MESH_FACE 0: A: 3 B: 0 C: 2 AB: 1 BC: 0 CA: 1 *MESH_SMOOTHING 1 *MESH_MTLID 0 
     *MESH_FACE 1: A: 1 B: 2 C: 0 AB: 1 BC: 0 CA: 1 *MESH_SMOOTHING 1 *MESH_MTLID 0 
 }

Here the format takes a complete departure from everywhere else. Suddenly the values get labeled? The first number is the face index, starting at 0 just like all the other indices. the A, B and C numbers are the vertex indices of the three corners of the triangle, in counter-clockwise order. the AB, BC, and CA are ignored by UnrealEd, but it's believed that they determine whether the edge should be drawn when viewed as wire frame. It gets stranger still as two identifiers show up on the same line as the *MESH_FACE. *MESH_SMOOTHING determines which smoothing groups the triangle is a member of and is a comma-delimited list. *MESH_MTLID specifies which submaterial to use for this triangle.

Mesh Texture Coordinate Specification

Once the geometry is in place, we can paint pretty pictures on it. The texture coordinate specification is identical to the vertex coordinate specification:

 *MESH_NUMTVERTEX 4
 *MESH_TVERTLIST {
     *MESH_TVERT 0  0.000  0.000  0.500
     *MESH_TVERT 1  1.000  0.000  0.500
     *MESH_TVERT 2  1.000  1.000  0.500
     *MESH_TVERT 3  0.000  1.000  0.500
 }

The last value is some sort of 3rd texture coordinate. It's not clear how or even if it's used. Once the coordinates are defined, you can apply the coordinates to the polygons:

 *MESH_NUMTVFACES 2
 *MESH_TFACELIST {
     *MESH_TFACE 0  3  0  2
     *MESH_TFACE 1  1  2  0
 }

The first number of each *MESH_TFACE selects a face to apply a texture to. The three numbers after that select coordinates from the *MESH_TVERTLIST to use for each of the three corners o the triangle.

Additional texture coordinate sets can be specified like this:

 *MESH_MAPPINGCHANNEL 2 {
     *MESH_NUMTVERTEX 4 
     *MESH_TVERTLIST { ... } 
     *MESH_NUMTVFACES 2 
     *MESH_TFACELIST { ... } 
 }

The only thing new here is the *MESH_MAPPINGCHANNEL block, which contains another copy of the texturing info with different values. The number after *MESH_MAPPINGCHANNEL seems to start at 2 for the 2nd set (the first one is outside any *MESH_MAPPINGCHANNEL), and count upwards for each additional set.

Mesh Vertex Color Specification

Now, it seems UnrealEd supports this. It shouldn't be able to, but it does. Nowhere in the binary do the strings identifying color information occur, yet it does seems to be able to extract it. Can either use this color information as lighting, or use the red channel to blend between two textures. Anyway, on with the specification.

Colors are specified in a similar way to geometry and textures. First a block of vertex data:

 *MESH_NUMCVERTEX 4
 *MESH_CVERTLIST {
     *MESH_VERTCOL 0 1.0000 0.0000 0.0000
     *MESH_VERTCOL 1 0.0000 1.0000 0.0000
     *MESH_VERTCOL 2 0.0000 0.0000 1.0000
     *MESH_VERTCOL 3 1.0000 1.0000 1.0000
 }

the first value is the color vertex index, the other three are the red green and blue of that vertex, from 0 to 1. Then just like textures, they're mapped onto polygons:

 *MESH_NUMCVFACES 2
 *MESH_CFACELIST {
     *MESH_CFACE 0  3  0  2
     *MESH_CFACE 1  1  2  0
 }

Mesh Vertex Normal Specification

Yet another bizarre twist here: two types of identifiers show up inside the MESH_NORMALS list. The first one is *MESH_FACENORMAL, which is followed by a face index and then three float values which are the normalized (length 1) normal for that vertex. the *MESH_FACENORMAL may be followed by exactly 3 *MESH_VERTEXNORMAL commands which are again followed by the vertex index (from *MESH_VERTEX_LIST) and three floats that form the normal for that corner of the triangle. I haven't checked if UnrealEd will let you specify different normals for the same vertex index, but my initial guess is no.

Node Animation Specifiers

More to come...

Well, that's all I know. There's still one identifier that shows up in UnrealEd's strings that I don't know about: *NUMSUBMTLS. I'm guessing this has something to do with materials. I also don't know how vertex colors are specified. I know the internal format supports them, as CTF-Magma makes use of vertex colors to blend between textures, but I don't know how to get the into UnrealEd.

Lots of info on the UnrealEd side of things, and a sample ASE file can be found at the udncontent logo VertexBlendingTutorial.

Category Modeling

Tarquin: You mean Category Application? but this is a file format, not an app! *confused*

inio: I'm blind :-) . yeah, relevancy is questionable. Maybe there should be a tools coding category or something, for stuff like this. I've come across a couple pages that seemed targeted more at people writing tools than people creating content.

Tarquin: interesting idea. Suggest it on the main categories page. in the meantime, link this page from file format if not already.

Tarquin: Is there a way to export ASE files from UnrealEd?

Anonymous: the AB,BC,CA are Edge flags. see glEdgeFlag.

Anonymous: most engines ignore the vertex normals, they are not guaranteed to be orthonormal in the ASE format. This is done by regenerating the normals at each vertex per face, averaging them togethor to get the normal. Assuming the engine even uses the normals.