Truck Description File

From Rigs Of Rods

Revision as of 19:29, 28 August 2006

This file is in text format. It contains all the structural, physical and visual parameters defining a truck. It is parsed by a very crude parser, so stick to the syntax, or expect crashes. Some keywords seems not logical, this is due to the fact that I did not know where I was going when I started this project. So be warned that this stuff is not foolproof. It is decomposed in sections, each section is announced by a keyword (except the title). Comments can be put anywhere by putting a ";" as the first character of the line. Node coordinates are always:

• X: front to back
• Y: bottom to top
• Z: right to left

See Truck Concepts to understand the building philosophy. I recommand the following method of construction:

• Draw the blueprint of your truck on a drawing paper. Mark the nodes, and write their number.
• Edit your truck file and put the title, globals, engine, cameras, nodes and beams section.
• Run the game to see how it goes. If you forget some beams the truck will fold on itself!
• When the chassis seems good, add wheels, suspensions, direction and test-drive
• When the truck is sound, do the bodywork and texture, and mark most beams as invisible (displaying too much beams have a large performance impact)

To see a simple truck file example, see this Step by step truck construction.

Before be start, let ask an important question: Is it a truck or is it a plane? or what makes a truck a truck and a plane a plane. Simple:

• A truck is a description file containing an engine section
• A plane is a description file containing a turboprops section

Also, notice that:

• You sould not have both an engine section and a turboprops section in the same file
• If you have neither, then you are making a load, and the file extension should be .load (see Creating a Load)
• It is legal to have a wings section on a truck (e.g. to add aerodynamic spoilers for stability).

We go thru the sections. Order is important, so stick to this order.

Title

This section is the only that is not introduced by a keyword. It is the name of the truck, and it must absolutely be the first line of the file. e.g.

My nice truck

Globals

This section defines some global parameters, in only one line containing: the global dry mass (in kg), the global cargo mass (mass of the nodes marked "l") and the name of the material that Ogre will use to texture the truck. This must coincide with the material name given in the Material File. If you don't know, or your truck is not textured yet (no submesh section) you can reuse any existing material, like tracks/semi for example.

globals
;dry mass, cargo mass, material
10000.0, 1000.0, tracks/semi

Globeams

This section is very special and should not be used for most designs. It was created to make the bridge. It allows you to alter the default mechanical and visual beam properties. The parameters are: default stress at which beams deforms (in Newtons), default stress at which beams break, default beams diameter (in meter), default beams material.

globeams
500000, 1000000, 0.5, tracks/beam

Engine

The engine section contains the engine parameters. You should not fiddle too much this. The interesting parameter is the torque (3rd one) that defines the engine power. You don't want to use this section if you want to do a plane or a load.

engine
;min rpm, max rpm, torque, differential ratio, rear gear, first, second, third, fourth, fifth, sixth...
1000.0, 1500.0,  8000.0, 2.00, 10.85,  13.86, 9.52, 6.56, 5.48, 4.58, 3.83, 3.02, 2.53, 2.08, 1.74, 1.43, 1.20, 1.00, -1.0

Cameras

This section is important. It helps to position the truck in space, by defining a local direction reference. For example this is used to measure the pitch and the roll of the truck. The three parameters are node numbers (defined in the next section). The first if the reference and may be anywhere, the second must be behind the first (if you look at the front of the truck, it is hidden behind the first), and the third must be at the left of the first (if you look to the right of the truck, it is hidden by the first)

cameras
;center,back,left
0,2,1

Nodes

With this section begins the structural description. Each line defines a node. The first parameter is the node number, and must absolutely be consecutive. The three following parameters are the x,y,z coordinates, in meter. You can attach an optional option to a node by adding a single character. Recognized options are:

• "l": this node bears a part of the cargo load
• "f": this node has extra friction with the ground (usefull for feets)
• "x": this node is the exhaust point (requires a "y" node)
• "y": exhaust reference point, this point is at the opposite of the direction of the exhaust
• "c": this node will not detect contact with ground (can be used for optimization, on inner chassis parts)
• "h": this node is a hook point (e.g. the extremity of a crane)
• "e": this node is a terrain editing point (used in the terrain editor truck)
• "b": this node is assigned an extra buoyancy force (experimental)

nodes
;id,    x,    y,    z,     options
;main chassis
  0, 0.00, 0.75, 0.66
  1, 0.00, 0.75, 1.84
  2, 0.63, 0.75, 0.66
  3, 0.63, 0.36, 0.66,l
  4, 0.63, 0.75, 1.84
  5, 0.63, 0.36, 1.84
  6, 1.48, 0.75, 0.66,l
  7, 1.48, 0.00, 0.66
  8, 1.48, 0.75, 1.84,c
  9, 1.48, 0.00, 1.84,x
 10, 2.33, 0.75, 0.66,y
 11, 2.33, 0.00, 0.66

Fixes

Fixes are nodes that are fixed in place. That means that once put in place in the terrain, they will never move, whatever happens. This is usefull to make fixed scenery elements from beams, like bridges. Just add the node number that you want to fix.

fixes
2
3
12

Beams

