OBJ
OBJ files define geometry and are used by modders and 3D modelers because it is a decent exchange format. Most every 3D modeling application will import and/or export .obj files, or they have plugins that add the functionality.
Therefore, it is a good file format for exporting geometry data from The Sims 2 (TS2) for use and modification by modders. Currently, SimPE only exports geometry data from TS2 files in the .obj format. (The Mesh Tool can export .smd files as well.)
The full specification can very easily be found on the web by using Google, but since the geometry data within TS2 is relatively simple, the .obj files created by SimPE only use a subset of the full .obj file specification. This document will only discuss the relevant parts of the .obj specification.
The .obj format is an ASCII format, meaning that it is plain-text. It can be opened by any text editor, manually changed, and saved. However, it must always have the extension .obj, or it will not be recognized as an .obj file.
The .obj format supports polygonal objects, which use point, lines, and faces, and freeform objects, which use curves and surfaces. This document will only discuss the relevant aspects of the polygonal objects.
Contents |
File Structure
Only the data definitions in bold below are applicable to TS2 data: (Definitions in italics may be present upon export from many apps.)
Vertex data
~- geometric vertices (v): these are the point data of a mesh ~- texture vertices (vt): these are the UVW texture mapping data ~- vertex normals (vn): these are the normal data of the mesh ~- parameter space vertices (vp): not applicable to TS2 data
Free-form curve/surface attributes
~- various curve types (cstype): not applicable to TS2 data ~- degree (deg): not applicable to TS2 data ~- basis matrix (bmat): not applicable to TS2 data ~- step size (step): not applicable to TS2 data
Elements
~- face (f): these are the polygon data of a mesh ~- point (p): not applicable to TS2 data ~- line (l): not applicable to TS2 data ~- curve (curv): not applicable to TS2 data ~- 2D curve (curv2): not applicable to TS2 data ~- surface (surf): not applicable to TS2 data
Free-form curve/surface body statements
~- parameter values (parm): not applicable to TS2 data ~- outer trimming (trim): not applicable to TS2 data ~- inner trimming (hole): not applicable to TS2 data ~- special curve (scrv): not applicable to TS2 data ~- special point (sp): not applicable to TS2 data ~- end statement (end): not applicable to TS2 data
Connectivity between free-form surfaces
~- connect (con): not applicable to TS2 data
Grouping
~- group name (g): This is the name of the model, i.e., "body" ~- smoothing group (s): not applicable to TS2 data ~- merging group (mg): not applicable to TS2 data ~- object name (o): There can be multiple separate objects in an .obj file
Display/render attributes
~- bevel interpolation (bevel): not applicable to TS2 data ~- color interpolation (c_interp): not applicable to TS2 data ~- dissolve interpolation (d_interp): not applicable to TS2 data ~- level of detail (lod): not applicable to TS2 data ~- material name (usemtl): not applicable to TS2 data ~- material library (mtllib): not applicable to TS2 data ~- shadow casting (shadow_obj): not applicable to TS2 data ~- ray tracing (trace_obj): not applicable to TS2 data ~- curve approximation technique (ctech): not applicable to TS2 data ~- surface approximation technique (stech): not applicable to TS2 data
Vertex data
Vertex data provides coordinates for: ~- geometric vertices ~- texture vertices ~- vertex normals
The vertex data is represented by three vertex lists, one for each type of vertex coordinate. A right-hand coordinate system is used to specify the coordinate locations.
The following is an example of a portion of an .obj file as SimPE might produce:
# Comments are defined by the use of the 'pound' symbol. # (Extra data cut for brevity; numbers are semi-made-up.) g body # begin 1341 vertices (this is a comment, too) v 0.50230 20.0003 10.2560 v 0.10000 1.52380 0.70750 v -100.000 -1.00000 20.3201 . . . v 1.00345 99.1919 -5.55555 # end 1341 vertices # begin 1341 vertex normals vn 0 0 1 vn .573 .573 .573 vn 0 1 0 . . . vn -1 0 -1 # end 1341 vertex normals # begin 1341 texture vertices vt .10 .10 0 vt .20 .25 0 vt .70 .10 0 . . . vt .91 .99 0 # end 1341 texture vertices # begin 2084 faces f 1/1/1 2/2/2 3/3/3 f 4/4/4 1/1/1 5/5/5 f 2/2/2 6/6/6 1/1/1 . . . f 1340/1340/1340 1339/1339/1339 1341/1341/1341 # end 2084 faces
The .obj file specification states that the first vertex definition is considered to be vertex '1', the second is '2', and so on. It doesn't matter how the data is arranged. It could have the first vertex texture definition after the first vertex definition, and all definitions could be scrambled or arranged however an application prefers. The same is true for the listing of the normals and texture vertices.
Syntax
v x y z
Specifies a geometric vertex with its x y z coordinates. The coordinates are floating point numbers that define the position of the vertex in three dimensions.
vn i j k
Specifies a normal vector with components i, j, and k. i j k are floating point numbers. Essentially, the vertex data specifies the end-point of a one-unit length line where the line's starting or origin point, and the origin of the coordinate system used for the vector coordinates are both co-incident with the vertex to which the normal is assoctiated. Vertex normals affect smooth shading and rendering of geometry. For polygons, vertex normals are used in place of actual facet normals. Rendering systems can calculate vertex normals on the fly, so they are not strictly necessary for all apps or systems, but pre-existing normals can speed up rendering. For games, it is a benefit to have the normals pre-calculated and stored with the mesh data, and to also limit the normals to one per vertex. Most 3D apps use one normal per poly per vertex, so that a vertex has one normal for each poly that shares that vertex, resulting in three normals per vertex for most or all vertices in a mesh made up of only triangles. This is so that the mesh can be displayed with with or without smoothing across given faces, depending on smoothing angle. Even if the whole mesh is smoothed, most 3D applications retain the normal information and will export the full list of normals in an .obj file. This is one of the issues with compatibility between the .obj file created by a 3D application, and the mesh data that TS2 expects to see.
vt u v w
Specifies a texture vertex with coordinates u, v, and w. u v w are floating point numbers. A 2D texture mapped to a 3D surface requires both the u and v coordinates. There is such a thing as a 3D texture, and therefore texture mapping is sometimes called UVW mapping or texturing, but for most games, including TS2, only 2D or UV mapping is used. Because there are three coordinates in the specification, many 3D apps automatically export the w component, but for UV mapping, w will always be '0' in the exported .obj file. This appears to be ignored by the Mesh Tool, so it shouldn't matter.
Texture vertices map a pixel coordinate in a 2D image to a certain vertex on a certain face, or you can think in reverse and say that they map a 3D vertex in a model to a 2D location on an image. A texture vertex definition in an .obj file is simply the 2D coordinate. A face definition must provide the link between a texture vertex coordinate and the 3D vertex coordinate that should be mapped to it. So in an .obj file, all the actual mapping is done in the face definition.
Again, most 3D apps have one UV coordinate per face per vertex used by the face, resulting in three coordinates per vertex if each vertex is shared by three faces, as is the case for most or all vertices in the average triangle mesh. So the number of UV coordinates, vt, that these 3D applications export to an .obj file will usually be equal to the number of faces times the number of vertices used in each face definition. Many games, TS2 included, only use one coordinate per vertex. In TS2, sections of a model are broken up into separate meshes so that they can be layed out flat on a 2D texture. This allows the game to use only one UV coordinate per vertex, saving RAM, GPU, and CPU resources, but the model will have to be composed of separate meshes, and attention has to be paid to making certain that vertices at the boundaries of the meshes are lined-up (co-incident) with each other, and that the normals of these boundary meshes are also co-incident, or averaged together, if smooth shading across the boundary is desired. Obviously, there is an inconsistency in what most 3D applications export and what TS2 expects to see.
f v/vt/vn v/vt/vn v/vt/vn v/vt/vn ...
Specifies a face with a list of at least three vertices(v). Texture vertices (vt) and vertex normals (vn) are optional. (However, they must either be present for each vertex or absent on all vertices.) If the vt or vn assignment is absent, the slashes must still be present. A face definition ties the texture vertex and vertex normal definitions to the correct vertex definition.
Valid examples:
f 1/1/1 2/2/2 3/3/3 f 4/4/4 1/5/5 2/6/6 f 1340/6250/6250 1339/6251/6251 1341/6252/6252 1342/6253/6253 f 5'' 6'' 4'' f 7/10/ 8/11/ 6/12/
Invalid examples:
f 1/1/1 2/2/2 (not enough vertices to make a legal face) f 1''1 2/2/2 3''3 (mix of undefined ''vt'' and defined ''vt'') f 1'' 2/ 3'' (slash missing)
[To be edited:]
So then the face definitions, being all triangles in this case, have three sets of listings.
Notice that the total number of vertices, vertex normals, and texture vertices are all equal. This is due to the way TS2 stores mesh data. It doesn't use an .obj file format internally. The .obj file format is merely one of the file formats that modders can use to transfer mesh data between applications. In games such as TS2, it is usually optimal for a mesh to have one texture vertex and one vertex normal per vertex, which is why the totals of each are the same.
(This document is about 65% complete.)
