.ASS File Specifications

The .ass file format holds an intermediate version of a Halo 2 map that is on its way from a modeling program into Halo 2 Architect. Data stored in .ass files are not directly readable by the Halo 2 engine: A compilation step run by Halo 2 Tool is required to convert the map to engine-ready binary BSP data.

Intermediate map files are always expected to be in a specific location (the \data\scenarios\multi\[levelname]\structure\ directory in the main Halo 2 Architect directory for proper processing by Tool.

File Structure

The .ass file format is ASCII-based, meaning that the intermediate level data are stored within a plain text file. Internally, each file is broken down into discrete sections that are usually identified by commented headings. Individual data values within a section are separated simply by white space and line breaks. No sections are optional; all sections must be present even if they only carry a value of 0.

The structure of an .ass file is broken down into the following major sections.

File Header: Supplies version compliance and map creator information.

Materials: Declares references to Halo 2 texture mapping assets.

Objects: Defines the building blocks used to construct the level.

Object Instances: Describes the level by positioning instances of the defined objects.

The following data types and their syntaxes are defined for .ass files.

 

Numbers that specify dimensions or positions in space will be scaled when compiled for the game engine, with 100 units in an .ass file equal to 1 Halo World Unit (10 feet in the real world). For reference, the Master Chief is slightly shorter than 100 units in an .ass file. The .ass file format uses the MAX coordinate system, where the x axis points forward, the y axis points left, and the z axis points up.

File Header

The file header section contains details that are helpful for understanding how to interpret the contents of the file.  In the event of a problem, the file header also contains useful information for tracking down the author and equipment used to generate the file.

Example File Header

 

 

File Header Data Value Details

ASS File Version:Revision number of the .ass file format specification used by this file. Halo 2 maps always obey revision 2.

Software Package:Name of the software packages used to export the file. All versions of 3ds Max are identified by the sting literal gMAXh, for example.

Exporter Version:Version of the exporter used to generate the file.

Author Name: Account name of the user who exported the level.

Host Name: Computer name used to export the level.

Materials

Materials describe the look and behavior of geometry in the Halo 2 game engine. An .ass file is not responsible for fleshing out the details of these materials. Instead, it merely provides the names of materials and shaders referenced by the level geometry that the game engine will later use to link to the proper texture maps and other resources.

Material Header and Its Data Value Details

;### MATERIALS ###                        gMaterialsh Section Heading 1                                                Material Count

Material Count: States the number of materials that will be defined following this header. Materials are numbered starting with 0 and continue to (Material Count – 1).

Material Definition and Its Data Value Details

;MATERIAL 0 "zanzibar basic_concrete"                Shader Name ""                                                Material Name

Shader Name: Name of the Halo 2 shader tag (minus the file extension) the engine will reference to define this material.

Material Name: Name of the material to reference within the shader. For most materials, the Shader Name is sufficient and this value is ignored. This value is usually left as an empty string.

Objects

The actual vertices and triangles of a level are defined in discrete building-block pieces called objects. Later in the file, instances of these objects are arranged to form the final geometry of the level.

Object Header and Its Data Value Details

;### OBJECTS ### 4                                                Object Count

Object Count: States the number of objects that will be defined following this header. Objects are numbered starting with 0 and continue to (Object Count – 1). Object order can be any assortment of the types listed below.

Sphere Object Definition and Its Data Value Details

;OBJECT 0 "SPHERE"                                        Object Type ""                                                XRef File ""                                                XRef Object -1                                                Material Index 25.000                                        Sphere Radius

Object Type: Identifies the object's type. Always set to gSPHEREh for a sphere primitive.

XRef File: If this object is a temporary stand-in that will be replaced by an object defined elsewhere, this value contains the path and name of the containing file. Usually this is just a blank string, meaning the object stands on its own and will appear as defined in the current file. This feature is specific to 3ds Max, as Halo 2 Tool requires .max files present to work. When using exporters for other programs, define all of their objects within the .ass file and set this value to a blank string.

XRef Object: If the object is a placeholder, this value contains the XRef File name of the object that will replace it. If it's not a placeholder, this is a blank string. This feature is specific to 3ds Max, as Halo 2 Tool requires .max files present to work. When using exporters for other programs, define all of their objects within the .ass file and set this value to a blank string.

Material Index: Assigns a material to the object with the corresponding number in the material header (see the Materials section). A value of 0 references the first defined material, 1 the second defined material, and so on. The scene root indexes a special material value of –1.

Sphere Radius: Establishes the size of the sphere by defining its radius.

Box Object Definition and Its Data Value Details

;OBJECT 1 "BOX"                                                Object Type ""                                                XRef File ""                                                XRef Object 0                                                Material Index 12.500        12.500        12.500        Box Extents

Object Type: Identifies the object's type. Always set to gBOXh for a box primitive.

XRef File: If this object is a temporary stand-in that will be replaced by an object defined elsewhere, this value contains the path and name of the containing file. Usually this is just a blank string, meaning the object stands on its own and will appear as defined in the current file. This feature is specific to 3ds Max as Halo 2 Tool requires .max files present to work. When using exporters for other programs, define all of their objects within the .ass file and set this value to a blank string.

XRef Object: If the object is a placeholder, this value contains the XRef File name of the object that will replace it. If it's not a placeholder, this is a blank string. This feature is specific to 3ds Max, as Halo 2 Tool requires .max files present to work.  When using exporters for other programs, define all of their objects within the .ass file and set this value to a blank string.

Material Index: Assigns a material to the object with the corresponding number in the material header (see the Materials section). A value of 0 references the first defined material, 1 the second defined material, and so on. The scene root indexes a special material value of –1.

Box Extents: Defines the length, width, and height of the box relative to its center. Each extent is one-half of its measured size, so a box with a length of 10, width of 20, and height of 30 would have extents of 5, 10, and 15, respectively.

Pill Object Definition and Its Data Value Details

;OBJECT 2 "PILL"                                        Object Type ""                                        XRef File ""                                        XRef Object 0                                        Material Index 200.000                                Pill Height 50.000                                        Pill Radius

Object Type: Identifies the object's type. Always set to gPILLh for a pill primitive.

XRef File: If this object is a temporary stand-in that will be replaced by an object defined elsewhere, this value contains the path and name of the containing file.  Usually this is just a blank string, meaning the object stands on its own and will appear as defined in the current file.  This feature is specific to 3D Studio MAX as Halo 2 Tool requires .max files present to work.  When using exporters for other programs, define all of their objects within the .ass file and set this value to a blank string.

XRef Object: If the object is a placeholder, this value contains the XRef File name of the object that will replace it. If it's not a placeholder, this is a blank string. This feature is specific to 3ds Max as Halo 2 Tools requires .max files present to work. When using exporters for other programs, define all of their objects within the .ass file and set this value to a blank string.

Material Index: Assigns a material to the object with the corresponding number in the material heading (see the Materials section). A value of 0 references the first defined material, 1 the second defined material, and so on. The scene root indexes a special material value of –1.

Pill Height: The full height of the pill shape.

Pill Radius: The thickness of the pill shape and rounding on the ends.

Mesh Object Definition and Data Value Details

Due to its complexity, the syntax for defining mesh objects is broken down into three sections in this document. Most of the specifications appear immediately below. Detailed explanations of the triangle and vertex definitions are split off into separate blocks that follow.

;OBJECT 3 "MESH"                                                    Object Type ""                                                XRef File ""                                                XRef Object 24                                                Vertex Count [Vertex Definitions] 12                                                Triangle Count [Triangle Definitions]

Object Type: Identifies the object's type. Always set to gMESHh for a mesh object.

XRef File: If this object is a temporary stand-in that will be replaced by an object defined elsewhere, this value contains the path and name of the containing file. Usually this is just a blank string, meaning the object stands on its own and will appear as defined in the current file. This feature is specific to 3ds Max as Halo 2 Tool requires .max files present to work.  When using exporters for other programs, define all of their objects within the .ass file and set this value to a blank string.

XRef Object: If the object is a placeholder, this value contains the XRef File name of the object that will replace it. If it's not a placeholder, this is a blank string. This feature is specific to 3ds Max as Halo 2 Tool requires .max files present to work. When using exporters for other programs, define all of their objects within the .ass file and set this value to a blank string.

Vertex Count: Number of vertices defined in the mesh. Because Halo 2 meshes support smoothing groups by splitting vertices along group boundaries and assigning the resulting vertex pairs differing normals, mesh objects in an .ass file may contain more vertices than the corresponding source mesh.

Triangle Count: Number of triangles defined for the mesh.

Vertex Definition and Its Data Value Details

-500.000        500.000        0.000                Vertex Position 0.000                0.000                1.000                Vertex Normal 1                                                Bone Influence Count 2        1.000                                        Bone Weight [...] 1                                                UV Count 1.000                1.000                                UV Coordinates [...]

Vertex Position: The x, y, and z coordinates of the vertex defined in the object's local space.

Vertex Normal:The x, y, and z components of a vector that defines the vertex normal in the object's local space. This vector should be normalized.

Bone Influence Count: The number of bone nodes that have influence over this vertex.

Bone Weight: A pair of values that identifies both the index of the Object acting as a deforming bone for this vertex and the amount of influence it carries for deforming the vertex's position and normal.  Repeats for Bone Influence Count number of bone and weight pairs.

UV Count: The number of texture mapping coordinate pairs defined for this vertex.

UV Coordinates: The U and V texturing coordinates for this vertex. Repeats for UV Count number of coordinate pairs.

Triangle Definition and Its Data Value Details

0                                                Material Index 0                                                Vertex Index #1 1                                                Vertex Index #2 2                                                Vertex Index #3

Material Index: Assigns a material to the triangle face with the corresponding number in the materials header (see the Materials section). A value of 0 references the first defined material, 1 the second defined material, and so on.

Vertex Index #1: Number of the vertex corresponding to the first point of the triangle.

Vertex Index #2: Number of the vertex corresponding to the second point of the triangle.

Vertex Index #3: Number of the vertex corresponding to the third point of the triangle.

Object Instances

Object instances take references to objects defined earlier in the file and give them unique positions and orientations around the world, building up a complex level from fundamental pieces. A single object may be referenced by multiple object instances, each uniquely positioned and oriented. These instances are preserved through to the Halo 2 game engine and, with proper level design, result in a much lower memory footprint for the level than if they were stored as an exhaustive list of triangles and vertices.

All levels define a special gScene Rooth node as the first object instance, which serves to give special context to the hierarchy of nodes that follows. The scene root instance node has the same value in every level and is presented in detail for reference in this document after the general Object Instance description.

Object Instance Header and Its Data Value Details

;### INSTANCES ### 2                                                Object Instance Count

Object Instance Count: States the number of object instances that will be defined following this header, including the scene root node. Object instances are numbered starting with 0 and continue to (Object Instance Count – 1).

Object Instance Definition and Its Data Value Details

;INSTANCE 1 0                                                Object Index "b_LevelFrame"                                Object Instance Name 0                                                Unique Instance ID 0                                                Parent Instance Index 0                                                Inheritance Flag 0.000        0.000        0.000        1.000                        Local Rotation 0.000        40.000 0.000                        Local Translation 1.000                                                Local Scale 0.000        0.000        0.000        1.000                        Pivot Point Rotation 0.000        0.000        0.000                                Pivot Point Translation 1.000                                                Pivot Point Scale 2                                                Object Bone Index [...]

Object Index: Assigns an object to the object instance with the corresponding number in the objects section. A value of 0 references the first defined object, 1 the second defined object, and so on. The scene root node indexes a special object value of –1.

Object Instance Name: The name of the object instance. This value usually matches the name of objects within the originating level design software. The scene root node always carries a name of gScene Rooth.

Unique Instance ID: An identifier handle number for the object instance. Every object instance must have a number that is unique to it within the scope of the .ass file. The scene root's Unique Instance ID is always –1.

Parent Instance Index: Identifies the object instance as the hierarchal child of the object instance numbered correspondingly to this value. The scene root has no parent and indexes a special object instance value of –1.

Inheritance Flag: Currently unsupported and always set to 0 for all object instances.

Local Rotation: The rotation component of the object instance's local transformation matrix relative to its parent node. This value is stored in a quaternion. The scene root node always has a rotation quaternion of 0.0, 0.0, 0.0, 1.0.

Local Translation: The x, y, and z translation component of the object instance's local transformation matrix, relative to its parent node. The scene root node always uses a 0 vector for translation.

Local Scale: The scale component of the object instance's local transformation matrix, relative to its parent node. Only uniform scaling is supported in this revision of the .ass file format. The scene root node always has a scaling factor of 1.0.

Pivot Point Rotation: The rotation component of an offset transformation matrix, relative to its pivot point. This value is stored in a quaternion. If the pivot point is the center of the object, this value is 0.0, 0.0, 0.0, 1.0. The scene root node always has a rotation quaternion of 0.0, 0.0, 0.0, 1.0.

Pivot Point Translation: The x, y, and z translation component of an offset transformation matrix, relative to its pivot point. If the pivot point is the center of the object, this value is a 0 vector. The scene root node always uses a 0 vector for translation.

Pivot Point Scale: The scale component of an offset transformation matrix, relative to its pivot point. Only uniform scaling is supported in this revision of the .ass file format. If the pivot point is the center of the object, this value is 1.0. The scene root node always has a scaling factor of 1.0.

Object Bone Index: Identifies an object used as a bone by the vertices in the instance's referenced object. It repeats to list all the objects influencing the instance's object as a bone. If no bones are influencing the object, this section is skipped. The scene root defines no bones and skips this section.

Scene Root Object Instance

;INSTANCE 0 -1                                                Object Reference "Scene Root"                                Instance Name -1                                                Unique Instance ID -1                                                Parent Instance 0                                                Inheritance Flag 0.000        0.000        0.000        1.000                        Local Rotation 0.000        0.000        0.000                                Local Position 1.000                                                Local Scale 0.000        0.000        0.000        1.000                        Pivot Point Rotation 0.000        0.000        0.000                                Pivot Point Translation 1.000                                                Pivot Point Scale