This section defines all the beams connecting nodes. Each line describes a beam. The two first parameters are the node number of the two connected nodes. Order has no importance. There is an optional 3rd parameter, composed of a single character. Recognized options are:

• "i": this beam is invisible. Very usefull to hide "cheating" structural beam, or to improve performances once the truck is textured.
• "r"; this beam is a rope (opposes no force to compression)

beams
0,1
2,4
3,5,i
6,8,i
7,9
10,12,i
11,13,i

Shocks

Shocks can be seen as tunable beams, usefull for suspensions. Parameters are: the two nodes connected by the shock, the spring factor (the stiffiness), the damp factor (to adjust the amount of rebound: the best value is given by 2*sqrt(suspended mass*spring)), the shortbound and the longbound factors that defines the amount of deformation the shock can support (beyond, it becomes rigid as a standard beam) when shortened and lenghtened, the last parameter is precomp, that allows to compress or depress the suspension (leave it to 1.0 for most cases). You can make the shocks stability-active with optional parameters:

• "l" to make a left-hand active shock.
• "r" to make a right-hand active shock.
• "i" to make the shock invisible (AVAILABLE FROM VERSION 0.29).

shocks
;critical damp=2*sqrt(mass*spring)
;id1, id2, spring, damp, shortbound, longbound, precomp
36,6,  500000,100000, 0.3, 0.3, 1.0
37,8,  500000,100000, 0.3, 0.3, 1.0,l
38,2,  500000,100000, 0.3, 0.3, 1.0,r

Hydros (direction)

The hydros section concerns only the direction actuactors! They are beams that changes of length depending on the direction command. The parameters are two node numbers and a lenghtening factor (negative or positive depending on wether you want to lenghten or shorten when turning left or the contrary)

hydros
43,37,-0.2
45,37,0.2
46,36,0.2
48,36,-0.2

Commands (hydros)

The commands section describes the "real" hydros, those you command with the function keys. They are like beams, but their length varies depending with the function keys you press. The parameters are the two node numbers, a speed rate (how fast the hydro will change length), the shortest length (1.0 is the startup length), the longest length (1.0 is the startup length), the number of the shortening function key and the number of the lengthtening function key (both between 1 and 12). You can have several hydro commanded with the same function keys, or any other combination. You can add the optional flag "i" to make the hydro invisible.

commands
;id1, id2, rate, short, long, keys, keyl
10,91,0.1,1.0, 7,   1, 2, i
12,93,0.1,1.0, 7,   1, 2, i
14,90,0.1,1.0, 7,   1, 2
16,92,0.1,1.0, 7,   1, 2
114,122,0.2,1.0, 19,   3, 4
115,123,0.2,1.0, 19,   3, 4
126,132,0.1,0.1, 1.0,   5, 6

Contacters

The contacters section lists the nodes that may contact with cab triangle. This concerns only contacts with other trucks or loads. You can easily omit this section at first.

contacters
34
18
20
22
24
26
28
30
32

Help

The help section gives the name material used for the help panel on the dashboard. This material must be defined elsewhere in the MaterialFile. This is optional.

help
tracks/semihelp

Ropes

Ropes are special beams that have no compression strength (they can shorten easily) but have standard extension strength, like a cable or a chain. They have also another particularity: the second node can "grab" the nearest reachable ropable node with the 'O' key. Standard use is to use a chassis node as the first node, and a "free" node as the second node (free as in not attached by any other beam). The best example of this are the chains of the multibennes truck.

ropes
;order is important: root->end
116,134
130,136
116,135
130,137

Ties

Ties are also special beams that have no compression strength (they can shorten easily) but have standard extension strength, like a cable or a chain. As the Ropes, they grab the nearest reachable ropable node with the 'O' key. But there is a twist: unlike the ropes, they disappear when not attached (because they have no extremity node at rest) and they automatically shorten until the extension forces reaches a thresold. They are very usefull to solidly strap a load to a chassis. The parameters are the number of the root node (the starting point of the beam), the maximum reach length, the rate of auto-shortening, the shortest length possible, and the last parameter... well... is probably not very usefull and should be kept as 1.0... You can make a tie invisible with the "i" option.

ties
;root, max len, rate, short, long
58, 1.5, 0.5, 0.3, 1.0
62, 1.5, 0.5, 0.3, 1.0
59, 1.5, 0.5, 0.3, 1.0
63, 1.5, 0.5, 0.3, 1.0

Ropables

This section lists the nodes that can be catched by ropes or ties. Good use is to define some ropable nodes at the front and back of the truck to allow towing the truck.

ropables
0
1

Wheels

This section is important, it defines the wheels! The order in which the wheel are declared is important: each consecutive pair of wheel is grouped into an axle. Parameters are:

• radius (in meter)
• width (in meter)
• number of rays
• the numbers of two existing nodes that defines the wheel axis (the second node must have a larger Y coordinate than the first)
• the number of a special rigidity node (see explanation about Axle Rigidity) or 9999 if it is not used
• is the wheel braked (1) or not (0)
• is the wheel propulsed (1) or not (0)
• the number of a reference arm node for this wheel. This is where reaction torque is applied to the chassis. Should be on the rotation axis of the suspension arm.
• mass of the wheel (in kg)
• spring factor of the wheel : the stiffiness of the wheel
• damp factor : the reboundiness of the wheel
• face material and band material (and no quote between them) if you don't know, use "tracks/wheelface" for the face and "tracks/wheelband1" for single wheel or "tracks/wheelband2" for dual mounted wheels.

