Jump to Content
Loading...
Grit Game Engine Wiki
for users / artists / developers
Log in
ยป
Username:
Password:
CapsLock is on.
Register
I forgot my password
History: TCOL
View page
Source of version: 1
(current)
The TCOL file contains enough information to simulate the physics of a object. Without a TCOL file the object will not be 'solid'. It will neither cause nor experience collisions. Each file contains information about a single physical object. The file is case-sensitive ASCII text, with c-style comments and white space (tabs/spaces/ends of line). However the first 7 bytes/characters of the file must be 'TCOL1.0'. All units are SI units (metres, kilograms, seconds, etc). !Example This is a bowling pin. It is an interesting example because of the way the complex shape is approximated with a few basic primitives. Many examples can be found in the common directory, just search for '*.tcol'. ~pp~ TCOL1.0 attributes { mass 30; angular_sleep_threshold 0.1; linear_sleep_threshold 0.1; ccd_motion_threshold 0.31; ccd_swept_sphere_radius 0; } compound { // head sphere { material "/common/PolishedWood"; centre 0 0 .88; radius 0.16; } // neck to waist cone { material "/common/PolishedWood"; centre 0 0 0.435; radius 0.27; height 0.83; } // waist sphere { material "/common/PolishedWood"; centre 0 0 0; radius 0.31; } // bottom cylinder { material "/common/PolishedWood"; centre 0 0 -0.315; dimensions 0.38 0.38 0.63; } } ~/pp~ !Body Attributes At the top of the file is a list of attributes that describe the object as a whole. !!Required Attributes Choose __one__ only. ~pp~ static; mass x; ~/pp~ If static the mesh will not move but will collide and prevent other objects from penetrating it. If static is not given, the object will move according to collisions and dynamics. However you must give the mass of the object (in Kilograms). !!Optional Attributes ~pp~ inertia x y z; ~/pp~ x y and z are the inertia values. By default the inertia is calculated automatically. This is pretty good but if you want to override it, you can set the inertia around each of the local coordinate axes. ~pp~ linear_damping x; ~/pp~ Where x is the proportion of speed lost per second. This is a model of drag. Defaults to __0.5__. If you want your object to have a terminal velocity of __v__ then set this to 9.8/v*2. This can be used to prevent small falling objects from 'tunnelling' through the floor by limiting their speed. ~pp~ angular_damping x; ~/pp~ Where x is the proportion of rotational speed lost per second. Defaults to __0.5__ . This can be used to avoid jitter and the stop the continual rotation of airborne objects. !!!Performance Optimisations In order to avoid wasting CPU cycles simulating objects that are stationary, when objects stop moving they are eliminated from the simulation until a collision occurs. Both linear and angular velocity must drop below these values in order for an object to enter this 'sleeping' state. If your objects stop suddenly or hover in mid air, reduce these quantities. ~pp~ linear_sleep_threshold x; ~/pp~ Defaults to __1.0__ ~pp~ angular_sleep_threshold x; ~/pp~ Defaults to __0.8__ !!!Penetration Avoidance In a physics simulation, objects move in 'steps'. Sometimes objects are moving so fast that they travel a large distance per step. Sometimes, they travel so far that they pass through a wall and appear on the other side. This mechanism can help counter this. Do not set these unless you have the problem just described. ~pp~ ccd_motion_threshold x; ~/pp~ This is the speed above which this feature is activated. Defaults to __0.0__ which means is a special value meaning disabled. ~pp~ ccd_swept_sphere_radius x; ~/pp~ If an object is moving fast enough, a sphere is swept through the space that the object is travelling through to search for collisions that may have been missed. This is the width of that sphere. It should be a sphere that is entirely contained within the object (not poking out). Defaults to __0.0__ which means an infinitely thin ray is used. If a missed collision is found, the object is made to travel only as far as the sphere was able to reach. This means the collision is not missed. !Physical shapes To define the shape of a body, a collection of primitive shapes is used. One can use either or both of a ''trimesh'' and ''compound''. Trimeshes are excellent for static world geometry. Compounds are good for dynamic objects but trimeshes can be used too. Compounds are faster and more reliable, especially if they use the mathematical shapes rather than the more general hulls. In particular, compounds of mathematical shapes are the only way to get a nice rolling object. !!Materials Different elements of a TCOL can have different ((Physical Materials|physical materials)), that are assigned giving . The material defines physical interactions like bounciness and friction as well as graphical / sound / gameplay effects. Each triangle of a trimesh can also be assigned a particular material. Physical materials are given by name, using a quoted string. There are some predefined physical materials in /common (see /common/phys_mats.lua) and users can also define their own. If the material is not given as an absolute path (i.e. the string does not start with a forward slash) then it is a relative path that is used to find the material starting from the dir containing the tcol file. !!Margin Some primitives have a margin which defines a volume in which collisions are handled with a different algorithm that is optimised for shallow penetrations. This defaults to 0.04 (4cm) which is good enough for most objects. For some primitives, the margin grows 'outwards' actually increasing the size of the shape. For these primitives you must compensate for the margin by shrinking the primitive slightly or your objects will 'hover' above the ground. For other primitives it grows 'inwards' and thus you need not worry about it other than to make sure that it does not extend all the way through your object and out the other side! !!Quaternions Orientations are given in quaternions, there is a ((Quaternion_Primer| primer)) on quaternions for the non-mathematically inclined. !!Compounds A compound is a list of solid primitive convex shapes at given positions that are fused together to approximate a complicated shape. Each primitive must be have a material and a set of properties appropriate for its kind. Usually there will be properties for giving the size and position of the shape. !!!Sphere Spheres are defined by centre x y z and radius. They have no margin as they are mathematically trivial. !!!Box Boxes are defined by their centre and their dimensions (width/breadth/height). They can be given a quaternion orientation. Their margin grows inwards. !!!Cylinder Cylinders are defined by their centre and their dimensions (width/breadth/height). They are by default standing upright but can be given a quaternion orientation. Their margin grows inwards. !!!Cone Cones are defined by their centre, height, and radius. They stand upright if not given a quaternion orientation. Their margin grows outwards. !!!Hull A hull is the convex shape defined by a set of vertexes. Imagine the vertexes shrink-wrapped and you get the idea. Hulls are powerful because any number of them can be used to define complicated concave shapes like cars and aeroplanes. They are defined by a set of vertexes. Their margin grows outwards. To help with compensating for the outward margin, there is a property __shrink__ which will move the vertexes to compensate for the margin. Just set the shrink value to the negative value of the margin. Hulls can get slow if there are too many vertexes. !!!Plane Planes are infinite and effectively 'zone off' half of the world. They are defined by their normal and their distance from the origin. They have no margin. They are useful for cheap flat ground, and multiple planes can be used to restrict the world to a convex internal zone. !!Trimeshes Triangle meshes are specified by a list of vertexes and faces just like a graphical mesh. These triangles are infinitely thin so the mesh is not solid. The vertexes are given as a list of x y z coordinates. Then the faces are given, each face selecting 3 vertexes from the original list (numbers starting from zero) and also the material of that face. A margin can be given, which gives the 'shell' a bit of thickness. If you use a margin you should compensate for the extra volume in your modeller by pulling in the triangles along their normals by the same quantity. Margins are useful on dynamic triangle meshes but are neither necessary nor advised for static triangle meshes. Note that triangle meshes can be slow. Generally, they do not need to be very detailed and lots of small triangles can make shapes behave unrealistically when they collide. It is usually preferable to use a compound of convex hulls to define a dynamic shape and leave triangle meshes just for static shapes. ~pp~ trimesh { margin 0.1; vertexes { -690.66 345.33 0; 690.66 345.33 0; -690.66 -345.33 0; 690.66 -345.33 0; } faces { 0 2 3 0x7; 0 3 1 0x7; } } ~/pp~ !Centre of Gravity The centre of gravity is fixed at 0,0,0 in object space, which is also 0,0,0 in the graphical mesh. To change the centre of gravity one must therefore offset both the triangles in the graphics mesh, and in the physics mesh. !Formal Grammar This is the TCOL grammar in BNF form. This is useful for people writing software that can read / write TCOL files such as exporters for modellers and converters to/from other formats. Feel free to ignore this part if you are not familiar with BNF. It is a slight restriction on the actual grammar allowed by the parser, in that the order of many of the attributes is allowed to vary from the form given here. !!Key * "<THIS>" is a token * "This" is a call to a factored out structure which should also be defined in this file * "|" is the choice between several options * "[]" is an optional sequence * "{}" is a sequence that can be repeated 0 or more times !!Grammar ~pp~File ::= <TCOL> [ <ATTRIBUTES> <LBRACE> {Attribute} <RBRACE> ] ( CompoundShape [ TriMesh ] | TriMesh ) Attribute ::= <STATIC> <SEMICOLON> | <MASS> <FLOAT> <SEMICOLON> | <INERTIA> <FLOAT> <FLOAT> <FLOAT> <SEMICOLON> | <LINEAR_DAMPING> <FLOAT> <SEMICOLON> | <ANGULAR_DAMPING> <FLOAT> <SEMICOLON> | <LINEAR_SLEEP_THRESHOLD> <FLOAT> <SEMICOLON> | <ANGULAR_SLEEP_THRESHOLD> <FLOAT> <SEMICOLON> | <CCD_MOTION_THRESHOLD> <FLOAT> <SEMICOLON> | <CCD_SWEPT_SPHERE_RADIUS> <FLOAT> <SEMICOLON> CompoundShape ::= <COMPOUND> <LBRACE> { InternalShape } <RBRACE> InternalShape ::= <HULL> <LBRACE> [ Margin ] [Shrink] Material Vertexes <RBRACE> | <BOX> <LBRACE> [ Margin ] Material Centre [ Orientation ] Dimensions <RBRACE> | <CYLINDER> <LBRACE> [ Margin ] Material Centre [ Orientation ] Dimensions <RBRACE> | <CONE> <LBRACE> [ Margin ] Material Centre [ Orientation ] Radius Height <RBRACE> | <PLANE> <LBRACE> Material Normal Distance <RBRACE> | <SPHERE> <LBRACE> Material Centre Radius <SEMICOLON> <RBRACE> Margin ::= <MARGIN> <FLOAT> <SEMICOLON> Shrink ::= <SHRINK> <FLOAT> <SEMICOLON> Vertexes ::= <VERTEXES> <LBRACE> { <FLOAT> <FLOAT> <FLOAT> <SEMICOLON> } <RBRACE> Centre ::= <CENTRE> <FLOAT> <FLOAT> <FLOAT> <SEMICOLON> Orientation ::= <ORIENTATION> <FLOAT> <FLOAT> <FLOAT> <FLOAT> <SEMICOLON> Dimensions ::= <DIMENSIONS> <FLOAT> <FLOAT> <FLOAT> <SEMICOLON> Radius ::= <RADIUS> <FLOAT> <SEMICOLON> Height ::= <HEIGHT> <FLOAT> <SEMICOLON> Normal ::= <NORMAL> <FLOAT> <FLOAT> <FLOAT> <SEMICOLON> Distance ::= <DISTANCE> <FLOAT> <SEMICOLON> Material ::= <MATERIAL> <STRING> <SEMICOLON> TriMesh ::= <TRIMESH> <LBRACE> [ Margin ] Vertexes Faces <RBRACE> Faces ::= <FACES> <LBRACE> { <NATURAL> <NATURAL> <NATURAL> <STRING> <SEMICOLON> } <RBRACE>~/pp~ !!Basic Tokens * <LBRACE> <RBRACE> <SEMICOLON> are the symbols described * <FLOAT> is a floating point number * <STRING> is a quoted string, e.g. "fish fingers" * Other tokens are just the lower case version of the text in the token, e.g. <LINEAR_DAMPING> is "linear_damping" ((Category:Physics)) ((Category:File Formats)) ((Category:Mapping))
Source
History
Export