wheels
;radius,width,numrays,node1,node2,snode,braked,propulsed, arm, mass, spring, damp, facemat bandmat
0.54, 0.40, 12, 35, 36, 9999, 1, 0, 3, 200.0, 800000.0, 4000.0, tracks/wheelface tracks/wheelband1
0.54, 0.40, 12, 37, 38, 9999, 1, 0, 5, 200.0, 800000.0, 4000.0, tracks/wheelface tracks/wheelband1
0.54, 0.80, 12, 39, 40, 41, 1, 1, 25, 400.0, 800000.0, 4000.0, tracks/wheelface tracks/wheelband2
0.54, 0.80, 12, 41, 42, -40, 1, 1, 23, 400.0, 800000.0, 4000.0, tracks/wheelface tracks/wheelband2

Cinecam

This define the position of the in-truck cam. It is a special node suspended to eight chassis nodes. The parameters are the 3 coordinates of the point and the 8 nodes numbers to which it is binded.

cinecam
;x,y,z,bindings
0.66, 2.0, 1.8, 75,76,77,78,73,74,53,54

Flares

This defines where the light flares will be. It is positionned relative to 3 nodes of the chassis. One node is the reference node, and the two others define a base (x,y). So the flare is in the plane defined by the 3 nodes, and is placed relative to the reference node by adding a fraction of the vectors ref->x and ref->y. The three first parameters are the 3 nodes numbers (rex,x,y) and the two next gives what amount of ref->x and ref->y to add to displace the flare point (these two should be logically between 0 and 1, or else that means you use the wrong base triangle and if the body flexes too much the flare will not stick to the body correctly).

flares
;ref,x,y,offsetx,offsety
51,1,79, 0.23, 0.50

Props

This allows you to "stick" any 3D mesh to a triangle of points of a truck. You can use it to stick air intakes, horns, seats, dashboard, bumbers, whatever to the truck (note that there will be no collision detection of these objects). They work the same way as the flares. It is positionned relative to 3 nodes of the chassis. One node is the reference node, and the two others define a base (x,y). So the prop is positionned relative to the plane defined by the 3 nodes, and is placed relative to the reference node by adding a fraction of the vectors ref->x and ref->y. Additionnally, you can displace the prop along the normal to the plane. The three first parameters are the 3 nodes numbers (rex,x,y) and the three next gives what amount of ref->x, ref->y and normal to add to displace the prop (the first two should be logically between 0 and 1, or else that means you use the wrong base triangle and if the body flexes too much the flare will not stick to the body correctly, the third is normalized, in meter). The next 3 parameters are rotation angles to apply to the mesh (in each 3 axis), and the last is the name of an Ogre3D mesh object. Note that meshes with the name beginning with "dashboard", "leftmirror", "rightmirror", "seat", "beacon", "pale" and "spinprop" are reserved as they employ some magic to work. The first "seat" mesh is made translucent, so it should be the driver's seat.

props
;ref,x,y,offsetx,offsety,offsetz,rotx,roty,rotz,mesh
93,95,92, 0.50, 0.37, 0.0, 90, 0, 0, airintake.mesh

Submeshes

This last part defines the most visible part of the truck: the body. It will dress the chassis with solid triangles. You must define each body panel (a continuous almost-flat section) in a different submesh section, in order to have sharp body angles, and to simplify texturing. A submesh has two subsection: the texcoords, that places nodes of the submesh on the texture image (coordinates between 0.0 and 1.0) , and then the cab subsection, that draws the triangles, with triplets of node numbers. The nodes used in the cab subsection must be present in the texcoord subsection. The order in which the three points forming the triangles is given is important, as its winding defines in which direction it will be visible. The winding must be counterclockwise to be visible (IIRC). There is an optional flag to the cab subsection: if you add "c" to the triangle, this triangle will be a contact triangle, that can contact with contacters nodes. mcreed has contributed a cool Texturing Tutorial that describes how to fill the submesh and cab parts of the truck file.

;cabin top
submesh
texcoords
75, 0.172, 0.334
76, 0.172, 0.665
77, 0.291, 0.334
78, 0.291, 0.665
cab
75,76,78
75,78,77

;cabin back
submesh
texcoords
77, 0.291, 0.334
78, 0.291, 0.665
53, 0.422, 0.334
54, 0.422, 0.665
6, 0.422, 0.334
8, 0.422, 0.665
cab
77,78,54
77,54,53
53,54,8,c
53,8,6,c

Wings

This section declares parts of the chassis as wings, and that they should bear aerodynamic forces. Each line of this section designs a wing segment, that is a homogeneous part of a wing. You can (and you should!) make a plane's wing from several contiguous wing segments.

End

The file MUST TERMINATE by end or it will crash

end